Promoted Products

Getting Started

A promoted product specifies the product that will be advertised on a line item.
Identify eligible products to promote by accessing your account catalog.
Each product can optionally be configured with a specific bid amount, allowing you to control how much you are willing to pay per click.
Each line item is limited to a maximum of 500 promoted products.

Endpoints

Method	Endpoint	Description
GET	`/line-items/{lineItemId}/products`	Retrieve all products associated with a specific line item.
POST	`/line-items/{lineItemId}/products/append`	Add products to a specific line item or update their bid override.
POST	`/line-items/{lineItemId}/products/delete`	Remove products from a specific line item.
POST	`/line-items/{lineItemId}/products/pause`	Pause products on a specific line item, preventing them from being advertised.
POST	`/line-items/{lineItemId}/products/unpause`	Reactivate paused products on a specific line item, allowing them to be advertised again.

Promoted Products Attributes

Attribute	Data Type	Description
`id`*	string	Product ID, unique identifier at the Retailer catalog and obtained from the account CatalogAccepted values: up to 500-chars string Writeable? N / Nullable? N
`lineItemId`*	string	Line Item ID, in which the product is to be promoted; required in the endpoints’ path to define in which line item to perform the actionAccepted values: string of int64 Writeable? N / Nullable? N
`bidOverride`	decimal	Bid value for the specific product; overrides `targetBid` specified on the Line Item and must satisfy `minBid` from Catalog (input excludes platform fees)Accepted values: `bidOverride` ≥ 0.0 Default: `0.0` Writeable? Y / Nullable? Y
`status`	enum	Status of Promoted Product; can only be updated to active or paused using the pause/un-pause endpoints below. For more details about each state, check out Campaign, Line Item & Products StatusAccepted values: `active`, `paused`, `scheduled`, `ended`, `budgetHit`, `noFunds`, `draft`, `archived` Writeable? Y / Nullable? N

*Required

Get All Products on a Specific Line Item

This endpoint lists all products on the specified line item. Results are paginated. Optional Query Parameters

Query Param	Data Type	Description
`offsite`	integer	Pagination parameter, see API Response
`limit`	integer	Pagination parameter, see API Response
`fields`	list	Comma-separated list of optional attributes to include in the response - can be used to optimize response time and payload length

Sample Request

curl -X GET "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188/products?offset=0&limit=10&fields=bidOverride,status" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

import requests

url = "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188/products?offset=0&limit=10&fields=bidOverride"

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/line-items/2465695028166499188/products?offset=0&limit=10&fields=bidOverride")
  .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/line-items/2465695028166499188/products?offset=0&limit=10&fields=bidOverride');
$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 🔵 HTTP code 200:

{
    "meta": {
        "offset": 0,
        "limit": 10,
        "count": 34,
        "responseCount": 34
    },
    "data": [
        {
            "id": "06d3049c3e1642ec92479dbeca1fc39f",
            "type": "RetailMediaPromotedProduct",
            "attributes": {
                "bidOverride": 0.70,
                "status": "active"
            }
        },
        // ...
        {
            "id": "926097",
            "type": "RetailMediaPromotedProduct",
            "attributes": {
                "bidOverride": 0.30,
                "status": "active"
            }
        }
    ]
}

Add Products to a Specific Line Item, or Update a Bid Override

This endpoint adds one or more products to promote on the specified line item. The resulting state of the line item is returned as a single page. If the product already exists, only its bid override will be updated. Sample Request

curl -X POST "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188/products/append" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
            "data": [
                {
                    "type": "RetailMediaPromotedProduct",
                    "id": "sku1",
                    "attributes": {
                        "bidOverride": 3.50
                    }
                },
                {
                    "type": "RetailMediaPromotedProduct",
                    "id": "sku3",
                    "attributes": {
                        "bidOverride": 2.00
                    }
                },
                {
                    "type": "RetailMediaPromotedProduct",
                    "id": "sku41",
                    "attributes": {
                        "bidOverride": 1.50
                    }
                },
                {
                    "type": "RetailMediaPromotedProduct",
                    "id": "sku67"
                }
            ]
        }'

import requests
import json

url = "https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/append"

payload = json.dumps({
  "data": [
    {
      "id": "be5a3dbc8eaf46608d58ce68107a5854",
      "type": "RetailMediaProductAppend",
      "attributes": {
        "bidOverride": "0.50"
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("POST", 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, "{\n  \"data\": [\n    {\n      \"id\": \"be5a3dbc8eaf46608d58ce68107a5854\",\n      \"type\": \"RetailMediaProductAppend\",\n      \"attributes\": {\n        \"bidOverride\": \"0.50\"\n      }\n    }\n  ]\n}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/append")
  .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/line-items/325713346766241792/products/append');
$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('{\n  "data": [\n    {\n      "id": "be5a3dbc8eaf46608d58ce68107a5854",\n      "type": "RetailMediaProductAppend",\n      "attributes": {\n        "bidOverride": "0.50"\n      }\n    }\n  ]\n}');
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

{
    "meta": {
        "totalItemsAcrossAllPages": 3,
        "currentPageSize": 2147483647,
        "currentPageIndex": 0,
        "totalPages": 1
    },
    "data": [
        {
            "attributes": {
                "bidOverride": null,
                "status": "active",
                "id": "06d3049c3e1642ec92479dbeca1fc39f"
            },
            "id": "06d3049c3e1642ec92479dbeca1fc39f",
            "type": "RetailMediaPromotedProduct"
        },
        {
            "attributes": {
                "bidOverride": null,
                "status": "active",
                "id": "156a8cb56faf4e6a9c2eb0451255f13c"
            },
            "id": "156a8cb56faf4e6a9c2eb0451255f13c",
            "type": "RetailMediaPromotedProduct"
        },
        {
            "attributes": {
                "bidOverride": 0.35000000,
                "status": "active",
                "id": "926097"
            },
            "id": "926097",
            "type": "RetailMediaPromotedProduct"
        }
    ],
    "warnings": [],
    "errors": []
}

Remove Products from a Specific Line Item

This endpoint removes one or more products from the specified line item. The resulting state of the line item is returned as a single page. Line items can be created without any promoted products, but once any products are added, at least one product must remain. Sample Request

curl -X POST "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188/products/delete" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
            "data": [
                {
                    "id": "sku1",
                    "type": "RetailMediaPromotedProduct"
                }
            ]
        }'

import requests
import json

url = "https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/delete"

payload = json.dumps({
  "data": [
    {
      "id": "be5a3dbc8eaf46608d58ce68107a5854",
      "type": "RetailMediaDeleteProduct",
      "attributes": {
        "bidOverride": "0.30"
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("POST", 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, "{\n  \"data\": [\n    {\n      \"id\": \"be5a3dbc8eaf46608d58ce68107a5854\",\n      \"type\": \"RetailMediaDeleteProduct\",\n      \"attributes\": {\n        \"bidOverride\": \"0.30\"\n      }\n    }\n  ]\n}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/delete")
  .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/line-items/325713346766241792/products/delete');
$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('{\n  "data": [\n    {\n      "id": "be5a3dbc8eaf46608d58ce68107a5854",\n      "type": "RetailMediaDeleteProduct",\n      "attributes": {\n        "bidOverride": "0.30"\n      }\n    }\n  ]\n}');
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 🔵 HTTP code 204 (no body content)

Pause Products on a Specific Line Item

This endpoint allows reactivating one or multiple paused products on a line item: Sample Request

curl -X POST 'https://api.criteo.com/{version}/retail-media/line-items/311990577399115776/products/pause' \
		-H 'Content-Type: application/json' \
		-H'Authorization: Bearer <MY_ACCESS_TOKEN>' \
    -d '{
          "data": [
            {
              "id": "4f5c49fce3c94542b5023e7cc1e1f5ca",
              "type": "RetailMediaPromotedProduct"
            }
         ]
    }'

import requests
import json

url = "https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/pause"

payload = json.dumps({
  "data": [
    {
      "id": "be5a3dbc8eaf46608d58ce68107a5854",
      "type": "RetailMediaPausePromoteDProduct"
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

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

print(response.text)

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

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

$request->setBody('{\n  "data": [\n    {\n      "id": "be5a3dbc8eaf46608d58ce68107a5854",\n      "type": "RetailMediaPausePromoteDProduct"\n    }\n  ]\n}');
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();
}

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

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

RequestBody body = RequestBody.create(mediaType, "{\n  \"data\": [\n    {\n      \"id\": \"be5a3dbc8eaf46608d58ce68107a5854\",\n      \"type\": \"RetailMediaPausePromoteDProduct\"\n    }\n  ]\n}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/pause")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

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

Sample Response 🔵 HTTP code 204 (no body content)

Unpaused Products on a Specific Line Item

This endpoint allows unpausing one or multiple products on a line item: Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/line-items/311990577399115776/products/unpause' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "id": "4f5c49fce3c94542b5023e7cc1e1f5ca",
      "type": "RetailMediaPromotedProduct"
    }
  ]
}'

import requests
import json

url = "https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/unpause"

payload = json.dumps({
  "data": [
    {
      "id": "be5a3dbc8eaf46608d58ce68107a5854",
      "type": "RetailMediaPausePromoteDProduct"
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("POST", 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, "{\n  \"data\": [\n    {\n      \"id\": \"be5a3dbc8eaf46608d58ce68107a5854\",\n      \"type\": \"RetailMediaPausePromoteDProduct\"\n    }\n  ]\n}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/line-items/325713346766241792/products/unpause")
  .method("POST", body)
  .addHeader("Content-Type", "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/line-items/325713346766241792/products/unpause');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

$request->setBody('{\n  "data": [\n    {\n      "id": "be5a3dbc8eaf46608d58ce68107a5854",\n      "type": "RetailMediaPausePromoteDProduct"\n    }\n  ]\n}');
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 🔵 HTTP code 204 (no body content)

Responses

Response	Description
🟢 `200`	Call completed with success
🟢 `204`	Promoted product paused or un-paused with success (no body content returned)
🔴 `400`	Bad Request - Common validation errors: Could not find the SKU ID used to append to the line item. Make sure the SKU exists in the retailer’s catalog Product bid override less than the product min bid Invalid bid override:Cannot use bid override attribute for a product belonging to a preferred deals line item Pausing/Un-pausing promoted products: Only the ID is required; do not include `BidOverride` or `Status` attributes.
🔴 `403`	API user does not have authorization to make requests for the account ID. For authorization, follow the authorization request steps.
🔴 `404`	Line item ID not found

Introduction

Guides for Retail Media API

Endpoints

Promoted Products Attributes

Get All Products on a Specific Line Item

Add Products to a Specific Line Item, or Update a Bid Override

Remove Products from a Specific Line Item

Pause Products on a Specific Line Item

Unpaused Products on a Specific Line Item

Responses

​Endpoints

​Promoted Products Attributes

​Get All Products on a Specific Line Item

​Add Products to a Specific Line Item, or Update a Bid Override

​Remove Products from a Specific Line Item

​Pause Products on a Specific Line Item

​Unpaused Products on a Specific Line Item

​Responses

Endpoints

Promoted Products Attributes

Get All Products on a Specific Line Item

Add Products to a Specific Line Item, or Update a Bid Override

Remove Products from a Specific Line Item

Pause Products on a Specific Line Item

Unpaused Products on a Specific Line Item

Responses