/products/update

Update one catalogue product. Put the SKU in code on the JSON body so values like BLUE+RED5 are not mangled.

Send only the fields you want to change. At least one writable field is required, otherwise you get 400 validation_error. Fields you leave out keep their current values.

This writes a product change log row per changed field, linked to the API key that made the call.

Catalogue scoping

Every API key is granted one or more catalogues. A product is identified by code within a catalogue.

API key reaches	What to send	If you omit it
One catalogue	Nothing, it is inferred	Fine
More than one catalogue	`catalogue_uid`	`400 catalogue_required`

catalogue_id still works as a fallback. A uid the key cannot reach returns 404 catalogue_not_found.

What cannot change

code identifies the product and cannot be renamed here. A product cannot be moved between catalogues. id, created_at and updated_at are ignored. Unknown field names are ignored.

Stock and price example:

{
  "catalogue_uid": "demo-catalogue",
  "code": "BLUE+RED5",
  "soh": 12,
  "retail_price": 199.99
}

Custom attributes

Send custom_attributes on the same body to upsert additional attributes. Core product fields are saved immediately. Attribute writes are queued. The product you get back still has the previous custom_attributes. Poll GET /product-batches/{ticket} using custom_attributes_update.ticket.

An attributes-only body is valid. If the queue is down you get 503 queue_unavailable and product fields are not written.

Match is this product plus key (latest row if duplicates exist).

Key	Behaviour
Already on the product	Updates `value` only. Uses the stored type. Incoming `type` is ignored.
New on the product	`type` is required. Creates the attribute.

type is one of 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",
  "code": "BLUE+RED5",
  "soh": 12,
  "custom_attributes": [
    { "key": "warehouse_bin", "value": "A-12" },
    { "key": "lead_time_days", "value": 5, "type": "number", "label": "Lead time (days)" }
  ]
}

A map is also accepted: { "warehouse_bin": { "value": "A-12" } }. GET-shaped value: { "data": ... } works for a round trip.

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",
    "code": "BLUE+RED5",
    "soh": 12,
    "retail_price": 199.99,
    "title": "Blue/red widget",
    "custom_attributes": [
        {
            "key": "warehouse_bin",
            "value": "A-12"
        },
        {
            "key": "lead_time_days",
            "value": 5,
            "type": "number",
            "label": "Lead time (days)"
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

The product after the update. If custom_attributes was sent, custom_attributes_update: { ticket, status: "queued" } is included. Returned custom_attributes are still the pre-queue values.

Bodyapplication/json

Example

{}

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🟠405

🟠429

🔴503Service Unavailable

Catalogue scoping#