GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

Onsite Display Line Items

Suggest Edits

📝

Getting Started

1- A line item holds promoted products to advertise on any single retailer
2 - Line items have bid settings, start & end dates, and optional budgeting & pacing controls
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

VerbEndpointDescription
GET/campaigns/{campaignId}/preferred-line-itemsGet all Preferred Deals Line items from a specific Campaign
POST/campaigns/{campaignId}/preferred-line-itemsCreates a Preferred Deals Line item
GET/preferred-line-items/{lineItemId}Get a specific Preferred Deals Line item
PUT/preferred-line-items/{lineItemId}Updates a specific Preferred Deals Line item

 

📘

  • Create operations using the POST method expect every Required (R) field; omitting Optional (O) fields will set those fields to Default values
  • Update operations using the PUT method expect every Write (W) field; omitting these fields is equivalent to setting them to null, if possible

 

Line Item Attributes

id

Data Type: string

Accepted Value: int64

Read or WriteRead

Nullable? -

Description: Line item ID


campaignId Required

Data Type: string

Accepted Value: int64

Read or Write Read

Nullable? -

Description: Campaign ID


name Required

Data Type: string

Accepted Value: 255 char limit

Read or Write Write

Nullable? -

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


targetRetailerId Required

Data Type: string

Accepted Value: int64

Read or Write -

Nullable? -

Description: ID of the retailer the line item serves on


startDate Required

Data Type: date

Accepted Value: YYYY-MM-DD

Read or Write Write

Nullable? -

Description: Line item start date in the account `timeZone`


endDate Required

Data Type: date

Accepted Value: YYYY-MM-DD

Read or Write Write

Nullable? Yes

Default Value null

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


budget Required

Data Type: number

Accepted Value: at least 0

Read or Write Write

Nullable? Yes

Default Value null

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


budgetSpent

Data Type: number

Accepted Value: at least 0

Read or Write -

Nullable? -

Default Value 0.0

Description: Amount the line item has already spent


budgetRemaining

Data Type: number

Accepted Value: between 0 and `budget`

Read or Write -

Nullable? Yes

Default Value null

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


pacing Required

Data Type: enum

Accepted Value: accelerated, standard

Read or Write -

Nullable? -

Default Value -

Description: Way the budget will be spent, between the following values: accelerated (Spend as fast as possible) or standard (Spend evenly)


capping Optional

Data Type: object

Accepted Value: -

Read or Write -

Nullable? -

Default Value -

Description: Frequency capping object


capping:range Required

Data Type: number

Accepted Value: range[0,]

Read or Write -

Nullable? -

Default Value -

Description: Frequency capping number


capping:type Required

Data Type: enum

Accepted Value: day, session

Read or Write -

Nullable? -

Default Value -

Description: Frequency capping type


page

Data Type: object

Accepted Value: -

Read or Write -

Nullable? -

Default Value -

Description: -


page:pageType Required

Data Type: enum

Accepted Value: -

Read or Write -

Nullable? -

Default Value `search`, `home`, `checkout`, `category`, `productDetail`, `confirmation`, `merchandising`, `deals`

Description: Page type to serve on


page:categories Optional

Data Type: object array

Accepted Value: -

Read or Write -

Nullable? -

Default Value -

Description: Categories to serve on. Only applies to `category`, `productDetail` and `merchandising` page types


page:categories:categoryId:value

Data Type: -

Accepted Value: -

Read or Write -

Nullable? -

Default Value -

Description: -


page:categories:includeChildren:value

Data Type: -

Accepted Value: -

Read or Write -

Nullable? -

Default Value -

Description: -


page:searchKeywords Optional

Data Type: string array

Accepted Value: -

Read or Write -

Nullable? -

Default Value -

Description: Keywords to serve on. Only applies to `search` page type


creativeId Required

Data Type: string

Accepted Value: -

Read or Write -

Nullable? -

Default Value -

Description: Identifier of the creative to be served with this line item


status

Data Type: enum

Accepted Value: -

Read or Write -

Nullable? -

Default Value `active`, `paused`, `scheduled`, `ended`, `budgetHit`, `noFunds`, `draft`, `archived`

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


status

Data Type: timestamp

Accepted Value: ISO-8601

Read or Write -

Nullable? -

Default Value -

Description: Timestamp in UTC of line item creation


status

Data Type: timestamp

Accepted Value: ISO-8601

Read or Write -

Nullable? -

Default Value -

Description: Timestamp in UTC of last line item update


Create an Onsite Display Line Item

This endpoint creates a new onsite display line item in the specified campaign

https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}/preferred-line-items

 

🚧

Creative ID Association with the Line Item

When generating a new creative, the initial id is known as a "parentId," of the creative. Every new update made to that creative creates a new "childId" which is a copy of the previous creative containing new updates. This means that the creativeId will change whenever a new update is made to the creative.

To ensure that your line item is using the correct creativeId, your application will need to call the latest creativeId from the Get Creatives endpoint before associating a new creative to the line item.

 

Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/campaigns/329628911113846784/preferred-line-items' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
--data-raw '{
    "data": {
        "type": "RetailMediaPDCampaignCreation",
        "attributes": {
            "name": "API PD Campaign V4 - categories",
            "startDate": "2022-06-29",
            "endDate": "2022-06-30",
            "pacing": "standard",
            "page": {
                "pageType": "category",
                "categories": [
                    {
                        "categoryID": "3595128",
                         "includeChildren": "false"
                    }
                ]
            },
            "targetRetailerId": "299",
            "budget": "1.00",
            "status": "draft",
            "capping": {
                "type": "day",
                "count": "5"
            },
            "creativeId": "231059293677002752"
        }
    }
}'

Sample Response

{
    "data": {
        "attributes": {
            "name": "API PD Campaign V4 - categories",
            "startDate": "2022-06-29",
            "endDate": "2022-06-30",
            "status": "draft",
            "pacing": "standard",
            "capping": {
                "type": "day",
                "count": 5
            },
            "page": {
                "pageType": "category",
                "categories": [
                    {
                        "categoryId": "3595128",
                        "includeChildren": false
                    }
                ],
                "searchKeywords": null
            },
            "targetRetailerId": "299",
            "budget": 1.00000000,
            "campaignId": "329628911113846784",
            "budgetSpent": 0.00000000,
            "budgetRemaining": 1.00000000,
            "createdAt": "2022-06-29T21:01:04+00:00",
            "updatedAt": "2022-06-29T21:01:06+00:00",
            "creativeId": "231059293677002752",
            "id": "330090318158475264"
        },
        "id": "330090318158475264",
        "type": "RetailMediaPreferredLineItem"
    },
    "warnings": [],
    "errors": []
}

Get All Onsite Display Line Items

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

https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}/preferred-line-items

Sample Request

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

Sample Response

{
    "data": [
        {
            "type": "RetailMediaLineItem",
            "id": "9979917896105882144",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "My New Line Item 3",
                "targetRetailerId": "18159942378514859684",
                "startDate": "2021-07-10",
                "endDate": "2021-07-14",
                "budget": 1520.00,
                "budgetSpent": 20.00,
                "budgetRemaining": 1500.00,
                "pacing": "accelerated",
                "capping": {
                    "type": "day",
                    "count": 5
                },
                "page": {
                    "pageType": "home",
                    "categories": null,
                    "searchKeywords": null
                },
                "status": "draft",
                "createdAt": "2020-04-04T06:11:23+00:00",
                "updatedAt": "2020-04-05T06:11:23+00:00",
                "creativeId": "231059024123875072"
            }
        },
        // ...
        {
            "type": "RetailMediaLineItem",
            "id": "6854840188706902009",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "My New Line Item",
                "targetRetailerId": "18159942378514859684",
                "startDate": "2021-07-20",
                "endDate": "2021-07-21",
                "budget": 10.00,
                "budgetSpent": null,
                "budgetRemaining": null,
                "pacing": "standard",
                "capping": {
                    "type": "day",
                    "count": 5
                },
                "page": {
                    "pageType": "home",
                    "categories": null,
                    "searchKeywords": null
                },
                "status": "draft",
                "createdAt": "2020-04-06T06:11:23+00:00",
                "updatedAt": "2020-04-06T06:11:23+00:00",
                "creativeId": "231059024123875072"      
            }
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 105,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 5,
        "nextPage": "https://api.criteo.com/{version}/retail-media/campaigns/8343086999167541140/preferred-line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}

Get a Specific Onsite Display Line Item

This endpoint retrieves the specified onsite display line item.

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

Sample Request

curl -X GET "https://api.criteo.com/{version}/retail-media/preferred-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": "2021-07-20",
            "endDate": "2021-07-21",
            "budget": 10.00,
            "budgetSpent": null,
            "budgetRemaining": null,
            "pacing": "standard",
            "page": {
                "pageType": "home",
                "categories": null,
                "searchKeywords": null
            },
            "capping": {
                "type": "day",
                "count": 5
            },
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:11:23+00:00",
            "creativeId": "231059024123875072"
        }
    }
}

Update a Specific Onsite Display Line Item

This endpoint updates the specified onsite display line item. In this example, we update the pacing status from accelerated to standard. Also, note the draft state of the line item because products to be promoted have not yet been added.

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

Sample Request

curl -X PUT "https://api.criteo.com/{version}/retail-media/preferred-line-items/2465695028166499188" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaLineItem",
                "id": "2465695028166499188",
                "attributes": {
                    "name": "My New Line Item",
                    "targetRetailerId": "18159942378514859684",
                    "startDate": "2021-07-20",
                    "endDate": "2021-07-21",
                    "budget": 10.00,
                    "pacing": "standard",
                    "page": {
                        "pageType": "home",
                        "categories": null,
                        "searchKeywords": null
                    },
                    "capping": {
                         "type": "day",
                         "count": 5
                    },
                    "status": "paused",
                    "creativeId": "231059024123875072"
                }
            }
        }'

Sample Response

{
    "data": { 
        "type": "RetailMediaLineItem",
        "id": "2465695028166499188",
        "attributes": {
            "name": "My New Line Item",
            "targetRetailerId": "18159942378514859684",
            "startDate": "2021-07-20",
            "endDate": "2021-07-21",
            "budget": 10.00,
            "budgetSpent": null,
            "budgetRemaining": null,
            "page": {
                "pageType": "home",
                "categories": null,
                "searchKeywords": null
            },
            "pacing": "standard",
            "capping": {
                "type": "day",
                "count": 5
            },
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:17:48+00:00",
            "creativeId": "231059024123875072"
        }
    }
}

Responses

ResponseDescription
🔵 200Call executed with success
🔵 201Preferred deals element created with success
🔴 400Bad request validation error

Updated 5 months ago