Changelog

Choose Rotate from the key's menu or its details in the dashboard. The new secret is shown once. A grace period of 0 revokes the old key at once. Revoked, expired and already rotated keys cannot be rotated.

Review reads and rich snippets carry review content, so they follow the Reviews plan. Workspaces whose plan includes Reviews see no change. See Rich snippets.

The three endpoints are GET /v1/inbox, GET /v1/posts/{id} and GET /v1/collections/{id}/posts. Before, the inbox and single post endpoints allowed 5 requests per second per key. Since September 24, every key also has a safety limit of 200 requests per second, with bursts of up to 400, across all API v1 data routes. See API v1 rate limits.

A preset is stored as the preset itself, not as the scopes that exist today, so a read-only key gains read access to new resources as they ship. Custom scope lists stay explicit, and existing credentials keep the scopes they had. A changed scope applies from the next request; MCP clients see a changed tool list after they reconnect.

See secret key scopes.

Before, the metadata was only at /.well-known/oauth-authorization-server, and spec-following clients such as Claude Code could fail to connect. Both locations now answer. See MCP for the discovery documents.

Buyer details are create-only: once loyalty processing has used an order's buyer, an API update can no longer reassign or unlink it. Before this change, fulfillment_status defaulted to PENDING when omitted.

Migration

Send buyer with POST /v2/orders, and remove it from PATCH /v2/orders/{id} requests, which now fail validation when they include it. Send fulfillment_status on create when you want a specific status rather than the one the lines imply.

include=products returns the tagged products localized to a market, which it then requires, and needs products:read. include=profiles returns the profiles the posts reference and needs profiles:read; profile fields are secret-key data, so keep them on your server. label_match is any by default and needs label_id.

GET /v1/posts requires market, filters by product_ref, gallery_id, profile_id and label_id among others, and pages with a cursor, up to 50 posts per page. Every Storefront operation now shares one limit per publishable key: 20 requests per second, with bursts of up to 40.

See Custom UGC and rate limits.

Every request counts once, whatever its page size. The per-key budgets and the separate costs for light, normal and heavy reads and for order writes are gone, so creating more keys no longer adds capacity. See Rate limits.

Migration

If you read data.rate_limits from GET /v2/me, use reads and writes instead of cheap_read, normal_read, expensive_read, expensive_read_workspace and high_risk_mutation. If you spread traffic across several keys for more capacity, plan for the shared workspace limit and back off on 429 using Retry-After.

Find the tools with tool-search, for example brandkit.get. Since September 30, changes go to a shared draft: brandkit.preview renders it, and brandkit.publish (or the BrandKit editor) makes it live. See BrandKit changes on the MCP page.

ingestion_mode is live by default, which keeps the behaviour new orders always had. Send historical for orders that already happened; such an order stays out of automatic purchase incentives even after later live updates. PATCH /v2/orders/{id} also accepts ingestion_mode.

Clients see a short tool list that stays the same as the server gains tools. tool-search returns matching tools with their input schemas; execute-tool runs one, and execute-batch runs independent reads together.

Migration

Clients that pick tools from the list need no change. If a prompt, script or client configuration calls an analytics tool by its old name, such as run-report, call tool-search to find it and run analytics.run-report through execute-tool instead. The current tools are listed on MCP.

Positions are stored as percentages and were checked against the published 0 to 1 range instead of being converted, so only values of exactly 0 or 1 survived. They are now divided by 100. No change is needed on your side; tagged_products simply carries the positions it always promised.

Reads take market for localized text and include for related resources and original content. GET /v2/orders/{order_id}/review-status returns the reviews an order already has and what its lines can still be reviewed for. Imports create a pending review and take an Idempotency-Key; see Idempotency. Grant the new scopes as described in secret key scopes.

Pass market for localized text and include=localization for the original content beside it. Review responses are never cached; see Caching.

Use the label ids to filter posts by label. See Includes in the API v1 guide.

Grant labels:read to read labels and labels:write to manage them; see secret key scopes. Filtering posts by label is described in Filtering.

Both events use the same signed envelope as every other webhook. See Set up a webhook.

The new triggers are upload.completed, tier.earned, reward.fulfilled, tier.evaluation-approaching and points.expiration-approaching. Deliveries use the same signed envelope as every other webhook; set one up as described in Set up a webhook.

The compatibility check rejects removed paths, operations, responses and properties, newly required parameters or body fields, and stricter request schemas. New operations, optional fields and looser request rules stay compatible.

The release also settled how the APIs are called:

• API v2 authenticates with Authorization: Bearer and a secret key (cev_sk_…); see Authentication.
• Resources have stable public ids with a type prefix, such as prf_ for profiles and pst_ for posts.
• POST /v2/orders and PATCH /v2/orders/{id} take an Idempotency-Key header. An identical retry within seven days replays the first response; reusing the key for a different request returns 409.
• The Storefront API's rich snippet operation moved under /v1, at GET /v1/products/{productRef}/rich-snippet.

The envelope no longer has apiVersion, payloadVersion, context or the flow block with run and attempt ids. data holds the public resources the event concerns, and origin.flow names the Flow that sent it, so you can tell two Flows on one endpoint apart.

Migration

Read the event from the new envelope: type for what happened, data for the resources and created_at for when. Handle product-review.submitted and company-review.submitted where you handled review.submitted; a Flow now triggers on one of the two. The envelope is described on Webhooks.

Each delivery is a POST signed with Standard Webhooks⁠ headers (webhook-id, webhook-timestamp, webhook-signature). The launch triggers were order.fulfilled, order.delivered and review.submitted. A retry sends the same event with the same webhook-id; a replay creates a new delivery to the destination's current URL. During a signing secret rotation, deliveries carry a signature for each secret.

Start with Webhooks and Verify signatures.

A client that requests no scopes still gets read access, now as analytics:read. Only clients that list scopes by name are affected.

Migration

Request analytics:read for queries and reports, and add analytics:write when the client should create or update reports and dashboards. Remove mcp:tools and mcp:analytics:write from the client's configuration.

Create a key in the dashboard, pick its scopes and, optionally, when it expires. The secret is shown once. On API v1, post and inbox requests need posts:read and the members endpoint needs members:read. Legacy keys can no longer be created.

See secret key scopes and API v1 authentication.

New tools include create-report, update-report, list-dashboards and get-dashboard, next to the query tools. Report and dashboard writes need explicit write consent when you authorize the client. Report runs, queries and writes are limited to 20 calls per minute.

Access tokens last 15 minutes. Refresh tokens rotate on every use and expire 30 days after the latest refresh, so a client that keeps using its connection does not have to sign in again. Reusing a refresh token that was already rotated is rejected.

Clients should read the advertised Protected Resource Metadata and send the MCP endpoint as the OAuth resource. Client implementer details are on MCP.

The first tools search saved analytics reports (search-reports), read a report (get-report), run it for a date range (run-report) and list the metric catalog (list-metrics). Access is scoped to the workspace you authorize. See MCP to connect a client.