A new unified Line Item Core endpoint is replacing the type-specific creation routes. This page remains available in the meantime.

A line item holds promoted products to advertise on any single retailer
Line items have bid settings, start & end dates, and optional budgeting & pacing controls
Budgets may additionally be controlled at the campaign level
Several reports are available to measure line item performance
Campaigns are limited to 10,000 non-archived line items
Line items are archived automatically 90 days after its end date

Endpoints

GET /campaigns/{campaignId}/preferred-line-items Get all Preferred Deals Line items from a specific Campaign
POST /campaigns/{campaignId}/preferred-line-items Creates 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

Attribute	Description	Values	Required	Default	Write	Nullable
`id`string	Line item ID	int64
`campaignId`string	Campaign ID	int64	Required
`name`string	Line item name; must be unique within acampaign	255 char limit	R		Write
`targetRetailerId`string	ID of theretailerthe line item serves on	int64	R
`startDate`date	Line item start date in theaccount`timeZone`	YYYY-MM-DD	R		W
`endDate`date	Line item end date in theaccount`timeZone`; serves indefinitely if omitted or set to`null`	YYYY-MM-DD	R	`null`	W	Yes
`budget`number	Line item lifetime spend cap;	at least 0	R	`null`	W	Yes
`budgetSpent`number	Amount the line item has already spent	at least 0		`0.0`
`budgetRemaining`number	Amount the line item has remaining until cap is hit;`null`if budget is uncapped	between 0 and`budget`		`null`		Yes
`pacing`enum	Way the budget will be spent, between the following values: `accelerated`(Spend as fast as possible) or`standard`(Spend evenly)	`accelerated`,`standard`	R
`capping`object	Frequency capping object		O
`capping:range`number	Frequency capping number	rangeline	R
`capping:type`enum	Frequency capping type	`day`,`session`	R
`page`object
`page:pageType`enum	Page type to serve on	`search`,`home`,`checkout`,`category`,`productDetail`,`confirmation`,`merchandising`,`deals`	R
`page:categories`objects array	Categories to serve on. Only applies to`category`,`productDetail`and`merchandising`page types		O
`page:categories:categoryId:value`
`page:categories:includeChildren:value`
`page:searchKeywords`string array	Keywords to serve on. Only applies to`search`page type		O
`creativeId`string	Identifier of the creative to be served with this line item		R
`status`enum	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	`active`,`paused`,`scheduled`,`ended`,`budgetHit`,`noFunds`,`draft`,`archived`
`createdAt`timestamp	Timestamp in UTC of line item creation	ISO-8601
`updatedAt`timestamp	Timestamp in UTC of last line item update	ISO-8601

Create a Preferred Deals Line Item

This endpoint creates a new preferred deals line item in the specified campaign Sample Request

curl -L -X POST 'https://api.criteo.com/experimental/retail-media/campaigns/329628911113846784/preferred-line-items' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkZMNllURk1pcVliT1RGUW4yUmh3cWFLTnhuaGV1MFBJTjFlZU9ydnBoSWMiLCJ0eXAiOiJKV1QifQ.eyJjbGllbnRfaWQiOiJiZTYyYWJmYmNhYWI0NzdhOWQwYzYyNTMzNGEzMGIwNiIsInR5cGUiOiJhY2Nlc3NfdG9rZW4iLCJpYXQiOjE2NTY1MzYxMzksImV4cCI6MTY1NjUzNzA5OSwiaXNzIjoicHJpdmF0ZS1jcml0ZW8tZXhhbW9hdXRoIiwiYXVkIjoicHJpdmF0ZS1jcml0ZW8tZXhhbW9hdXRoIn0.FmNUnRDfkT3KZAnGCwzmbtnXEXvUB5VpsZ7-f2QgW94AJrLziFKYwBpHckxiH4Dg0BcM0o5UFbeB5qIkdBl8NFvgWYnMpnaZLj7z32U-jk7Cwm2kMVH4DwqONd_qRsSPhn4MGKgK74qXY4L1shAKKchIVQQ-j5tBmiIvbQxJriALdCPm61ZHtSXJkPWAt8eBSGjPrfXFdOlb4auVzuHb57mr-YHIJBgm7LiVb-43mKVZtSf9sIiJafCwV2iCnqD8WlVzuwrcP7HZsnYgiIjQg3-E00vE8BptesIKpJyTf-xIzQ52KyzVeIGrx4EU9F5dBPug49J0H3HgGqrVyzEXxg' \
--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 Preferred Deals Line Items

This endpoint lists all preferred deals line items in the specified campaign. Results are paginated. Sample Request

curl -X GET "https://api.criteo.com/experimental/retail-media/campaigns/8343086999167541140/preferred-line-items" \
    -H "Authorization: Bearer myaccesstoken"

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/experimental/retail-media/campaigns/8343086999167541140/preferred-line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}

Get a Specific Preferred Deals Line Item

This endpoint retrieves the specified preferred deals line item.

curl -X GET "https://api.criteo.com/experimental/retail-media/preferred-line-items/2465695028166499188" \
    -H "Authorization: Bearer myaccesstoken"

{
    "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 Preferred Deals Line Item

This endpoint updates the specified preferred deals 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. Sample Request

curl -X PUT "https://api.criteo.com/experimental/retail-media/preferred-line-items/2465695028166499188" \
    -H "Authorization: Bearer myaccesstoken" \
    -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"
        }
    }
}

Introduction

Guides for Retail Media API

Preferred Deals Line Items

Endpoints

Line Item Attributes

Create a Preferred Deals Line Item

Get All Preferred Deals Line Items

Get a Specific Preferred Deals Line Item

Update a Specific Preferred Deals Line Item

​Endpoints

​Line Item Attributes

​Create a Preferred Deals Line Item

​Get All Preferred Deals Line Items

​Get a Specific Preferred Deals Line Item

​Update a Specific Preferred Deals Line Item

Endpoints

Line Item Attributes

Create a Preferred Deals Line Item

Get All Preferred Deals Line Items

Get a Specific Preferred Deals Line Item

Update a Specific Preferred Deals Line Item