Onsite Sponsored Products Line Items

Getting StartedLearn more about how open auction line items work with our API in Onsite Sponsored Products

Endpoints

Verb	Endpoint	Description
GET	`/campaigns/{campaignId}/auction-line-items`	Get all Open Auction Line items from a specific Campaign
POST	`/campaigns/{campaignId}/auction-line-items`	Create an Open Auction Line item
GET	`/auction-line-items/{lineItemId}`	Get a specific Open Auction Line item
PUT	`/auction-line-items/{lineItemId}`	Update a specific Open Auction Line item

Info

Create operations using the POST method expect every Required field; omitting Optional fields will set those fields to Default values
Update operations using the PUT method expect every Writeable field; omitting these fields is equivalent to setting them to null, if possible

Line Item Attributes

Attribute	Data Type	Description
`id`	string	Auction line item ID, generated internally by Criteo Acceptable values: int64 Writeable? N / Nullable? N
`name`*	string	Line item name, must be unique within theCampaign Accepted values: between 2 and 255-chars string Writeable? Y / Nullable? N
`campaignId`*	string	CampaignID, in which the respective line item belongs and generated internally by Criteo Acceptable values: int64 Writeable? N / Nullable? N
`targetRetailerId`*	string	RetailerID where the line item will serve ads on Accepted values: int64 Writeable? N / Nullable? N
`startDate`*	date	Line item start date, in theAccounttimezone Accepted values:`YYYY-MM-DD` Writeable? Y / Nullable? N
`endDate`	date	Line item end date (optional), in theAccounttimezone Accepted values:`YYYY-MM-DD` Writeable? Y / Nullable? Y
`budget`	decimal	Lifetime spend cap of line item (optional), uncapped if omitted or set to`null` Accepted values:`budget`≥ 0.0 Default:`null` Writeable? Y / Nullable? Y
`budgetSpent`	decimal	Amount the line item has already sent Accepted values:`budgetSpent`≥ 0.0 Default:`0.0` Writeable? N / Nullable? N
`budgetRemaining`	decimal	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
`monthlyPacing`	decimal	Amount the line item can spend per calendar month (optional), in theAccounttimezone Accepted values:`null`or greater than zero Default:`null` Writeable? Y / Nullable? Y
`dailyPacing`	decimal	Amount the line item can spend per calendar month (optional), in theAccounttimezone It resets each day overwritten by calculation if`isAutoDailyPacing`is enabled; uncapped if omitted of set to`null` Accepted values:`null`or greater than zero Default:`null` Writeable? Y / Nullable? Y
`isAutoDailyPacing`*	boolean	To activate, either line item`endDate`and budget, or`monthlyPace`, must be specified; overwrites`dailyPacing`with calculation if not set prior Accepted values:`true`,`false` Default:`false` Writeable? Y / Nullable? N
`bidStrategy`	enum	Bid algorithm optimizing for sales conversions, sales revenue or clicks Accepted values:`conversion`,`revenue`,`clicks` Default:`conversion` Writeable? Y / Nullable? N
`targetBid`*	decimal	If optimizing for`conversion`or`revenue`, a target average amount to bid (as each bid is modulated up/down by our optimization algorithm); else bids stay constant, if optimizing for`clicks` Bidding is uncapped if omitted or set to`null` ℹ️ Note: Must meet`minBid`for line item to deliver ads, which depends on selected products (available through theCatalog) Input excludes platform fees Accepted values: at least the greatest value of`minBid`across all products in the line item Default:`0.3` Writeable? Y / Nullable? N
`maxBid`	decimal	If optimizing for`conversion`or`revenue`, the maximum amount allowed to bid for each display (respected regardless of`targetBid`). Does not apply if optimizing for`clicks` Bidding is uncapped if omitted or set to`null` ℹ️ Note: Must meet`minBid`for line item to deliver ads, which depends on selected products (available through theCatalog) Input excludes platform fees Accepted values: at least`0.1` Writeable? Y / Nullable? Y
`status`	enum	Line item status, can only be updated by user to`active`or`paused` Other values are applied automatically depending start/end dates, financials or missing attributes required for line item to deliver ads. To understand the conditions that cause status changes, check outCampaign & Line Item Status Accepted values:`active`,`paused`,`scheduled`,`ended`,`budgetHit`,`noFunds`,`draft`,`archived` Writeable? N / 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) Writeable? N / Nullable? N

*Required

Field Definitions

Writeable (Y/N): Indicates if the field can be modified in requests.
Nullable (Y/N): Indicates if the field can accept null/empty values.
Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., retailerId, campaignId, lineItemId) and are usually required in the URL path.

Create an Onsite Sponsored Products Line Item

This endpoint creates a new Onsite Sponsored Products line item in the specified campaign. Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/campaigns/405429491681951744/auction-line-items' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
        "data": {
          "type": "RetailMediaAuctionLineItem",
          "attributes": {
            "name": "API Campaign",
            "startDate": "2023-01-23",
            "targetRetailerId": "299",
            "endDate": "2023-01-31",
            "status": "active",
            "budget": "1.00",
            "targetBid": "5",
            "maxBid": "5",
            "monthlyPacing": "50",
            "dailyPacing": "5",
            "isAutoDailyPacing": false,
            "bidStrategy": "conversion"
          }
        }
      }'

Sample Response

{
    "data": {
        "id": "405482503263227904",
        "type": "RetailMediaAuctionLineItem",
        "attributes": {
            "id": "405482503263227904",
            "name": "API Line Item",
            "startDate": "2023-01-23",
            "endDate": "2023-01-31",
            "maxBid": 5.00000000,
            "budget": 1.00000000,
            "monthlyPacing": 50.00000000,
            "dailyPacing": 5.00000000,
            "bidStrategy": "conversion",
            "targetRetailerId": "299",
            "status": "draft",
            "targetBid": 5.00000000,
            "isAutoDailyPacing": false,
            "campaignId": "405429491681951744",
            "budgetSpent": 0.00000000,
            "budgetRemaining": 1.00000000,
            "createdAt": "2023-01-23T22:02:42+00:00",
            "updatedAt": "2023-01-23T22:02:42+00:00"
        }
    },
    "warnings": [],
    "errors": []
}

Get all Onsite Sponsored Products Line Items

This endpoint lists all Onsite Sponsored Products 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/campaigns/8343086999167541140/auction-line-items?pageIndex=0&pageSize=25" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

Sample Response

{
    "data": [
        {
            "id": "9979917896105882144",
            "type": "RetailMediaLineItem",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "Line Item 123",
                "targetRetailerId": "3239117063738827231",
                "startDate": "2020-04-06",
                "endDate": null,
                "budget": null,
                "budgetSpent": 2383.87,
                "budgetRemaining": null,
                "monthlyPacing": null,
                "dailyPacing": null,
                "isAutoDailyPacing": false,
                "bidStrategy": "conversion",
                "targetBid": 1.50,
                "maxBid": 2.50,
                "status": "active",
                "createdAt": "2020-04-06T17:29:11+00:00",
                "updatedAt": "2020-04-06T17:29:11+00:00"
            }
        },
        // ...
        {
            "id": "6854840188706902009",
            "type": "RetailMediaLineItem",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "Line Item 789",
                "targetRetailerId": "18159942378514859684",
                "startDate": "2020-04-08",
                "endDate": null,
                "budget": 8000.00,
                "budgetSpent": 1921.23,
                "budgetRemaining": 6078.77,
                "monthlyPacing": 1000.00,
                "dailyPacing": 33.33,
                "isAutoDailyPacing": true,
                "bidStrategy": "conversion",
                "targetBid": 0.75,
                "maxBid": 1.25,
                "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/campaigns/8343086999167541140/line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}

Get a specific Onsite Sponsored Products Line Item

This endpoint retrieves the specified Onsite Sponsored Products line item Sample Request

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

Sample Response

{
    "data": { 
        "id": "2465695028166499188",
        "type": "RetailMediaLineItem",
        "attributes": {
            "campaignId": "8343086999167541140",
            "name": "My New Line Item",
            "targetRetailerId": "18159942378514859684",
            "startDate": "2020-04-06",
            "endDate": null,
            "budget": null,
            "budgetSpent": 0.00,
            "budgetRemaining": null,
            "monthlyPacing": null,
            "dailyPacing": null,
            "isAutoDailyPacing": false,
            "bidStrategy": "conversion",
            "targetBid": 0.30,
            "maxBid": null,
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:11:23+00:00"
        }
    }
}

Update a specific Onsite Sponsored Products Line Item

This endpoint updates the specified Onsite Sponsored Products line item. In this example, we enable auto daily pacing by setting a monthly pace simultaneously. Note that with auto daily pacing enabled, daily pacing is automatically calculated and overwrites its previous value, if any. 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/{version}/retail-media/auction-line-items/2465695028166499188" \
  -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "id": "2465695028166499188",
          "type": "RetailMediaLineItem",
          "attributes": {
            "name": "My New Line Item",
            "startDate": "2020-04-06",
            "endDate": null,
            "budget": null,
            "monthlyPacing": 30.00,
            "dailyPacing": null,
            "isAutoDailyPacing": true,
            "bidStrategy": "conversion",
            "targetBid": 0.30,
            "maxBid": null,
            "status": "active"
          }
        }
      }'

Sample Response

{
    "data": { 
        "id": "2465695028166499188",
        "type": "RetailMediaLineItem",
        "attributes": {
            "campaignId": "8343086999167541140",
            "name": "My New Line Item",
            "targetRetailerId": "18159942378514859684",
            "startDate": "2020-04-06",
            "endDate": null,
            "budget": null,
            "budgetSpent": 0.00,
            "budgetRemaining": null,
            "monthlyPacing": 3000.00,
            "dailyPacing": 120.00,
            "isAutoDailyPacing": true,
            "bidStrategy": "conversion",
            "targetBid": 0.30,
            "maxBid": null,
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:17:48+00:00"
        }
    }
}

Responses

Responses	Description
🔵`200`	Call completed with success
🔵`201`	Line item created with success
🔴`400`	Bad request leading to a validation error Common validation errors Invalid`isAutoDailyPacing`- Cannot turn on`IsAutoDailyPacing`and add a`dailyPacing`value. Only one of the two options can be used

Description

🔵200

Call completed with success

🔵201

Line item created with success

🔴400

Bad request leading to a validation error

Common validation errors

InvalidisAutoDailyPacing- Cannot turn onIsAutoDailyPacingand add adailyPacingvalue. Only one of the two options can be used

​Endpoints

​Line Item Attributes

​Create an Onsite Sponsored Products Line Item

​Get all Onsite Sponsored Products Line Items

​Get a specific Onsite Sponsored Products Line Item

​Update a specific Onsite Sponsored Products Line Item

​Responses

Endpoints

Line Item Attributes

Create an Onsite Sponsored Products Line Item

Get all Onsite Sponsored Products Line Items

Get a specific Onsite Sponsored Products Line Item

Update a specific Onsite Sponsored Products Line Item

Responses