Catalogue structure

Overview

These endpoints read and change the structure around the products: brands, product labels, the category tree and which products are featured on top of a category. Each write is the MCP tool of the same name over HTTP: the data equals the structured result, the change is logged with the token (name, id, channel api) and the calls count on the write limit. The path names the subject and must not be repeated in the body. Bodies are JSON objects, at most 65536 bytes. The tools are described in Catalogue write tools.

• Scopes. Reading needs commerce.read. Brands, labels and putting a product in or out of a category need commerce.write.products (edit permission Products). Creating, renaming and moving categories and featured products need commerce.write.collections (Categories). The two scopes are separate: a products token cannot edit the tree.
• Result. {"data": {...}} with the subject plus changed (false when nothing differed) and changes ({field: {old, new}}).
• PIM. Brand names are owned by the PIM when a PIM-linked product uses the brand. Labels and category placements by the shop itself are always editable; detaching a placement the PIM import made is 422 field_owned_by_pim.

Reference lists

Four lists give the ids the writes take. They need commerce.read only.

curl -s -H "Authorization: Bearer $COMMERCE_API_TOKEN" \
  "https://<your-shop-domain>/api/v1/brands?limit=50"

{
  "data": [
    {"id": 7, "name": "Bosch", "slug": "bosch", "url": "https://<your-shop-domain>/merken/bosch",
     "logo_url": null, "product_count": 12, "pim_managed": false}
  ],
  "meta": {"next_cursor": null, "has_more": false}
}

Brands

Needs commerce.write.products. Result of the first four and the two logo endpoints: brand (id, name, slug, url, logo_url, product_count, pim_managed), changed, changes; delete answers brand_id, deleted, changed, changes. Assign a brand to a product by name with PATCH /products/{id}.

curl -sS -X PUT "https://<your-shop-domain>/api/v1/brands/7/logo" \
  -H "Authorization: Bearer $COMMERCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://images.example.com/bosch.png", "alt": "Bosch logo"}'

Labels

Needs commerce.write.products. Putting labels on a product is PUT /products/{id}/labels (see Product writes). Result: label (id, name, slug, tone, position, product_count), changed, changes (a move names position:{label id} for both labels); delete answers label_id, deleted, changed, changes.

Categories

Read the tree with GET /categories. Result of the tree writes: collection (id, slug, name, parent_id, position, description), changed, changes. The placement endpoints answer product_id, collection, in_collection, changed, changes. A category of the hidden PIM import tree, or a parent there, is 422; an unknown category or product is 404.

curl -sS -X POST "https://<your-shop-domain>/api/v1/categories" \
  -H "Authorization: Bearer $COMMERCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hanglampen", "parent_id": 30}'

curl -sS -X PUT "https://<your-shop-domain>/api/v1/categories/31/products/101" \
  -H "Authorization: Bearer $COMMERCE_API_TOKEN"

Featured products in a category

Featured products sort above all other products of a category listing. All three need commerce.write.collections and the product must already be in the category (PUT .../products/{productId}), otherwise 422. Result: product_id, collection, featured, featured_product_ids (top first, at most 100), changed, changes (position:{product id}).

Errors