Line Items Endpoints - Criteo Docs

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.

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	CampaignID, in which the respective line item belongs Accepted values: string of int64 Writeable? N / Nullable? N
`type`	enum	Campaigntype Accepted values:`auction`,`preferred` Writeable? Y / Nullable? N
`targetRetailerId`	string	RetailerID, 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 theAccounttimezone; used to schedule its activation and start serving ads. To understand the conditions that will cause a status to change, check outCampaign & Line Item Status Accepted values:`yyyy-mm-dd` Writeable? Y / Nullable? N
`endDate`	date	End date of the line item, in theAccounttimezone; 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`(inISO-8601) Default: if`null`or absent, balance will be available indefinitely Writeable? Y / Nullable? Y
`budget`	decimal	Line item lifetime spend cap, uncapped if omitted or set to`null` Accepted values:`budget`≥ 0.0 Default:`0.0` Writeable? Y / Nullable? Y
`budgetSpent`	decimal	Budget amount the line item has already spent Accepted values:`budgetSpent`≥ 0.0 Default:`0.0` Writeable? N / Nullable? N
`budgetRemaining`	decimal	Budget amount the line item has remaining until cap is hit;`null`if budget is uncapped Accepted 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 outCampaign & 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`(inISO-8601) Writeable? N / Nullable? N
`updatedAt`	timestamp	Timestamp of last line item update, in UTC Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm`(inISO-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 using pageIndex and pageSize query parameters; if omitted, defaults to 0 and 25, respectively. See API Response. Sample Request

curl -X GET "https://api.criteo.com/{version}/retail-media/accounts/123456/line-items?pageIndex=0&pageSize=25" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

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 Sample Request

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

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.

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.

​Endpoints

​Line Item Attributes

​Get all Line Items

​Get a specific Line Item

​Responses

Endpoints

Line Item Attributes

Get all Line Items

Get a specific Line Item

Responses