Line Items Endpoints

📝

Getting Started

  1. A line item holds promoted products to advertise on a single retailer.
  2. Line items include basic settings such as start and end dates, optional budget controls, and the associated retailer where ads are served.
  3. Budgets can also be managed at the campaign level.
  4. Several reports are available to track line item performance.
  5. Campaigns are limited to 10,000 non-archived line items.
  6. Line items are automatically archived 90 days after their end date.

Endpoints

MethodEndpointDescription
GET/accounts/{accountId}/line-itemsRetrieve all line items associated with a specific account.
GET/line-items/{lineItemId}Retrieve details of a specific line item by its ID.

Line Item Attributes

AttributeData TypeDescription
idstringLine item ID, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
namestringLine item name, must be unique within a campaign

Accepted values: up to 255-chars string
Writeable? Y / Nullable? N
campaignIdstringCampaign ID, in which the respective line item belongs

Accepted values: string of int64
Writeable? N / Nullable? N
typeenumCampaign type

Accepted values: auction, preferred
Writeable? Y / Nullable? N
targetRetailerIdstringRetailer ID, in which the respective line item serves ad on

Accepted values: string of int64
Writeable? N / Nullable? N
startDatedateStart date of the line item, in the Account timezone; used to schedule its activation and start serving ads.
To understand the conditions that will cause a status to change, check out Campaign & Line Item Status

Accepted values: yyyy-mm-dd
Writeable? Y / Nullable? N
endDatedateEnd date of the line item, in the Account timezone; serves ads indefinitely if omitted or set to null.
A timestamp can be included as well if the line item is desired to end at a certain time of day

Accepted values: yyyy-mm-ddThh:mm:ss±hh:mm (in ISO-8601 )
Default: if null or absent, balance will be available indefinitely
Writeable? Y / Nullable? Y
budgetdecimalLine item lifetime spend cap, uncapped if omitted or set to null

Accepted values: budget ≥ 0.0
Default: 0.0
Writeable? Y / Nullable? Y
budgetSpentdecimalBudget amount the line item has already spent

Accepted values: budgetSpent ≥ 0.0
Default: 0.0
Writeable? N / Nullable? N
budgetRemainingdecimalBudget amount the line item has remaining until cap is hit; null if budget is uncapped

Accepted values: 0 ≤ budgetRemainingbudget
Default: 0.0
Writeable? N / Nullable? Y
statusenumLine item status; can only be updated by a user to active or paused; all other values are applied automatically depending on financials, flight dates, or missing attributes required for line item to serve.
To understand the conditions that will cause a status to change, check out Campaign & Line Item Status

Accepted values: active, paused, scheduled, ended, budgetHit, noFunds, draft, archived
Writeable? Y / Nullable? N
createdAttimestampTimestamp of line item creation, in UTC

Accepted values: yyyy-mm-ddThh:mm:ss±hh:mm(in ISO-8601)
Writeable? N / Nullable? N
updatedAttimestampTimestamp of last line item update, in UTC

Accepted values: yyyy-mm-ddThh:mm:ss±hh:mm(in ISO-8601)
Default: same as createdAt
Writeable? N / Nullable? N

Get all Line Items

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

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

Sample Request

curl -X GET "https://api.criteo.com/{version}/retail-media/accounts/123456/line-items" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
import requests

url = "https://api.criteo.com/{version}/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/{version}/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/{version}/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/{version}/retail-media/accounts/123456/line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}

Get a specific Line Item

This endpoint retrieves details for a specified line item by its ID

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

Sample Request

curl -L -X GET "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
import requests

url = "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188"

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/{version}/retail-media/line-items/2465695028166499188")
  .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/{version}/retail-media/line-items/2465695028166499188');
$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

ResponseDescription
🟢 200Call completed successfully. The specified line item details are returned.
🔴 403API user is not authorized to make requests for the account ID. To request authorization, follow the authorization request steps.
🔴 404Line item ID not found. Ensure the lineItemId is correct and exists.