Skip to main content
Getting StartedLearn more about how open auction line items work with our API here!
 

​
Endpoints

VerbEndpointDescription
GET/campaigns/{campaignId}/auction-line-itemsGet all Open Auction Line items from a specific Campaign
POST/campaigns/{campaignId}/auction-line-itemsCreates an Open Auction Line item
GET/auction-line-items/{lineItemId}Get a specific Open Auction Line item
PUT/auction-line-items/{lineItemId}Updates 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

AttributeData TypeDescription
idstringLine item IDAcceptable values: int64 Writeable? N / Nullable? N
campaignId*stringCampaign IDAcceptable values: int64 Writeable? N / Nullable? N
name*stringLine item name, must be unique within the CampaignAccepted values: 255 char limit Writeable? Y / Nullable? N
targetRetailerId*stringRetailer ID where the line item will serve ads onAccepted values: int64 Writeable? N / Nullable? N
startDate*dateLine item start date, in the Account timezoneAccepted values: YYYY-MM-DD Writeable? Y / Nullable? N
endDatedateLine item end date (optional), in the Account timezoneAccepted values: YYYY-MM-DD Writeable? Y / Nullable? Y
budgetdecimalLine item lifetime spend cap (optional); if omitted or set to null, will be considered uncappedAccepted values: null or greater than zero Default: null Writeable? Y / Nullable? Y
budgetSpentdecimalAmount the line item has already sentAccepted values: equals or greater than 0 Default: 0.0 Writeable? N / Nullable? N
budgetRemainingdecimalAmount the line item has remaining until cap is hit; null if budget is uncappedAcceptable values: between zero and budget Writeable? N / Nullable? Y
monthlyPacingdecimalAmount the line item can spend per calendar month, in the Account timezone (optional)Accepted values: null or greater than zero Default: null Writeable? Y / Nullable? Y
dailyPacingdecimalAmount the line item can spend per calendar month, in the Account timezone (optional) It resets each day overwritten by calculation if isAutoDailyPacing is enabled; uncapped if omitted of set to nullAccepted values: null or greater than zero Default: null Writeable? Y / Nullable? Y
isAutoDailyPacing*booleanTo activate, either line item endDate and budget, or monthlyPace, must be specified; overwrites dailyPacing with calculation if not set priorAccepted values: true, false Default: false Writeable? Y / Nullable? N
bidStrategyenumBid algorithm optimizing for sales conversions, sales revenue or clicksAccepted values: conversion, revenue, clicks Default: conversion Writeable? Y / Nullable? N
targetBid*decimalIf 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 the Catalog)
  • Input excludes platform feesAccepted 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 the Catalog)
  • Input excludes platform feesAccepted 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 out Campaign & Line Item StatusAccepted values: active, paused, scheduled, ended, budgetHit, noFunds, draft, arquived Writeable? N / Nullable? N | | createdAt | timestamp | Timestamp of line item creation, in UTCAccepted values: yyyy-mm-ddThh:mm:ss±hh:mm (in ISO-8601) Writeable? N / Nullable? N | | updatedAt | timestamp | Timestamp of last line item update, in UTCAccepted values: yyyy-mm-ddThh:mm:ss±hh:mm (in ISO-8601 ) Writeable? N / Nullable? N |
*Required

​
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>' \
--data-raw '{
	"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": {
        "attributes": {
            "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",
            "id": "405482503263227904"
        },
        "id": "405482503263227904",
        "type": "RetailMediaAuctionLineItem"
    },
    "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 Sample Request 
curl -X GET "https://api.criteo.com/{version}/retail-media/campaigns/8343086999167541140/auction-line-items" \
    -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,
                "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"
            }
        },
        // ...
        {
            "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,
                "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": { 
        "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,
            "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": {
                "type": "RetailMediaLineItem",
                "id": "2465695028166499188",
                "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": { 
        "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,
            "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

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