Upcoming changes (unstable)

Not final: these changes may still move before the next dated release.

From 2026-07 to unstable. 4 breaking, 0 caution, 35 compatible. All releases

Surface

REST MCP Webhooks

Impact

⚠ Breaking change · 4 ! Check your integration · 0 ✓ No action needed · 35

Breaking

Category

# The "childrens" property of categories is renamed "children". Read and write "children"; older versions keep "childrens".

RESTMCPWebhooks Action required

The rename also applies to embedded categories, such as the ones returned with ?expand=children.

• ⚠ Breaking change REST Property childrens removed (read)
  Before: array of object | string (iri-reference), optional, scopes: categories:read
  Affects 20 operations

  Path	GET	POST	PATCH
  /api/categories	GET	POST	-
  /api/categories/{id}	GET	-	PATCH
  /api/products	GET	POST	-
  /api/products/{id}	GET	-	PATCH
  /api/products/{productId}/variants	GET	POST	-
  /api/products/{productId}/variants/{variantId}	GET	-	PATCH
  /api/purchase_offers	GET	POST	-
  /api/purchase_offers/{id}	GET	-	PATCH
  /api/sale_offers	GET	POST	-
  /api/sale_offers/{id}	GET	-	PATCH

• ⚠ Breaking change REST Property childrens removed (write)
  Before: array of string (iri-reference), optional, scopes: categories:read
  Affects 2 operations

  Path	POST	PATCH
  /api/categories	POST	-
  /api/categories/{id}	-	PATCH

• ⚠ Breaking change MCP Property items[].childrens removed (read)
  Before: array of string (iri-reference), optional, scopes: categories:read
  Affects 1 tool

  • list_categories
• ⚠ Breaking change Webhooks Property childrens removed (read)
  Before: array of object | string (iri-reference), optional, scopes: categories:read
  Affects 3 topics

  • product/created
  • product/deleted
  • product/updated
• ✓ No action needed REST Property children added (read)
  After: array of object | string (iri-reference), optional, scopes: categories:read
  Affects 20 operations

  Path	GET	POST	PATCH
  /api/categories	GET	POST	-
  /api/categories/{id}	GET	-	PATCH
  /api/products	GET	POST	-
  /api/products/{id}	GET	-	PATCH
  /api/products/{productId}/variants	GET	POST	-
  /api/products/{productId}/variants/{variantId}	GET	-	PATCH
  /api/purchase_offers	GET	POST	-
  /api/purchase_offers/{id}	GET	-	PATCH
  /api/sale_offers	GET	POST	-
  /api/sale_offers/{id}	GET	-	PATCH

• ✓ No action needed REST Property children added (write)
  After: array of string (iri-reference), optional, scopes: categories:read
  Affects 2 operations

  Path	POST	PATCH
  /api/categories	POST	-
  /api/categories/{id}	-	PATCH

Compatible

AttributeDefinition

# Endpoint DELETE /api/attribute_definitions/{id} added

REST ✓ No action needed

• After: scopes: categories:read and categories:write
  Affects 1 operation

  Path	DELETE
  /api/attribute_definitions/{id}	DELETE

# Endpoint GET /api/attribute_definitions added

REST ✓ No action needed

• After: scopes: categories:read
  Affects 1 operation

  Path	GET
  /api/attribute_definitions	GET

# Endpoint GET /api/attribute_definitions/{id} added

REST ✓ No action needed

• After: scopes: categories:read
  Affects 1 operation

  Path	GET
  /api/attribute_definitions/{id}	GET

# Endpoint PATCH /api/attribute_definitions/{id} added

REST ✓ No action needed

• After: scopes: categories:read and categories:write
  Affects 1 operation

  Path	PATCH
  /api/attribute_definitions/{id}	PATCH

# Endpoint POST /api/attribute_definitions added

REST ✓ No action needed

• After: scopes: categories:read and categories:write
  Affects 1 operation

  Path	POST
  /api/attribute_definitions	POST

AttributeOption

# Endpoint DELETE /api/attribute_options/{id} added

REST ✓ No action needed

• After: scopes: categories:read and categories:write
  Affects 1 operation

  Path	DELETE
  /api/attribute_options/{id}	DELETE

# Endpoint GET /api/attribute_definitions/{definitionId}/options added

REST ✓ No action needed

• After: scopes: categories:read
  Affects 1 operation

  Path	GET
  /api/attribute_definitions/{definitionId}/options	GET

# Endpoint GET /api/attribute_options/{id} added

REST ✓ No action needed

• After: scopes: categories:read
  Affects 1 operation

  Path	GET
  /api/attribute_options/{id}	GET

# Endpoint PATCH /api/attribute_options/{id} added

REST ✓ No action needed

• After: scopes: categories:read and categories:write
  Affects 1 operation

  Path	PATCH
  /api/attribute_options/{id}	PATCH

# Endpoint POST /api/attribute_definitions/{definitionId}/options added

REST ✓ No action needed

• After: scopes: categories:read and categories:write
  Affects 1 operation

  Path	POST
  /api/attribute_definitions/{definitionId}/options	POST

Category

# Property attributes added (read)

REST ✓ No action needed

• After: array of string (iri-reference), optional, scopes: categories:read
  Affects 20 operations

  Path	GET	POST	PATCH
  /api/categories	GET	POST	-
  /api/categories/{id}	GET	-	PATCH
  /api/products	GET	POST	-
  /api/products/{id}	GET	-	PATCH
  /api/products/{productId}/variants	GET	POST	-
  /api/products/{productId}/variants/{variantId}	GET	-	PATCH
  /api/purchase_offers	GET	POST	-
  /api/purchase_offers/{id}	GET	-	PATCH
  /api/sale_offers	GET	POST	-
  /api/sale_offers/{id}	GET	-	PATCH

# Property attributes added (write)

REST ✓ No action needed

• After: array of string (iri-reference), optional, scopes: categories:read
  Affects 2 operations

  Path	POST	PATCH
  /api/categories	POST	-
  /api/categories/{id}	-	PATCH

# Property items[].attributes added (read)

MCP ✓ No action needed

• After: array of string (iri-reference), optional, scopes: categories:read
  Affects 1 tool

  • list_categories

# Property items[].children added (read)

MCP ✓ No action needed

• After: array of string (iri-reference), optional, scopes: categories:read
  Affects 1 tool

  • list_categories

# Property attributes added (read)

Webhooks ✓ No action needed

• After: array of string (iri-reference), optional, scopes: categories:read
  Affects 3 topics

  • product/created
  • product/deleted
  • product/updated

# Property children added (read)

Webhooks ✓ No action needed

• After: array of object | string (iri-reference), optional, scopes: categories:read
  Affects 3 topics

  • product/created
  • product/deleted
  • product/updated

ImportType

# Endpoint GET /api/imports/types/{type}/sample added

REST ✓ No action needed

• After: scopes: imports:read
  Affects 1 operation

  Path	GET
  /api/imports/types/{type}/sample	GET

MetaobjectDefinitionCount

# Endpoint GET /api/metaobject_definitions/entry_counts added

REST ✓ No action needed

• After: scopes: metaobjects:read
  Affects 1 operation

  Path	GET
  /api/metaobject_definitions/entry_counts	GET

# Endpoint GET /api/metaobject_definitions/{definitionId}/entry_count added

REST ✓ No action needed

• After: scopes: metaobjects:read
  Affects 1 operation

  Path	GET
  /api/metaobject_definitions/{definitionId}/entry_count	GET

Product

# Property attributes added (read)

REST ✓ No action needed

• After: array of object, optional
  Affects 16 operations

  Path	GET	POST	PATCH
  /api/products	GET	POST	-
  /api/products/{id}	GET	-	PATCH
  /api/products/{productId}/variants	GET	POST	-
  /api/products/{productId}/variants/{variantId}	GET	-	PATCH
  /api/purchase_offers	GET	POST	-
  /api/purchase_offers/{id}	GET	-	PATCH
  /api/sale_offers	GET	POST	-
  /api/sale_offers/{id}	GET	-	PATCH

# Property attributes added (write)

REST ✓ No action needed

• After: array of object, optional
  Affects 2 operations

  Path	POST	PATCH
  /api/products	POST	-
  /api/products/{id}	-	PATCH

# Property attributes added (read)

MCP ✓ No action needed

• After: array of object, optional
  Affects 1 tool

  • get_product

# Property items[].attributes added (read)

MCP ✓ No action needed

• After: array of object, optional
  Affects 1 tool

  • list_products

# Property attributes added (read)

MCP ✓ No action needed

• After: array of object, optional
  Affects 1 tool

  • update_product

# Property attributes added (write)

MCP ✓ No action needed

• After: array of object, optional
  Affects 1 tool

  • update_product

# Property attributes added (read)

Webhooks ✓ No action needed

• After: array of object, optional
  Affects 3 topics

  • product/created
  • product/deleted
  • product/updated

Product Variant

# Endpoint GET /api/variants added

REST ✓ No action needed

• After: scopes: products:org:read, or products:read
  Affects 1 operation

  Path	GET
  /api/variants	GET

ResolvedMetafield

# Endpoint GET /api/{ownerResource}/{ownerId}/resolved-metafields added

REST ✓ No action needed

• After: scopes: metafields:read
  Affects 1 operation

  Path	GET
  /api/{ownerResource}/{ownerId}/resolved-metafields	GET

WebhookSubscription

# Endpoint DELETE /api/webhook_subscriptions/{id} added

REST ✓ No action needed

• After: scopes: webhooks:read and webhooks:write
  Affects 1 operation

  Path	DELETE
  /api/webhook_subscriptions/{id}	DELETE

# Endpoint GET /api/webhook_subscriptions added

REST ✓ No action needed

• After: scopes: webhooks:read
  Affects 1 operation

  Path	GET
  /api/webhook_subscriptions	GET

# Endpoint GET /api/webhook_subscriptions/{id} added

REST ✓ No action needed

• After: scopes: webhooks:read
  Affects 1 operation

  Path	GET
  /api/webhook_subscriptions/{id}	GET

# Endpoint PATCH /api/webhook_subscriptions/{id} added

REST ✓ No action needed

• After: scopes: webhooks:read and webhooks:write
  Affects 1 operation

  Path	PATCH
  /api/webhook_subscriptions/{id}	PATCH

# Endpoint POST /api/webhook_subscriptions added

REST ✓ No action needed

• After: scopes: webhooks:read and webhooks:write
  Affects 1 operation

  Path	POST
  /api/webhook_subscriptions	POST