Line Items Settings

📝
A FEW THINGS TO KNOW
1 - A line item holds promoted products to advertise on any single retailer
2 - Line items have basic settings such as start & end dates, optional budget settings & associated retailers on which ads are served
3 - Budgets may additionally be controlled at the campaign level
4 - Several reports are available to measure line item performance
5 - Campaigns are limited to 10,000 non-archived line items
6 - Line items are archived automatically 90 days after their end date

Endpoints

Verb	Endpoint	Description
GET	`/accounts/{accountId}/line-items`	Get All Line Items
GET	`/line-items/{lineItemId}`	Get a Specific Line Item

Line Item Attributes

Status actually appears to be a required parameter as not including it in LI update calls will result in a 400 error

id Required

Data Type: string

Accepted Value: int64

Write? No

Nullable? No

Description: Line Item ID

type Required

Data Type: enum

Accepted Value: auction, preferred

Write? No

Nullable? No

Description: Campaign type

campaignId Required

Data Type: string

Accepted Value: int64

Write? No

Nullable? No

Description: Campaign ID

name Required

Data Type: string

Accepted Value: 255 char limit

Write? Yes

Nullable? No

Description: Line item name; must be unique within a campaign

targetRetailerId Required

Data Type: string

Accepted Value: int64

Write? No

Nullable? No

Description: ID of the retailer the line item serves on

startDate Required

Data Type: date

Accepted Value: YYYY-MM-DD

Write? Yes

Nullable? No

Description: Line item start date in the account timeZone

endDate Optional

Data Type: date

Accepted Value: YYYY-MM-DD

Write? Yes

Nullable? Yes

Description: Line item end date in the account timeZone; serves indefinitely if omitted or set to null

budget Optional

Data Type: number

Accepted Value: at least 0

Write? No

Nullable? No

Description: Line item lifetime spend cap; uncapped if omitted or set to null

budgetSpent

Data Type: number

Accepted Value: at least 0

Write? No

Nullable? No

Description: The amount the line item has already spent

budgetRemaining

Data Type: number

Accepted Value: 0 and budget

Write? No

Nullable? Yes

Description: Amount the line item has to remain until cap is hit; null if budget is uncapped

status

Data Type: enum

Accepted Value: active, paused, scheduled, ended, budgetHit, noFunds, draft, archived

Write? Yes

Nullable? No

Description: Line item status; can only be updated by a user to active or paused; all other values are applied automatically depending on flight dates, financials, or missing attributes required for line item to serve. To understand the conditions that will cause a status to change, check out our status page

createdAt Optional

Data Type: timestamp

Accepted Value: ISO-8601

Write? No

Nullable? No

Description: Timestamp in UTC of last line item update

Get All Line Items

This endpoint lists all line items in the specified campaign. Results are paginated.

https://api.criteo.com/2022-10/retail-media/accounts/{accountId}/line-items

Sample Request

curl -X GET "https://api.criteo.com/2022-10/retail-media/accounts/123456/line-items" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

import requests

url = "https://api.criteo.com/2022-07/retail-media/accounts/4/line-items"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("text/plain");

RequestBody body = RequestBody.create(mediaType, "");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/accounts/4/line-items")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/accounts/4/line-items');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));

$request->setHeader(array(
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}

catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Sample Response

{
    "data": [
        {
            "type": "RetailMediaLineItem",
            "id": "9979917896105882144",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "Line Item 123",
                "targetRetailerId": "3239117063738827231",
                "startDate": "2020-04-06",
                "endDate": null,
                "budget": null,
                "budgetSpent": 2383.87,
                "budgetRemaining": null,
                "status": "active",
                "createdAt": "2020-04-06T17:29:11+00:00",
                "updatedAt": "2020-04-06T17:29:11+00:00"
            }
        },
 
        // ...
 
        {
            "type": "RetailMediaLineItem",
            "id": "6854840188706902009",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "Line Item 789",
                "targetRetailerId": "18159942378514859684",
                "startDate": "2020-04-08",
                "endDate": null,
                "budget": 8000.00,
                "budgetSpent": 1921.23,
                "budgetRemaining": 6078.77,
                "status": "paused",
                "createdAt": "2020-04-06T23:42:47+00:00",
                "updatedAt": "2020-06-03T03:01:52+00:00"       
            }
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 105,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 5,
        "nextPage": "https://api.criteo.com/2022-10/retail-media/accounts/123456/line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}

Get a Specific Line Item

This endpoint retrieves the specified line item

https://api.criteo.com/2022-10/retail-media/line-items/{lineItemId}

Sample Request

curl -X GET "https://api.criteo.com/2022-10/retail-media/line-item/2465695028166499188" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

import requests

url = "https://api.criteo.com/2022-07/retail-media/line-items/1232"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("text/plain");

RequestBody body = RequestBody.create(mediaType, "");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/line-items/1232")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/line-items/1232');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));

$request->setHeader(array(
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}

catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Sample Response

{
    "data": { 
        "type": "RetailMediaLineItem",
        "id": "2465695028166499188",
        "attributes": {
            "campaignId": "8343086999167541140",
            "name": "My New Line Item",
            "targetRetailerId": "18159942378514859684",
            "startDate": "2020-04-06",
            "endDate": null,
            "budget": null,
            "budgetSpent": 0.00,
            "budgetRemaining": null,
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:11:23+00:00"
        }
    }
}

Responses

Response	Description
`200`	Call completed with success
`403`	API user does not have the authorization to make requests to the account ID. For an authorization request, follow the authorization request steps
`404`	Line item ID not found

📝A FEW THINGS TO KNOW

Endpoints

Line Item Attributes

Get All Line Items

Get a Specific Line Item

Responses

📝
A FEW THINGS TO KNOW