Marketplace

Introduction

The Marketplace endpoints are used to update the product catalog with the latest status of a product. Products should be updated with the same information on the Product Detail Page found on the retailer's website.

Note: These APIs are going to be processed asynchronously, so success response indicates the request was accepted but not yet completed.

📘
You can also find the Marketplace endpoints in our API Reference here for updating the buy box winner and here for updating offers.

URLs

For AMERICAS: api.us.criteo.com
For APAC: api.as.criteo.com
For EMEA: api.eu.criteo.com

Endpoints

Verb	Endpoint	Description
POST	`/preview/retail-media/retailers/{retailer-id}/products/set-buy-box-winners`	Update the buy box winner for one or more products
POST	`/preview/retail-media/retailers/{retailer-id}/offers/update`	Update one or more offers by replacing each offer's price and availability with the given values

Marketplace Properties

Attribute	Data Type	Description
`retailer-id`*	String	The ID of the retailer. Writeable? Y / Nullable? N
`offerId`*	String	Identifies an existing offer. Writeable? Y / Nullable? N
`availability`*	String	Accepted values: outOfStock, preOrder, inStock, backOrder Writeable? Y / Nullable? N
`price`*	double	Product’s price at this store Writeable? Y / 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.

Update BuyBoxWinner

The Buy Box Winner for multiple products can be updated for a retailer by making a POST call to the BuyBoxWinner endpoint. For each product specified, the designated offer becomes the new buy box winner, while the previous buy box winner for that product becomes a loser.

The request body should specify the Offer ID of the current buy box winner. We support a maximum of 5000 buy box winners to be updated simultaneously.

📘
Use case: Update the Buy Box Winner for one or more products by only sending the new winner

https://api.criteo.com/preview/retail-media/retailers/{retailer-id}/products/set-buy-box-winners

Sample request

{
  "data": {
    "type": "SetProductBuyBoxWinnersRequest",
    "attributes": {
      "productBuyBoxWinners": [
        {
          "offerId": "123"
        },
        {
          "offerId": "456"
        }
      ]
    }
  }
}

Sample response

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

Update Offers

Offers can be updated for multiple offers on a specific retailer by making a POST call to the Offer endpoint.

The request body should specify the Offer ID, availability, and price of the offer. We support a maximum of 5000 offers to be updated simultaneously.

📘
Use case: Update the price and availability for an offer

https://api.criteo.com/preview/retail-media/retailers/{retailer-id}/offers/update

Sample request

{
  "data": {
    "type": "UpdateOffersRequest",
    "attributes": {
      "offerUpdates": [
        {
          "offerId": "123",
          "price": 100.00,
          "availability": "preOrder"
        },
        {
          "offerId": "456",
          "price": 200.00,
          "availability": "preOrder"
        }
      ]
    }
  }
}

Sample response

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

Validation errors

invalid-retailer-id
The request contains an invalid Retailer ID

duplicate-offer-id
An duplicate Offer ID has been found in the request.

REQUIRED_FIELD
The required field is missing.