Line Items Endpoints
Getting Started
- A line item holds promoted products to advertise on a single retailer.
- Line items include basic settings such as start and end dates, optional budget controls, and the associated retailer where ads are served.
- Budgets can also be managed at the campaign level.
- Several reports are available to track line item performance.
- Campaigns are limited to 10,000 non-archived line items.
- Line items are automatically archived 90 days after their end date.
Endpoints
Method | Endpoint | Description |
---|---|---|
GET | /accounts/{accountId}/line-items | Retrieve 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
Attribute | Data Type | Description |
---|---|---|
id | string | Line item ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
name | string | Line item name, must be unique within a campaign Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
campaignId | string | Campaign ID, in which the respective line item belongs Accepted values: string of int64 Writeable? N / Nullable? N |
type | enum | Campaign type Accepted values: auction , preferred Writeable? Y / Nullable? N |
targetRetailerId | string | Retailer ID, in which the respective line item serves ad on Accepted values: string of int64 Writeable? N / Nullable? N |
startDate | date | Start 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 |
endDate | date | End 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 indefinitelyWriteable? Y / Nullable? Y |
budget | decimal | Line item lifetime spend cap, uncapped if omitted or set to null Accepted values: budget ≥ 0.0Default: 0.0 Writeable? Y / Nullable? Y |
budgetSpent | decimal | Budget amount the line item has already spent Accepted values: budgetSpent ≥ 0.0Default: 0.0 Writeable? N / Nullable? N |
budgetRemaining | decimal | Budget amount the line item has remaining until cap is hit; null if budget is uncappedAccepted values: 0 ≤ budgetRemaining ≤ budget Default: 0.0 Writeable? N / Nullable? Y |
status | enum | Line 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 |
createdAt | timestamp | Timestamp of line item creation, in UTC Accepted values: yyyy-mm-ddThh:mm:ss±hh:mm (in ISO-8601)Writeable? N / Nullable? N |
updatedAt | timestamp | Timestamp 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
Response | Description |
---|---|
🟢 200 | Call completed successfully. The specified line item details are returned. |
🔴 403 | API user is not authorized to make requests for the account ID. To request authorization, follow the authorization request steps. |
🔴 404 | Line item ID not found. Ensure the lineItemId is correct and exists. |
Updated 4 days ago