Skip to content

Update a product

Open in ClaudeOpen in ChatGPTView as Markdown
PATCH
/products/{id}

Updates a product, and replaces any nested collection included in the body.

  • Omitting codes, tags, suppliers, variant_attributes or components leaves that collection untouched; sending [] clears it.

  • tags are referenced by tag id; an unknown id is a 400.

  • supply_price is never accepted, neither on the product nor on a nested supplier.

  • variant_options is read-only and ignored if sent.

  • variant_attributes can only change while the product has no live variant children; once it does, a change is a 409.

  • The version a GET response returned can be sent back as the concurrency check, same as today’s expected_version; sending both requires they agree.

  • The write is atomic: an invalid entry in any collection applies nothing, not even a scalar change.

  • image_url fetches the image once and imports it through the same pipeline as an admin upload; a fetch failure does not undo the update: it answers 422 IMAGE_FETCH_FAILED with the updated product in data. Gift card products can’t be changed through this endpoint.

  • 400 VALIDATION_FAILED: a field failed validation, version and expected_version disagree, or a variant_attributes rule (more than 3 entries, a position outside 1 to 3, or a duplicate position).

  • 404 NOT_FOUND: the id is foreign, unknown, or already deleted, or a referenced brand or category was not found.

  • 409 CONFLICT: variant_attributes changed while the product has live variant children, or a nested code or supplier link conflicts with an existing one.

  • 409 STALE_VERSION: version/expected_version did not match the product’s current version.

  • 422 UNPROCESSABLE: it is a gift card product, or a codes, tags, suppliers or components cap was exceeded.

  • 422 IMAGE_FETCH_FAILED: the product was updated but the image could not be imported.

Requires scope: catalog:write

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
active
boolean
brand_id
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
category_id
Any of:
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
codes
Array<object>
object
code
required
string
type
required
string
Allowed values: upc isbn itf ean jan custom
components
Array<object>
object
product_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
quantity
required
integer
>= 1 <= 9007199254740991
created_at
description
Any of:
string
<= 255 characters
dimension_unit
Any of:
string
Allowed values: mm cm in ft
expected_version
Any of:
integer
<= 9007199254740991
has_inventory
boolean
has_variants
height
Any of:
number
<= 99999.99
id
image_thumb_url
image_url
Any of:
string format: uri
<= 2048 characters
is_composite
is_gift_card
length
Any of:
number
<= 99999.99
loyalty_amount
Any of:
integer
<= 900719925474
name
string
>= 1 characters <= 85 characters
purchase_account_code
Any of:
string
<= 50 characters
retail_price
integer
<= 900719925474
sales_account_code
Any of:
string
<= 50 characters
sku
suppliers
Array<object>
object
id
string
is_primary
boolean
supplier_code
Any of:
string
<= 100 characters
supplier_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
supplier_name
string
tags
Array<object>
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
name
string
updated_at
variant_attributes
Array<object>
object
id
string
name
required
string
>= 1 characters <= 50 characters
position
required
integer
>= 1 <= 3
variant_options
Array
variant_parent_id
version
Any of:
integer
<= 9007199254740991
weight
Any of:
number
<= 99999.99
weight_unit
Any of:
string
Allowed values: g kg lb oz
width
Any of:
number
<= 99999.99

Responses

Section titled “Responses”

200

Section titled “200”

Update a product

Media typeapplication/json
object
data
required
object
active
required
boolean
brand_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
category_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
codes
required
Array<object>
object
code
required
string
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
type
required
string
components
required
Array<object>
object
product_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
quantity
required
integer
>= -9007199254740991 <= 9007199254740991
created_at
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
description
required
string | null
dimension_unit
required
string | null
has_inventory
required
boolean
has_variants
required
boolean
height
required
number | null
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
image_thumb_url
required
string | null
image_url
required
string | null
is_composite
required
boolean
is_gift_card
required
boolean
length
required
number | null
loyalty_amount
required
Any of:

The loyalty amount earned on sale. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
name
required
string
purchase_account_code
required
string | null
retail_price
required

The retail price. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
sales_account_code
required
string | null
sku
required
string
suppliers
required

Live supplier links for this product. Never carries supply_price; use the admin UI or an export for cost data.

Array<object>
object
id
required

This supplier link’s own id, not the supplier’s id. Distinct from supplier_id below.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
is_primary
required

Whether this is the product’s primary supplier.

boolean
supplier_code
required

This retailer’s own code for the product at this supplier, if set.

string | null
supplier_id
required

The linked supplier’s id.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
supplier_name
required

The supplier name as of this document.

string
tags
required

Tags attached to this product, with names.

Array<object>
object
id
required

The tag’s own id, usable to reference it elsewhere.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
name
required

The tag name as of this document.

string
updated_at
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
variant_attributes
required

Present on a variant parent product; empty on a variant child or an ordinary product.

Array<object>
object
id
required

The variant attribute’s id. A variant child’s variant_options reference it as attribute_id.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
name
required

The attribute name, for example Size or Colour.

string
position
required

Display order among this product’s variant attributes.

integer
>= -9007199254740991 <= 9007199254740991
variant_options
required
Array<object>
object
attribute_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
attribute_name
required
string
value
required
string
variant_parent_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
version
required

Opaque delta-sync version. Increases with every change to this document: its own fields, and the addition, removal, or edit of a code, tag link, supplier link, variant option, variant attribute, or component, including when an attached tag or supplier is itself renamed. Use it to detect updates.

string
weight
required
number | null
weight_unit
required
string | null
width
required
number | null
Examplegenerated
{
  "data": {
    "active": true,
    "brand_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "category_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "codes": [
      {
        "code": "example",
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "type": "example"
      }
    ],
    "components": [
      {
        "product_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "quantity": 1
      }
    ],
    "created_at": "2026-04-15T12:00:00Z",
    "description": "example",
    "dimension_unit": "example",
    "has_inventory": true,
    "has_variants": true,
    "height": 1,
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "image_thumb_url": "example",
    "image_url": "example",
    "is_composite": true,
    "is_gift_card": true,
    "length": 1,
    "loyalty_amount": 1,
    "name": "example",
    "purchase_account_code": "example",
    "retail_price": 1,
    "sales_account_code": "example",
    "sku": "example",
    "suppliers": [
      {
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "is_primary": true,
        "supplier_code": "example",
        "supplier_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "supplier_name": "example"
      }
    ],
    "tags": [
      {
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "name": "example"
      }
    ],
    "updated_at": "2026-04-15T12:00:00Z",
    "variant_attributes": [
      {
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "name": "example",
        "position": 1
      }
    ],
    "variant_options": [
      {
        "attribute_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "attribute_name": "example",
        "value": "example"
      }
    ],
    "variant_parent_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "version": "example",
    "weight": 1,
    "weight_unit": "example",
    "width": 1
  }
}

default

Section titled “default”

An error response.

Media typeapplication/json
object
error
required
object
code
required

A machine-readable error code, e.g. VALIDATION_FAILED.

string
Allowed values: UNAUTHORIZED PLAN_REQUIRED INSUFFICIENT_SCOPE NOT_FOUND VALIDATION_FAILED CONFLICT STALE_VERSION RATE_LIMITED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS IMAGE_FETCH_FAILED UNPROCESSABLE INTERNAL RETAILER_CANCELLED RETAILER_SUSPENDED RETAILER_NOT_FOUND TRIAL_DECISION_REQUIRED PLAN_USERS_EXCEEDED RETAILER_PAUSED PRODUCT_LIMIT_REACHED NOT_STOCK_TRACKED REASON_DIRECTION_MISMATCH REASON_NOT_ALLOWED INSUFFICIENT_STOCK OUTLET_DELETED
fields
Array<object>
object
field
required
string
message
required
string
message
required

A plain-English sentence describing what went wrong.

string
Example
{
  "error": {
    "code": "UNAUTHORIZED"
  }
}