Store Inventory

Introduction

Store Inventory enables retailers to manage product availability and pricing at the store level, supporting accurate PDP/ad experiences. Inventory events (upserts and deletes) are sent in batches, enabling real-time updates for price and availability per store.

This API is event-driven and multi-tenant.

📘
You can also find the Store Inventory endpoints in our API Reference here for upsert, and here for delete.

URLs

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

Endpoints

Verb	Endpoint	Description
POST	`/{version}/catalog/merchants/\{merchantId}/store-inventory/upsert`	Insert or update store(s)
POST	`/{version}/catalog/merchants/\{merchantId}/store-inventory/delete`	Delete store(s)

Store Inventory Attributes

Attribute	Data Type	Description
`merchantId`*	integer	The ID of the managing account. Criteo: the `partnerId` Accepted values: integer (int32) Writeable? N / Nullable? N
`batchId`*	String	Identifies this event. Should be unique for a given endpoint call. Writeable? Y / Nullable? N
`productId`*	String	Identifies a product Accepted values: up to 50 chars string Writeable? Y / Nullable? N
`storeId`*	String	Identifies the store for the customer. Accepted values: up to 64 chars string Writeable? Y / Nullable? N
`availability`*	String	Accepted values: In stock, Out of stock, Preorder, Backorder Writeable? Y / Nullable? N
`price`*	String	Product’s price at this store Accepted values: up to 14 chars string Writeable? Y / Nullable? N
`salePrice`	String	The sale price of the product Accepted values: up to 14 chars string Writeable? Y / Nullable? Y

(*) 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., merchantId, batchId, productId) and are usually required in the URL path.

Upsert Store Inventory

Send a batch of inventory upsert events for a merchant.

📘
Use case: Insert or update store-level inventory (price, availability) for one or more products.

https://api.criteo.com/{version}/retail-media/catalog/merchants/{merchantId}/store-inventory/upsert

Sample request

{
  "data": [
    {
      "type": "Upsert",
      "attributes": {
        "batchId": "batch1",
        "productId": "product1",
        "storeId": "store1",
        "availability": "IN_STOCK",
        "price": "19.99",
        "salePrice": "10.99"
      }
    },
    {
      "type": "Upsert",
      "attributes": {
        "batchId": "batch2",
        "productId": "product2",
        "storeId": "store2",
        "availability": "OUT_OF_STOCK",
        "price": "29.99"
      }
    }
  ]
}

Sample Response

HTTP STATUS 204 (No Content)
<EMPTY PAYLOAD>

Delete Store Inventory

Send a batch of inventory delete events for a merchant.

📘
Use case: Remove outdated or unavailable inventory records.

https://api.criteo.com/{version}/retail-media/catalog/merchants/{merchantId}/store-inventory/delete

Sample Request

{
  "data": [
    {
      "type": "Delete",
      "attributes": {
        "batchId": "batch1",
        "productId": "product1",
        "storeId": "store1"
      }
    },
    {
      "type": "Delete",
      "attributes": {
        "batchId": "batch2",
        "productId": "product2",
        "storeId": "store2"
      }
    }
  ]
}

Response Example

HTTP STATUS 204 (No Content)
<EMPTY PAYLOAD>

Error Codes

Error code	Error text	Description
400	Bad request	Validation errors, required fields, unique `batchId`/`productId`/`storeCode`
400	Request too large	Payload exceeds 1000 events
401	Unauthorized	Authentication required
403	Forbidden	Not authorized
429	Too Many Requests	Rate limiting
500	Internal Error	Server error
503	Service Unavailable	Service temporarily unavailable