API: Products

What It Does

The Products API provides RPCs for updating individual products and applying bulk updates across many products in a single request.

Who It’s For

Developers building integrations that sync product catalogues, apply attribute corrections, or automate product data management.

update_product

What it does

Updates a single product’s attributes by applying a JSON patch. The patch is merged server-side — only included fields are changed. Attribute values are validated against the brand’s DPP schema.

Request

1
{
2
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
3
  "_product_id": "p1a2c3d4-0000-0000-0000-000000000001",
4
  "_patch": {
5
    "commercial_status": "ACTIVE",
6
    "attributes": {
7
      "weight_kg": 1.5,
8
      "country_of_origin": "GB"
9
    }
10
  }
11
}

Response (example)

1
{
2
  "ok": true,
3
  "product_id": "<uuid>",
4
  "validation_warnings": []
5
}

Errors (examples)

• Not authenticated — request has no valid JWT.
• Forbidden — caller does not have sufficient access for this operation.
• Invalid input — request is malformed or cannot be processed.

bulk_update_products

What it does

Applies patches to multiple products in a single synchronous request. Each product is processed independently — a failure on one row does not roll back others.

Request

1
{
2
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
3
  "_patches": [
4
    {
5
      "product_id": "p1a2c3d4-0000-0000-0000-000000000001",
6
      "patch": { "attributes": { "country_of_origin": "FR" } }
7
    },
8
    {
9
      "product_id": "p1a2c3d4-0000-0000-0000-000000000002",
10
      "patch": { "attributes": { "country_of_origin": "DE" } }
11
    }
12
  ]
13
}

Response (example)

1
{
2
  "ok": true,
3
  "results": [
4
    {
5
      "product_id": "<uuid>",
6
      "status": "success",
7
      "error_message": null,
8
      "validation_warnings": []
9
    }
10
  ]
11
}

Errors (examples)

• Not authenticated — request has no valid JWT or the token has expired.
• Forbidden — caller does not have admin access to the specified brand.
• Invalid input — patches array is malformed or contains invalid field values.

Limits & Notes

• Both RPCs require authentication with an admin role for the specified brand.
• Attribute patches are validated against the brand’s DPP schema.
• bulk_update_products processes all items synchronously; for larger workloads, use the asynchronous bulk update job workflow.
• Identifier fields (SKU, GTIN, EAN, UPC) cannot be updated via product patches — use the Identifiers API instead.

FAQ

Can I create a product via this API? Product creation is handled via the import workflow. update_product is for updating existing products.

Is the bulk update synchronous or asynchronous? bulk_update_products is synchronous. For large-scale updates with progress tracking, use the async job workflow documented in Bulk Updates.