Open mobile menu
Discard
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussionsLog In

Promoted Products

Suggest Edits
  • A promoted product specifies the product to promote on a line item
  • Identify eligible products to promote through your account catalog
  • Each product may be optionally configured with a specific amount to bid with
  • Line items are each limited to 500 promoted products

Enpoints

  • GET /line-items/{lineItemId}/products Get All Products on a Specific Line Item
  • POST /line-items/{lineItemId}/products/append Add Products to a Specific Line Item, or update a 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
  • POST /line-items/{lineItemId}/products/unpause Reactivate Paused Products on a Specific Line Item

Promoted Product Attributes

Attribute

Description

Values

Required

id string

Retailer product ID unique to the retailer; obtained from the account catalog

500 char limit

Required

bidOverride number

Amount used to bid for the specific product; overrides targetBid specified on the line item and behaves similarly; must meet minBid, which is retrieved through the catalogs; input excludes platform fees

at least minBid

Optional

status

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

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
https://api.criteo.com/2022-04/retail-media//line-items/{lineItemId}/products/append

Sample Request

curl -X POST "https://api.criteo.com/2022-04/retail-media/line-items/2465695028166499188/products/append" \
    -H "Authorization: Bearer myaccesstoken" \
    -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"
                }
            ]
        }'

Sample Response

{
    "metadata": {
        "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.

https://api.criteo.com/2022-04/retail-media//line-items/{lineItemId}/products/delete

Sample Request

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

Sample Response

{
    "metadata": {
        "totalItemsAcrossAllPages": 2,
        "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"
        }
    ],
    "warnings": [],
    "errors": []
}

Get All Products on a Specific Line Item

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

https://api.criteo.com/2022-04/retail-media/line-items/{lineItemId}/products

Sample Request

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

Sample Response

{
    "metadata": {
        "totalItemsAcrossAllPages": 3,
        "currentPageSize": 20,
        "currentPageIndex": 0,
        "totalPages": 1
    },
    "data": [
        {
            "attributes": {
                "bidOverride": null,
                "status": "active",
                "id": "06d3049c3e1642ec92479dbeca1fc39f"
            },
            "id": "06d3049c3e1642ec92479dbeca1fc39f",
            "type": "RetailMediaPromotedProduct"
        },
      
      //...

        {
            "attributes": {
                "bidOverride": null,
                "status": "active",
                "id": "926097"
            },
            "id": "926097",
            "type": "RetailMediaPromotedProduct"
        }
    ],
    "warnings": [],
    "errors": []
}

Pause Products on a Specific Line Item

  • This endpoint allows reactivating one or multiple paused products on a line item
https://api.criteo.com/2022-04/retail-media/line-items/{lineItemId}/products/pause

Sample Request

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

Sample Response

{
    "warnings": [],
    "errors": []
}

Reactivate Paused Products on a Specific Line Item

This endpoint allows pausing one or multiple products on a line item

https://api.criteo.com/2022-04/retail-media/line-items/{lineItemId}/products/unpause

Sample Request

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

Sample Response

// Sample Response
{
    "warnings": [],
    "errors": []
}

Updated 2 days ago

What’s Next
Did this page help you?