/product-batches

Queue many product updates and get a ticket back immediately (202). Poll GET /product-batches/{ticket} for progress.

This is update only. Missing SKUs are recorded as errors on the ticket, they are not created. Max 2000 products per request.

Identify each row with code and catalogue_uid in the body (you can also set catalogue_uid once at the top level). Do not put SKUs in the URL.

Processing is rate limited so a large batch cannot starve the database. Each successful field change is written to the product change log against this API key.

Batch submit has a tighter budget than ordinary requests (10 per minute per key by default), on top of the usual 120 requests per minute.

Custom attributes

Each item can include custom_attributes in the same shape as a single product update. Attribute-only items are valid.

Core fields and attributes are applied when the worker runs. Poll this ticket with GET /product-batches/{ticket}. Missing type on a new key fails that item, not the whole batch.

Match is that product plus key. Existing keys update value only. New keys need type (string, date, currency, number, array, boolean, json). Caps: 50 keys per product, key length 100, value 8KB. No deletes. value: null clears the stored value.

{
  "catalogue_uid": "demo-catalogue",
  "products": [
    {
      "code": "BLUE+RED5",
      "soh": 12,
      "custom_attributes": [
        { "key": "warehouse_bin", "value": "A-12" },
        { "key": "lead_time_days", "value": 5, "type": "number" }
      ]
    }
  ]
}

Request

Authorization

Send your HTTP requests with an

Authorization

header that contains the word Basic followed by a space and a base64-encoded string username:password

Example:

Authorization: Basic *****************

Body Params application/jsonRequired

Example

{
    "catalogue_uid": "demo-catalogue",
    "products": [
        {
            "code": "BLUE+RED5",
            "soh": 12,
            "retail_price": 199.99,
            "custom_attributes": [
                {
                    "key": "warehouse_bin",
                    "value": "A-12"
                },
                {
                    "key": "lead_time_days",
                    "value": 5,
                    "type": "number"
                }
            ]
        },
        {
            "code": "APL-IPH-34",
            "soh": 34,
            "title": "iPhone 15 Pro 256GB"
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

application/json

The batch was accepted and is queued.

Bodyapplication/json

Example

{
    "ticket": "3b6c1e2a-8f11-4c2d-9a44-0b1c2d3e4f55",
    "status": "queued",
    "total": 2
}

Custom attributes#

Request

Request Code Samples

Responses

Custom attributes