Auth and rate limiting
UCP traffic to Shopify's MCP servers is classified into three tiers based on how your agent identifies itself. Each tier has different capabilities and rate-limiting allowances.
Anchor to Traffic tiersTraffic tiers
Each tier reflects how much Shopify knows about the agent making the request. Stronger identification means higher rate limits and access to more sensitive tools.
The following table summarizes what each tier can do. Subsequent sections describe how to qualify for each tier.
| Auth type | Catalog tools | Cart tools | Checkout tools | complete_checkout | Order tools |
|---|---|---|---|---|---|
| Token | Yes, and provides personalized search results when presenting a buyer-linked token | Yes | Yes, and applies any automatic discounts when presenting a buyer-linked token | When the token is granted permission to complete purchases | Yes, with the read_global_api_orders scope |
| Signed | Yes | Yes | Yes | No | No |
| Anonymous | Yes | Yes | Yes | No | No |
Rate-limit guidance:
- Rate limits scale with identification. The Token tier gets the highest limits, Signed gets lower limits, and Anonymous gets the lowest.
- Checkout MCP is rate-limited more strictly than Cart MCP at every tier. Use Cart MCP to iterate on line items, refine context, and estimate totals, and reserve Checkout MCP for buyers who are ready to purchase.
- Order MCP is for on-demand reads. Reserve
get_orderfor buyer-initiated views and reconciling missed webhooks. For proactive lifecycle updates, subscribe to Order webhooks.
Anchor to Global Catalog rate limitsGlobal Catalog rate limits
Authenticated requests to the Global Catalog endpoint, https://catalog.shopify.com/api/ucp/mcp, are rate limited for each API client. The default limit is 5 requests each second for each API client.
The following Catalog tools share the same quota:
These limits apply only to the Global Catalog. Storefront Catalog requests to a store's /api/ucp/mcp endpoint use the same tool names, but they're rate limited separately for each store.
Unauthenticated requests are rate limited for each IP address and also share a single limit with all other unauthenticated traffic, so their throughput isn't guaranteed. Don't use unauthenticated requests for production traffic.
If your integration needs a higher request rate, then contact your Shopify representative or partner contact. If you don't have a Shopify contact, then go to the Shopify Help Center. Include your API client, expected traffic, and business reason.
Anchor to TokenToken
Agents authenticating with a credential issued through Dev Dashboard, such as a global API token, customer accounts token, or shop access token.
- How to authenticate: JWT passed with Bearer token authentication. See Authenticate your agent for a working example.
- What you can do: Access cart, checkout, and order tools at the highest rate limits. Call
complete_checkoutwhen your token has been granted the required permission to complete purchases on the shop's behalf. Callget_orderwhen your token includes theread_global_api_ordersscope. Order access is restricted to orders placed through your agent. - What you must send: A
Shopify-Buyer-IPheader on everytools/callrequest to a merchant's UCP MCP endpoint.
Anchor to Buyer-linked tokensBuyer-linked tokens
Buyer-linked tokens carry a signed-in Shop customer's identity. Pass a buyer-linked token to make your calls buyer-aware. For example, use one to return personalized search results from the Global Catalog, or to sign in the buyer to the merchant store.
If your agent already holds a Shop access token for a signed-in customer, it can exchange that token for a buyer-linked token without a second browser redirect using the UCP delegated identity provider (IdP) flow with Shop as the IdP.
Anchor to SignedSigned
Agents that haven't created an API key but have implemented HTTP signatures per the UCP specification.
- How to authenticate: HTTP Message Signatures per RFC 9421 using ECDSA P-256. Shopify verifies the signature against the public key published in your agent's well-known UCP profile. See the UCP signatures specification for how to construct signed requests.
- What you can do: Access cart and checkout tools at lower rate limits than the Token tier.
complete_checkoutand order tools aren't available at this tier.
Anchor to AnonymousAnonymous
Agents that haven't identified themselves to Shopify.
- How to authenticate: No credentials or signatures provided. Send the request without an
Authorizationheader or signature headers. - What you can do: Access catalog, cart, and checkout build/edit tools at the lowest rate limits.
complete_checkoutand order tools aren't available at this tier.
Anchor to Buyer IP headerBuyer IP header
A Token-tier request acts for a specific buyer, so Shopify needs that buyer's IP address. Send it in the Shopify-Buyer-IP header on every tools/call request to a merchant's UCP MCP endpoint, https://{shop-domain}/api/ucp/mcp. That endpoint serves Storefront Catalog, Cart MCP, Checkout MCP, and Order MCP. Global Catalog requests don't need the header.
- What to send: The IPv4 or IPv6 address of the buyer your agent is acting for.
- When it's required: On every Token-tier
tools/call, including read-only calls such asget_cartandget_order. Discovery requests such asinitializeandtools/listdon't need it, and neither do Signed or Anonymous requests. - When you don't have one: There's no placeholder value, and Shopify doesn't fall back to the address your agent connects from. If your agent makes a Token-tier
tools/callwhen no buyer is present, such as from a scheduled job, then the call fails.
If the header is missing or isn't a valid IP address, then Shopify rejects the request with HTTP 422:
Anchor to Rate-limit responsesRate-limit responses
When your traffic exceeds the allowance for its tier, Shopify returns HTTP 429 with a Retry-After header. For merchant UCP MCP endpoints, the response body looks like this:
Wait the number of seconds in Retry-After, then retry with exponential backoff and jitter. When you retry a call that takes meta["idempotency-key"], such as complete_checkout, reuse the key from the original request so the retry doesn't repeat the action.
On merchant UCP MCP endpoints, allowances differ by tier and by tool and can change, so read Retry-After from each 429 response instead of hard-coding a request budget.
