Line Item Bidding

Overview

Use the Line Item Bidding endpoints to retrieve and set the CPM bidding configuration for an Onsite Display Auction line item, including Standard page-type bids and the Adaptive maximum bid.

Availability: AvailableThis endpoint is available in the Experimental version of the Retail Media API only. Only Onsite Display Auction line items are supported. Experimental endpoints may change without prior notice. See the versioning policy for details.

The response identifies the active strategy and includes preserved settings for the inactive strategy when available. This allows clients to inspect both Standard page-type bids and the Adaptive maximum bid without losing previously configured values.

Endpoints

Method	Endpoint	Description
`GET`	`/experimental/retail-media/line-items/{line-item-id}/bidding-strategy`	Retrieve the current bidding configuration for a line item.
`POST`	`/experimental/retail-media/line-items/{line-item-id}/set-bidding-strategy`	Set the bidding strategy and configuration for a line item.

Get Bidding Strategy

Path parameter

Parameter	Type	Required	Description
`line-item-id`	string	Yes	Identifier of the Onsite Display Auction line item.

The authenticated user must have permission to view the requested line item.

Sample request

curl -X GET "https://api.criteo.com/experimental/retail-media/line-items/123456789012345678/bidding-strategy" \
  -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
  -H "Accept: application/json"

Response attributes

All attributes below are nested under data.attributes in the response envelope.

Attribute	Type	Description
`cpm`	object or null	CPM-specific bidding configuration.
`cpm.bidStrategy`	string	Active strategy: `Standard` or `Adaptive`.
`cpm.standardBiddingSettings`	object or null	Active or preserved Standard strategy settings.
`cpm.standardBiddingSettings.auctionBids`	array	Manual bid amounts configured by page type.
`cpm.standardBiddingSettings.auctionBids[].pageType`	string	Page type to which the bid applies.
`cpm.standardBiddingSettings.auctionBids[].bid`	number	Bid amount in the line item’s currency.
`cpm.adaptiveBiddingSettings`	object or null	Active or preserved Adaptive strategy settings.
`cpm.adaptiveBiddingSettings.maxBid`	number or null	Maximum bid the Adaptive strategy may use.

Supported pageType values: Unknown, Search, Home, Browse, Checkout, Category, ProductDetail, Confirmation, Merchandising, Deals, Favorites, SearchBar, CategoryMenu, AiAssistant. Availability depends on the retailer and line item configuration.

Active and preserved settings

The value of cpm.bidStrategy identifies the active bidding strategy. The response can include both standardBiddingSettings and adaptiveBiddingSettings: the settings for the non-active strategy are preserved configuration, not an indication that both strategies are active.

Sample response

{
  "data": {
    "type": "BiddingSettings",
    "attributes": {
      "cpm": {
        "bidStrategy": "Adaptive",
        "standardBiddingSettings": {
          "auctionBids": [
            {
              "pageType": "Search",
              "bid": 1.25
            }
          ]
        },
        "adaptiveBiddingSettings": {
          "maxBid": 3.5
        }
      }
    }
  }
}

Responses

Status	Description
`200 OK`	Returns the current bidding configuration.
`400 Bad Request`	The line item type is not supported.
`401 Unauthorized`	The access token is missing, invalid, or expired.
`403 Forbidden`	The line item does not exist or is not accessible.

Set Bidding Strategy

The endpoint replaces the submitted Standard page-type bids. It updates only the strategy settings supplied in the request — omitted settings are preserved.

Path parameter

Parameter	Type	Required	Description
`line-item-id`	string	Yes	Identifier of the Onsite Display Auction line item.

The authenticated user must have permission to edit the requested line item.

Request attributes

All attributes below are nested under data.attributes in the request envelope.

Attribute	Type	Required	Description
`cpm`	object	No	CPM-specific bidding configuration to update.
`cpm.bidStrategy`	string	Yes, when `cpm` is supplied	Active strategy to set: `Standard` or `Adaptive`.
`cpm.standardBiddingSettings`	object	No	Standard strategy settings to update.
`cpm.standardBiddingSettings.auctionBids`	array	Yes, when `standardBiddingSettings` is supplied	Manual bid amounts by page type. Replaces all existing Standard bids.
`cpm.standardBiddingSettings.auctionBids[].pageType`	string	Yes	Page type to which the bid applies.
`cpm.standardBiddingSettings.auctionBids[].bid`	number	Yes	Bid amount in the line item’s currency.
`cpm.adaptiveBiddingSettings`	object	No	Adaptive strategy settings to update.
`cpm.adaptiveBiddingSettings.maxBid`	number or null	No	Maximum bid the Adaptive strategy may use.

Sample request

curl -X POST "https://api.criteo.com/experimental/retail-media/line-items/123456789012345678/set-bidding-strategy" \
  -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "data": {
      "type": "BiddingSettings",
      "attributes": {
        "cpm": {
          "bidStrategy": "Standard",
          "standardBiddingSettings": {
            "auctionBids": [
              {
                "pageType": "Search",
                "bid": 1.25
              }
            ]
          }
        }
      }
    }
  }'

Sample response

{
  "data": {
    "type": "BiddingSettings",
    "attributes": {
      "cpm": {
        "bidStrategy": "Standard",
        "standardBiddingSettings": {
          "auctionBids": [
            {
              "pageType": "Search",
              "bid": 1.25
            }
          ]
        },
        "adaptiveBiddingSettings": {
          "maxBid": 3.5
        }
      }
    }
  },
  "warnings": [],
  "errors": []
}

Responses

Status	Code	Description
`200 OK`		Returns the updated bidding configuration. Inspect `errors` and `warnings` before treating the response as complete.
`400 Bad Request`	`missing-cpm-bidding-settings`	The request does not include CPM bidding settings.
`400 Bad Request`	`invalid-bid-strategy`	The specified bidding strategy is invalid.
`400 Bad Request`	`enable-adaptive-requires-end-date`	Enabling Adaptive bidding requires a line item end date.
`400 Bad Request`	`enable-adaptive-requires-capped-budget`	Enabling Adaptive bidding requires a capped line item budget.
`400 Bad Request`	`adaptive-max-bid-out-of-range`	The Adaptive maximum bid is outside the supported range.
`400 Bad Request`	`adaptive-max-bid-below-floor`	The Adaptive maximum bid is below the applicable retailer floor.
`400 Bad Request`	`auction-bid-duplicate-page-type`	More than one Standard bid is supplied for the same page type.
`400 Bad Request`	`auction-bid-invalid-page-type`	A supplied page type is invalid.
`400 Bad Request`	`auction-bid-out-of-range`	A Standard bid is outside the supported range.
`400 Bad Request`	`bid-below-floor`	A Standard bid is below the applicable retailer floor for its page type.
`400 Bad Request`	`unsupported-line-item-type`	The line item type is not supported.
`401 Unauthorized`		The access token is missing, invalid, or expired.
`403 Forbidden`		The line item does not exist or is not accessible.

Introduction

Guides for Retail Media API

Overview

Endpoints

Get Bidding Strategy

Path parameter

Sample request

Response attributes

Active and preserved settings

Sample response

Responses

Set Bidding Strategy

Path parameter

Request attributes

Sample request

Sample response

Responses

​Overview

​Endpoints

​Get Bidding Strategy

​Path parameter

​Sample request

​Response attributes

​Active and preserved settings

​Sample response

​Responses

​Set Bidding Strategy

​Path parameter

​Request attributes

​Sample request

​Sample response

​Responses

Overview

Endpoints

Get Bidding Strategy

Path parameter

Sample request

Response attributes

Active and preserved settings

Sample response

Responses

Set Bidding Strategy

Path parameter

Request attributes

Sample request

Sample response

Responses