> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Catalyst version 1.12.0 release notes

> Catalyst 1.12.0 proxies the UCP agentic commerce endpoints through to BigCommerce so agents can reach them on the storefront domain, and stops the correlation ID header from making every Next.js Data Cache lookup miss.

Catalyst 1.12.0 is a minor release. It serves the Universal Commerce Protocol (UCP) endpoints on the storefront's public domain by proxying them to BigCommerce, and stops `X-Correlation-ID` from making every Next.js Data Cache lookup miss. For a full list of Catalyst changes, see the [changeset on GitHub](https://github.com/bigcommerce/catalyst/blob/canary/core/CHANGELOG.md#1120).

## UCP endpoints on the storefront domain

Agents discover and call [UCP](https://ucp.dev/) on the storefront's public domain, but the protocol is served by the BigCommerce platform rather than by Catalyst. Catalyst now proxies both UCP surfaces through to BigCommerce:

* `/.well-known/ucp` — the discovery document. It was previously locale-redirected, like any other unmatched path.
* `/api/ucp/*` — the checkout endpoints, for every HTTP method. These previously returned a 404.

Only the headers the [UCP REST transport spec](https://ucp.dev/2026-04-08/specification/checkout-rest/) defines are passed in either direction, so nothing outside the spec is exchanged with a separate origin. No new environment variable is required.

Catalyst serves trailing-slash URLs, so the trailing slash is stripped before a UCP path is proxied. The platform answers a trailing slash with a 307 back to the bare path, which an agent resolves against the storefront domain and sends straight back, so the call would never land. Agents still follow Catalyst's own `trailingSlash` redirect on the way in.

## Upgrading a customized proxy

An unmodified `proxy.ts` picks up the UCP proxy with the rest of the upgrade. If you have customized it, make two changes:

1. Add `withUcpProxy` as the first argument to `composeProxies`.
2. Add `/api/ucp/:path*` to `config.matcher`.

## Correlation ID and the Next.js Data Cache

`X-Correlation-ID` is no longer sent on cacheable GraphQL requests, where it was making every Data Cache lookup miss.

The correlation ID is a fresh `crypto.randomUUID()` per request, memoized for the duration of a render by `React.cache`. Next.js builds its Data Cache key from the fetch URL, method, body, and headers, so a header that changes on every request produces a unique key on every request. Fetches configured with `next: { revalidate }` could therefore never hit: each one missed, went out to the BigCommerce GraphQL API, and wrote a new entry that nothing would ever read again. On a product page that is roughly 12 queries per page view, at the full uncached render cost every time, plus unbounded growth in the data cache.

Next.js already strips `traceparent` and `tracestate` from the cache key for this reason, but it can only do that for headers it knows about.

The correlation ID now follows the same rule as `X-Forwarded-For` and `True-Client-IP` in the same hook: it is attached only when `fetchOptions.cache` is `no-store` or `no-cache`. Those requests are uncacheable by construction, so there is no cache key to pollute, and they are the per-customer requests where a correlation ID is most useful for tracing. Cacheable requests now share a stable key and hit the Data Cache as intended.

## Release tags

* [**@bigcommerce/catalyst-core@1.12.0**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-core%401.12.0)
* [**@bigcommerce/create-catalyst@2.0.6**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcreate-catalyst%402.0.6)

Latest stable:

* [**@bigcommerce/catalyst-core@latest**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-core%40latest)
* [**@bigcommerce/catalyst-makeswift@latest**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-makeswift%40latest)