Onsite Sponsored Products Line Items

📝
Getting Started
Learn 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 the Campaign Accepted values: between 2 and 255-chars string Writeable? Y / Nullable? N
`campaignId`*	string	Campaign ID, in which the respective line item belongs and generated internally by Criteo Acceptable values: int64 Writeable? N / Nullable? N
`targetRetailerId`*	string	Retailer ID where the line item will serve ads on Accepted values: int64 Writeable? N / Nullable? N
`startDate`*	date	Line item start date, in the Account timezone Accepted values: `YYYY-MM-DD` Writeable? Y / Nullable? N
`endDate`	date	Line item end date (optional), in the Account timezone 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 the Account timezone 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 the Account timezone 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 the Catalog) 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 the Catalog) 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 out Campaign & 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` (in ISO-8601) Writeable? N / Nullable? N
`updatedAt`	timestamp	Timestamp of last line item update, in UTC Accepted values: `yyyy-mm-ddThh:mm:ss±hh:mm` (in ISO-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.

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

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"
          }
        }
      }'

import http.client
import json

conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": {
    "type": "RetailMediaAuctionLineItem",
    "attributes": {
      "name": "API Campaing",
      "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"
    }
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
conn.request("POST", "/{version}/retail-media/campaigns/405429491681951744/auction-line-items", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"data\":{\"type\":\"RetailMediaAuctionLineItem\",\"attributes\":{\"name\":\"API Campaing\",\"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\"}}\n}");
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/campaigns/405429491681951744/auction-line-items")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();
Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/campaigns/405429491681951744/auction-line-items');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
$request->setBody('{"data":{"type":"RetailMediaAuctionLineItem","attributes":{"name":"API Campaing","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"}}}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status:' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error:' . $e->getMessage();
}

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

https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}/auction-line-items?pageIndex={pageIndex}&pageSize={pageSize}

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>"

import requests

url = "https://api.criteo.com/{version}/retail-media/campaigns/76216196459831296/auction-line-items?pageIndex=0&pageSize=25"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("text/plain");

RequestBody body = RequestBody.create(mediaType, "");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/campaigns/76216196459831296/auction-line-items?pageIndex=0&pageSize=25")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/campaigns/76216196459831296/auction-line-items?pageIndex=0&pageSize=25');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));

$request->setHeader(array(
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}

catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

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

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

Sample Request

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

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("text/plain");

RequestBody body = RequestBody.create(mediaType, "");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/auction-line-items/358669652976373760")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("text/plain");

RequestBody body = RequestBody.create(mediaType, "");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/auction-line-items/358669652976373760")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/auction-line-items/358669652976373760');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}

catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

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.

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

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"
          }
        }
      }'

import requests
import json

url = "https://api.criteo.com/{version}/retail-media/auction-line-items/358669652976373760"

payload = json.dumps({
  "data": {
    "id": "2465695028166499188",
    "type": "RetailMediaLineItem",
    "attributes": {
      "name": "My New Line Item",
      "startDate": "2020-04-06",
      "endDate": None,
      "budget": None,
      "monthlyPacing": 30.00,
      "dailyPacing": None,
      "isAutoDailyPacing": True,
      "bidStrategy": "conversion",
      "targetBid": 0.30,
      "maxBid": None,
      "status": "active"
    }
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\"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\"}}}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/auction-line-items/358669652976373760")
  .method("PUT", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();
Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/auction-line-items/358669652976373760');
$request->setMethod(HTTP_Request2::METHOD_PUT);
$request->setConfig(array(
  'follow_redirects' => TRUE
));

$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

$request->setBody('{"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"}}}');

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}

catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

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

Invalid isAutoDailyPacing - Cannot turn on IsAutoDailyPacing and add a dailyPacing value. Only one of the two options can be used