---
title: "Product Catalog API: Breaking Changes to Variant and Product Endpoints"
slug: "product-catalog-api-breaking-changes-to-variant-and-product-endpoints"
updated: 2026-09-03T08:18:19Z
published: 2026-09-03T08:18:19Z
canonical: "docs.mapp.com/product-catalog-api-breaking-changes-to-variant-and-product-endpoints"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Catalog API: Breaking Changes to Variant and Product Endpoints

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

Until now, these calls failed with a 400 Bad Request when an ID contained special characters such as `;`, `/`, or `?`, because the ID was part of the URL path. The query parameter fixes this.

---

## What Is Changing

- **Single-ID calls now use 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 now has its own path.** The old call, `GET .../variants` without an ID, would otherwise have collided with the new single-variant call on the same path. It now uses `GET .../variants/bulk`.
- **Deleting all variants is now an explicit bulk call.** Until now, calling `DELETE .../variants/` without a variant ID deleted every variant in the catalog. The 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]
> Warning
> 
> Two old calls got no transition period. `GET .../variants` (listing/pagination) and `DELETE .../variants/` (delete all) stopped 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](https://docs.mapp.com/apidocs/product-catalog-api-api-reference) for the full list of old and new endpoints and for parameter details.

---

## Availability

This update is live for all Product Catalog API customers as of **2 September 2026**.