Pre-Announcement: Product Catalog API – Breaking Changes to Variant and Product Endpoints

  • 2 minute(s) read
Prev Next

On 2 September 2026, we're moving product and variant IDs from the URL path to a query parameter for single-ID calls in the Product Catalog API. This applies to every customer using these endpoints, not only those with special characters in their IDs.

Currently, these calls fail with a 400 Bad Request when an ID contains special characters such as ;, /, or ?, because the ID is part of the URL path. The query parameter fixes this.

This page is an advance notice so you can review the change and update your integration before it ships.

What Is Changing

  • Single-ID calls move to a query parameter. This covers the six endpoints that get, replace, partially update, or delete a variant, delete a variant's attributes, or list a product's variants. The ID moves from the URL path to a query parameter. Getting a variant, for example, changes from GET .../variants/{variantId} to GET .../variants?variantId={variantId}. The ID must be URL-encoded: probe;semi becomes probe%3Bsemi.

  • Listing and paginating all variants of a catalog moves to its own path. The old call, GET .../variants without an ID, would otherwise collide with the new single-variant call on the same path. It moves to GET .../variants/bulk instead.

  • Deleting all variants becomes an explicit bulk call. Until now, calling DELETE .../variants/ without a variant ID deleted every variant in the catalog. The new bulk endpoint, DELETE .../variants/bulk/all, has to be called deliberately, so a whole catalog can no longer be wiped by accident.

  • New: bulk search for variants. POST .../variants/bulk/search accepts up to 1,000 variant IDs in a single request and returns all matching variants, instead of one call per ID.

Warning

Two old calls get no transition period. GET .../variants (listing/pagination) and DELETE .../variants/ (delete all) both stop working on 2 September 2026, together with this release. Use GET .../variants/bulk and DELETE .../variants/bulk/all instead.

What You Need to Do

Update your integration to the query-parameter form before 2 October 2026. The old path-based endpoints (get, replace, partially update, and delete a variant; delete a variant's attributes; and list a product's variants) keep working until then, so nothing breaks immediately. After 2 October 2026, they are removed.

Your product and variant IDs themselves stay the same. Only how you pass them to these six endpoints is different.

See the updated Product Catalog API reference for the full list of old and new endpoints and for parameter details.

Availability

These changes go live on 2 September 2026. The updated API reference, including the full endpoint mapping, will be published at the same time.