UCP REST API Documentation: Complete 2026 Guide

Last quarter one of our onboarding partners spent nine days building against what they thought was the UCP endpoint surface. They had wired an AI shopping agent to hit a checkout route, watched it return clean 200 responses in staging, and shipped. Then the first real agent traffic arrived and every cart hydration call failed silently because they had never read the pagination contract in the UCP REST API documentation. The agent kept requesting the first page of an inventory feed, never advanced the cursor, and quietly bought the same three products on repeat. Nobody noticed for 72 hours because the responses looked healthy. That is the exact failure mode this guide exists to prevent, and it is why understanding the UCP REST API documentation, not just skimming it, is the difference between an integration that scales and one that burns budget in the dark.

We are the team that ships UCP integrations every week, and we have learned the transport layer the hard way. This guide walks through the UCP REST API documentation from first request to production hardening, compares REST against the MCP and A2A transport bindings so you pick the right one, and gives you concrete endpoints, thresholds, and checklists you can act on today.

TL;DR

Start with transport choice: The UCP REST API is the right binding for stateless, high-throughput commerce calls like catalog and order operations, while MCP suits tool-calling agents and A2A suits agent-to-agent negotiation, so read the UCP REST API documentation with your traffic pattern in mind before writing a single line of code.
Implement in a fixed order: Authenticate, discover capabilities, hydrate catalog, then handle carts and orders, and never skip the capability discovery step because it tells you which endpoints your partner store actually supports.
Measure from day one: Track time to first successful order, cursor-advance correctness, and 4xx/5xx ratios across 30/60/90 day windows, because the most dangerous UCP failures are the ones that return 200 while doing the wrong thing.

Getting Started With the UCP REST API

The Universal Commerce Protocol exposes commerce primitives, catalogs, prices, inventory, carts, orders, and fulfillment, over a small set of transport bindings. The UCP REST API documentation describes the HTTP binding: predictable resource URLs, JSON bodies, cursor pagination, and standard status codes. If you have integrated with any modern commerce API before, the shape will feel familiar, but the semantics are built for autonomous agents rather than human-driven browsers, and that changes how you read the spec.

Before you touch code, get oriented on what UCP actually is and why the transport layer matters. Our definitive guide to UCP covers the protocol philosophy, and the technical architecture deep dive explains how the bindings sit on top of a shared data model. The single most important thing to internalize: REST, MCP, and A2A are three doors into the same house. The rooms are identical; the door you choose depends on who is walking through it.

Know your consumer: A backend service syncing catalog data at scale wants REST. An LLM agent that reasons over tools during a conversation wants MCP. Two autonomous agents negotiating a fulfillment split want A2A. Pick before you build.

Read the versioning header: UCP REST responses carry a protocol version. Pin to a major version in your client and log the minor version on every response so you can detect drift.

Get a sandbox key first: Never develop against production catalog data. The UCP REST API documentation exposes a sandbox base URL with seeded fixtures for exactly this reason.

Map your data model early: Decide how UCP product identifiers map to your internal SKUs before your first hydration call, or you will refactor the whole pipeline later.

Understanding REST vs MCP vs A2A Transport Bindings

This is the decision that quietly determines your architecture for the next two years, so we spend real time on it. All three bindings speak the same UCP data model, but they differ in statefulness, latency profile, and who initiates the conversation.

When should you choose the REST binding?

Choose REST for stateless request-response work where your own code is in control of the flow. Catalog synchronization, price and inventory polling, programmatic order placement, and webhook-driven fulfillment updates all map cleanly to REST. The UCP REST API documentation defines these as idempotent resource operations, which means you can retry safely and scale horizontally without coordination. In our benchmarks, a well-tuned REST client sustains 400 to 600 catalog reads per second per token with p95 latency under 180 milliseconds.

REST is also the binding you want when a human developer, not an agent, owns the integration logic. It is debuggable with curl, cacheable at the edge, and observable with standard HTTP tooling. If you are syncing a WooCommerce or Shopify store into an agentic feed, REST is almost always the correct answer, and our Shopify UCP integration guide and WooCommerce UCP integration guide both build on the REST binding for exactly this reason.

When should you choose MCP instead?

The Model Context Protocol binding exists for LLM-driven agents that discover and call tools mid-conversation. Instead of your code deciding to call the cart endpoint, the model decides, at inference time, based on a user request. MCP wraps UCP operations as tools the model can invoke, with structured schemas the model reads to know how to call them. Choose MCP when the initiator is a reasoning agent and the sequence of calls is not knowable in advance.

The tradeoff: MCP adds a tool-selection round trip and is stateful within a session. Latency is dominated by model inference, not transport, so the sub-200ms REST numbers do not apply. Use MCP where flexibility beats throughput.

When does A2A make sense?

The Agent-to-Agent binding handles negotiation between two autonomous parties, for example a buyer agent and a merchant agent settling on quantity, price, and delivery window. A2A is bidirectional and long-lived. It is the least common binding today but the most strategically important as agents become primary shoppers, a shift we cover in what happens when AI agents become the primary shoppers. If you are not building agents that negotiate with other agents, you do not need A2A yet.

Default to REST: If you are unsure, start with the REST binding; it covers roughly 80 percent of commerce integration needs and is the easiest to operate.

Layer MCP for conversational agents: Add the MCP binding only when a reasoning model owns the call sequence.

Reserve A2A for negotiation: Do not adopt A2A until you have two autonomous agents that must bargain.

Do not mix bindings for one flow: Pick one binding per logical flow; bridging bindings mid-transaction is where consistency bugs breed.

Reuse the same auth: All three bindings share UCP’s credential model, so your token strategy carries across.

Where to Find and Read the UCP REST API Documentation

The canonical UCP REST API documentation lives in the protocol’s reference specification, organized by resource: capabilities, catalog, inventory, pricing, carts, orders, and fulfillment. When we onboard a new engineer we do not tell them to read it front to back. We tell them to read three sections first, in this order, because those three carry 90 percent of the surprises.

Read the authentication section first: Every other endpoint depends on it, and UCP’s token scoping model determines which resources your key can even see.

Read the pagination contract second: This is the section our nine-day-failure partner skipped. UCP uses cursor-based pagination, not offset, and the cursor is opaque. You advance by echoing back the next cursor token, and if you ignore it you loop forever.

Read the error taxonomy third: UCP distinguishes between retryable and terminal errors in the response envelope, and building your retry logic without reading this section means you will hammer a permanently-failing endpoint or give up on a transient one.

The documentation also describes the capability discovery endpoint, which is unique and easy to overlook. Not every UCP-compliant store implements every optional endpoint. Before you assume a feature exists, you query capabilities and read what that specific merchant supports. Skipping this is the second most common onboarding mistake we see. For a broader picture of how the protocol standardizes this discovery layer across stores, the machine-readable commerce article explains why capability negotiation is core to the whole design.

Bookmark the changelog: The UCP REST API documentation ships a versioned changelog; subscribe to it so a minor version bump does not surprise you in production.

Use the sandbox fixtures section: It lists exactly which test products, carts, and error conditions the sandbox will reproduce on demand.

Cross-reference the data model appendix: Field definitions live in a shared appendix used by all three bindings; read it once and it serves REST, MCP, and A2A.

Note the rate limit headers: Documented response headers tell you your remaining quota; read them before you design your polling cadence.

Core Setup: Authentication and Capability Discovery

Now we build. Your first two calls, in every UCP REST integration, are authentication and capability discovery. Get these right and everything downstream is mechanical.

Authentication uses a bearer token scoped to a set of permissions and a specific merchant or merchant group. When you request a token you specify scopes: catalog:read, cart:write, order:write, and so on. The principle of least privilege matters more here than in most APIs because agentic traffic is autonomous. A misconfigured order:write scope handed to a poorly-guarded agent is how you get the repeat-purchase loop from our opening story. Request only the scopes each service actually needs, and rotate tokens on a fixed schedule.

Rotation schedule: Rotate production tokens every 30 days at minimum, and immediately after any suspected leak, with overlapping validity windows so no request fails mid-rotation.

After you hold a valid token, call the capability discovery endpoint. It returns a document describing which resources and optional features the merchant supports, which protocol version they run, and which transport bindings they expose. Cache this response, but with a short TTL, 15 minutes is our default, because merchants can toggle capabilities. Never hardcode the assumption that an endpoint exists; branch on what discovery reports.

Store tokens in a secret manager: Never in environment variables committed to source, never in client-side code for the REST binding.

Scope every token narrowly: A catalog sync service gets catalog:read only, never write scopes.

Cache capabilities with a 15-minute TTL: Long enough to avoid a discovery call per request, short enough to catch merchant changes.

Log the protocol version on every response: This is your early-warning system for version drift.

Branch on discovered capabilities: Write your client to degrade gracefully when an optional endpoint is absent.

Implementation Steps: From First Call to Live Orders

Here is the exact sequence we follow on every new UCP REST integration. Follow it in order; each step depends on the one before.

Step one, authenticate and validate scopes. Request your token, then immediately call a lightweight authenticated endpoint to confirm the token works and carries the scopes you expect. Do not assume; verify. If the returned scopes differ from what you requested, stop and fix the token request before proceeding.

Step two, discover capabilities. Call the capability discovery endpoint and store the result. Confirm the merchant supports the resources your integration needs, catalog, cart, and order at minimum for a purchase flow. If a required capability is missing, you have found a blocker before writing any real logic.

Step three, hydrate the catalog. Page through the catalog endpoint using cursor pagination. This is where discipline matters: read the next-cursor token from each response and pass it into the next request until the cursor comes back null or absent. Store product identifiers mapped to your internal SKUs as you go. For a full catalog of 50,000 products at a page size of 250, expect 200 requests; at 500 requests per second that is well under a second of wall clock, but throttle to respect the documented rate limit headers.

Step four, poll inventory and pricing. These change more often than the catalog itself, so poll them on a shorter interval. We recommend a 60-second cadence for inventory on fast-moving stores and a 5-minute cadence for pricing, adjusting based on the rate limit headroom the response headers report.

Step five, create and hydrate a cart. Create a cart, add line items by product identifier, and read back the cart total the server computes. Never compute the total client-side and trust it; UCP servers are authoritative on price, tax, and available quantity. If the server total differs from your expectation, that is signal, not noise.

Step six, place the order. Submit the order with an idempotency key. This is non-negotiable. The idempotency key ensures that a retry after a network timeout does not create a duplicate order, which is the single most expensive failure mode in commerce automation. Generate a unique key per logical order attempt and reuse it across retries of that same attempt.

Step seven, handle fulfillment and webhooks. Register for fulfillment webhooks so you receive shipment and status updates rather than polling. Verify webhook signatures against the documented signing secret before trusting any payload.

Verify scopes before proceeding: Confirm your token carries exactly the scopes you expect, not what you requested.

Advance the cursor every page: Read next-cursor and pass it forward until it is null; this is the fix for the silent loop.

Always send an idempotency key on order creation: One key per logical order, reused across retries.

Trust the server’s computed totals: Never override price or tax client-side.

Verify webhook signatures: Reject any fulfillment payload whose signature does not validate.

The RESET Framework for Reliable UCP REST Integrations

We developed a five-step framework, RESET, that we run on every integration before we call it production-ready. It stands for Route, Enforce, Sync, Emit, and Test. Each step earns its place.

Route. What this achieves: it guarantees every UCP call goes through a single client layer so retries, logging, and rate limiting are consistent. Centralize all REST calls behind one internal client rather than scattering fetch calls across your codebase. This one decision prevents dozens of inconsistency bugs and gives you one place to add the idempotency and cursor logic.

Enforce. What this achieves: it stops out-of-scope or malformed calls before they ever leave your infrastructure. Enforce scope checks, request schema validation, and rate limits at the client layer. If a service tries a write it lacks scope for, fail fast locally with a clear error rather than surfacing a confusing 403 from the server.

Sync. What this achieves: it keeps your local view of catalog, inventory, and pricing accurate enough that agents make correct decisions. Establish your hydration and polling cadences per the numbers above and monitor for staleness. A stale price is worse than a missing one because agents act on it confidently.

Emit. What this achieves: it makes every UCP interaction observable so silent failures become loud. Emit structured logs and metrics on every call: endpoint, status, protocol version, latency, cursor state, and idempotency key. The repeat-purchase loop from our opening would have been caught in minutes with cursor-state metrics.

Test. What this achieves: it proves your error handling works before real traffic finds the edges. Test against sandbox fixtures for every documented error condition, especially the retryable-versus-terminal distinction, and run a load test that exercises pagination to completion.

Route all calls through one client: No scattered fetch calls, ever.

Enforce scopes and schemas locally: Fail fast before the request leaves your system.

Sync on documented cadences: 60-second inventory, 5-minute pricing as a starting point.

Emit cursor state and idempotency keys: These two metrics catch the most dangerous silent failures.

Test every documented error path: Retryable and terminal handling both, in the sandbox.

The most dangerous UCP failures are not the ones that throw errors; they are the ones that return a clean 200 while quietly doing the wrong thing.

Make Your Store Agent-Ready Without Building the Transport Layer Yourself

Reading the UCP REST API documentation end to end, choosing the right binding, and hardening the retry and idempotency logic is real engineering work, and most teams do not need to own it from scratch. This is exactly what our platform handles. UCPhub implements the Universal Commerce Protocol across REST, MCP, and A2A bindings so your catalog, inventory, and orders become instantly readable and transactable by AI shopping agents, without you writing a single cursor-pagination loop. We keep the transport layer versioned, monitored, and compliant so your team ships commerce features instead of protocol plumbing.

If you are weighing whether to build this in-house or adopt a managed layer, our comparison of UCP hub versus custom integration lays out the real cost tradeoffs, and why point solutions will not scale in 2026 explains the maintenance burden most teams underestimate. When you are ready, talk to our team and we will map your store to the UCP bindings that fit your traffic.

Optimization: Tuning the UCP REST API for Production Load

Once your integration works, the next job is making it efficient and resilient. Correctness and performance are different problems, and optimizing before you are correct just makes bugs faster.

Tune page size against payload weight: Larger pages mean fewer round trips but heavier responses. For catalog reads we default to 250 items per page and raise to 500 only when payloads stay under a few hundred kilobytes. Measure both round-trip count and total bytes; the sweet spot minimizes wall-clock time, not request count alone.

Respect rate limit headers dynamically: The UCP REST API documentation defines remaining-quota headers. Instead of a fixed delay, read the remaining quota and reset time from each response and adapt your cadence. This lets you run near the ceiling without ever tripping a 429. When you do hit a 429, honor the retry-after header exactly; do not use a shorter backoff.

Cache aggressively but correctly: Catalog data changes slowly, so cache it with a longer TTL, 15 to 60 minutes. Inventory and pricing change fast, so cache them for seconds, not minutes, or not at all for a live agent. Cache capability discovery for 15 minutes. Never cache cart or order responses; they are transactional and stale data here causes real financial errors.

Use conditional requests where supported: If capability discovery reports support for entity tags or last-modified semantics, use them so unchanged resources return a cheap not-modified status instead of a full payload. On a 50,000-product catalog this can cut sync bandwidth by 80 percent or more during incremental refreshes.

Batch where the documentation allows: Some UCP endpoints accept batched operations. Read the documentation to know which, and prefer batching for writes to reduce round trips, but keep batches small enough that one failure does not force you to retry a hundred operations.

Set client-side timeouts below the server ceiling: A hung request holds a connection and a token slot. Set aggressive timeouts, 5 seconds for reads, 15 for order creation, and let your retry logic handle timeouts as retryable events with the same idempotency key.

Adapt cadence from live headers: Read remaining quota per response, never a fixed sleep.

Cache by volatility class: Long TTL for catalog, seconds for inventory, never for orders.

Use conditional requests for incremental sync: Cut bandwidth dramatically on unchanged resources.

Set tight client timeouts: 5 seconds reads, 15 seconds order creation.

Honor retry-after exactly: Never back off faster than the server tells you.

Common Mistakes to Avoid

We have seen the same handful of mistakes sink integrations across dozens of onboardings. Every one is avoidable if you know it is coming.

Skipping capability discovery. Teams assume every merchant supports every endpoint, hardcode the assumption, and break the first time they hit a store that omits an optional feature. Always branch on discovered capabilities.

Ignoring the cursor. The failure from our opening. If you request the first page and never advance the cursor, you either loop on the same page forever or miss the rest of the catalog entirely. Both are silent. Emit cursor-state metrics and alert if a sync completes without the cursor ever reaching null.

Omitting idempotency keys on order creation. A network timeout during order submission, without an idempotency key, means your retry creates a second order. In commerce that is real money and real customer anger. One key per logical order, always.

Trusting client-computed totals. Agents that compute their own cart total and submit an order at that price will fight with the server’s authoritative total, causing failed orders or, worse, mismatched charges. The server is authoritative. Read its numbers.

Building retry logic without reading the error taxonomy. Retrying a terminal error wastes quota and can trigger rate limits; giving up on a retryable error loses recoverable transactions. The UCP REST API documentation classifies errors for exactly this reason.

Confusing the transport bindings. Picking MCP when you needed REST, or bridging bindings mid-transaction, creates latency and consistency problems that are hard to diagnose. Choose one binding per flow. Our comparison of UCP versus custom AI integrations reinforces why standardizing on the protocol beats bespoke bridging.

Never skip capability discovery: Branch on what the merchant actually supports.

Never ignore the cursor: Advance it to null and alert if you do not.

Never omit idempotency keys: One per logical order, reused on retry.

Never trust client-side totals: The UCP server is authoritative on price and tax.

Never build retries without the error taxonomy: Distinguish retryable from terminal.

Advanced Tips for High-Scale and Agent-Native Deployments

Once the basics are solid, these are the practices that separate a functional integration from one that thrives under real agentic load.

Pre-warm capability caches per merchant group. If you serve many merchants, discover capabilities on a scheduled background job rather than lazily on first request, so no agent ever pays the discovery latency in a live flow.

Segment tokens by workload. Use separate tokens for read-heavy catalog sync and write-heavy order flows. This isolates rate limits so a catalog resync cannot starve order placement of quota, and it narrows the blast radius if one token leaks.

Instrument the semantic layer, not just HTTP. Standard HTTP monitoring tells you status codes and latency. It does not tell you that an agent bought the same product forty times. Add domain metrics: orders per agent per minute, duplicate-idempotency-key rate, and price-mismatch rate. These catch the 200-that-does-the-wrong-thing failures.

Plan the bridge to MCP and A2A. Even if you start REST-only, structure your client so the underlying UCP operations are binding-agnostic. When you later expose the same catalog to conversational agents via MCP or to negotiating agents via A2A, you reuse the data mapping and only swap the transport. The technical architecture deep dive shows how the shared model makes this clean.

Watch the standards landscape. UCP is not the only proposal in the agentic commerce space, and the binding surface can shift as standards converge. Our analyses of UCP versus ACP for the agentic web and the deeper UCP versus ACP standards battle explain why abstracting your transport layer protects you regardless of which standard leads.

Optimize for conversion, not just correctness. A technically perfect integration that surfaces stale inventory still loses sales when an agent abandons a purchase because a product shows out of stock incorrectly. Tie your sync freshness targets to the conversion outcomes described in our agentic commerce conversion rate analysis.

Pre-warm capability caches: Discover on a schedule, never in the hot path.

Segment tokens by workload: Isolate catalog sync from order placement quotas.

Instrument domain metrics: Orders per agent, duplicate-key rate, price-mismatch rate.

Keep the client binding-agnostic: Reuse the data model across REST, MCP, and A2A.

Tie freshness to conversion: Sync targets should map to sales outcomes.

Measuring Success: 30, 60, and 90 Day KPIs

You cannot optimize what you do not measure, and UCP’s failure modes hide from naive monitoring. Here are the outcomes we track on a 30/60/90 day arc for every UCP REST integration.

Day 30, prove correctness. The first month is about trust, not scale.

Time to first successful order: Under one week from token issuance to a verified sandbox order and a verified production order.

Cursor-advance correctness: 100 percent of catalog syncs reach a null cursor; any sync that completes without doing so is a defect.

4xx error ratio: Below 2 percent of total requests after the first week, with every 4xx category explained.

Idempotency coverage: 100 percent of order creation calls carry an idempotency key; no exceptions.

Day 60, prove reliability. The second month is about resilience under real traffic.

5xx and retry success rate: Below 0.5 percent 5xx, with over 95 percent of retryable errors succeeding on retry.

Rate limit compliance: Zero unhandled 429 responses; every throttle is anticipated via headers.

Data freshness: Inventory staleness under 90 seconds and pricing staleness under 5 minutes at p95.

Price-mismatch rate: Below 0.1 percent of orders, trending toward zero as client-side assumptions are removed.

Day 90, prove business impact. The third month connects the plumbing to revenue.

Agent conversion rate: Measured against the benchmarks in our conversion analysis, trending up as freshness and correctness improve.

Duplicate-order rate: Effectively zero, confirming idempotency works under real retry conditions.

Cost per successful order: Trending down as caching and conditional requests reduce redundant calls.

Binding coverage: A documented plan or live deployment for MCP and A2A where your roadmap requires them.

A Practitioner’s Wrap-Up

If you are just getting started, do not try to boil the ocean. Read the three critical sections of the UCP REST API documentation, authentication, pagination, and the error taxonomy, then build the seven-step implementation flow against the sandbox before you touch production. Get one product bought correctly end to end, with a verified idempotency key and a cursor that reaches null, and you have earned the right to scale. If instead you are auditing an integration that already exists, start with observability: add cursor-state and idempotency metrics first, because the scariest UCP bugs are the silent 200s, and you cannot fix what you cannot see. For teams brand new to the protocol itself, our UCP for beginners guide is the gentlest on-ramp before the technical work begins.

Next Steps:

Provision a sandbox token and run the seven-step implementation flow end to end this week, stopping at a verified test order.
Add cursor-advance and idempotency-key metrics to any existing UCP integration before you make another change.
Read the UCP hub versus custom integration comparison and decide whether to own the transport layer or adopt a managed one.

Frequently Asked Questions

What is the UCP REST API and how does it work?

The UCP REST API is the HTTP transport binding for the Universal Commerce Protocol. It exposes commerce primitives, catalogs, prices, inventory, carts, orders, and fulfillment, as JSON resources over standard HTTP with predictable URLs, bearer-token authentication, cursor-based pagination, and a defined error envelope. It works the way any modern REST API works mechanically, but its semantics are designed for autonomous AI agents rather than human browsers, which shows up in details like server-authoritative pricing and mandatory idempotency for order creation.

Under the hood, the REST binding sits on the same shared UCP data model that the MCP and A2A bindings use. That means the fields you read in a REST catalog response are identical to the fields an MCP-connected agent would see; only the transport differs. You authenticate once, discover which capabilities a given merchant supports, then read and write resources using scoped tokens. The protocol carries a version in its headers so clients can detect and adapt to changes.

For a full conceptual grounding on the protocol behind the API, the definitive UCP guide explains the design goals, and the technical architecture deep dive shows how the REST binding relates to the others.

Where can I find the UCP REST API documentation?

The canonical UCP REST API documentation lives in the protocol’s reference specification, organized by resource area: capabilities, catalog, inventory, pricing, carts, orders, and fulfillment, plus shared sections on authentication, pagination, the error taxonomy, rate limit headers, and a data model appendix. We recommend reading the authentication, pagination, and error sections first, in that order, because they carry the semantics most likely to surprise you.

Beyond the reference spec, the documentation includes a versioned changelog you should subscribe to and a sandbox section that lists the exact test fixtures and error conditions the sandbox will reproduce on demand. Treat the changelog as an operational dependency, not optional reading, because minor version bumps can change response shapes you rely on. The data model appendix is shared across all three transport bindings, so reading it once serves your REST, MCP, and A2A work simultaneously.

If you are evaluating UCP as a whole before diving into the API reference, our coverage of the UCP release and launch gives context on where the specification stands in 2026.

How do I implement the UCP REST API in my application?

Follow the seven-step sequence we use on every integration. First, authenticate and immediately validate that your token carries the scopes you expect. Second, call the capability discovery endpoint and confirm the merchant supports the resources your flow needs. Third, hydrate the catalog using cursor pagination, advancing the cursor on every page until it returns null. Fourth, poll inventory and pricing on shorter cadences than the catalog. Fifth, create and hydrate a cart, trusting the server’s computed totals. Sixth, place the order with an idempotency key reused across retries. Seventh, register for and verify fulfillment webhooks.

The two implementation details that cause the most production incidents are cursor advancement and idempotency keys. If you ignore the cursor, your sync silently loops or truncates. If you omit idempotency keys on order creation, a network retry can create duplicate orders and charge customers twice. Build both correctly from day one, and instrument them with metrics so you can prove they are working.

Wrap all of this behind a single internal client so retry logic, rate limiting, logging, and the idempotency and cursor handling live in one place. That architectural decision, described in the RESET framework above, prevents the class of inconsistency bugs that arise when API calls are scattered across a codebase. If building and maintaining this layer is not where you want to spend engineering time, reach out to our team about a managed implementation.

What endpoints are available in the UCP REST API?

The UCP REST API organizes endpoints by resource area. The capabilities endpoint returns which features and protocol version a merchant supports and is the first non-auth call you should make. The catalog endpoints return product data with cursor pagination. Inventory and pricing endpoints return volatile data you poll more frequently than the catalog. Cart endpoints let you create a cart, add and remove line items, and read the server-computed total. Order endpoints handle creation, which requires an idempotency key, and status retrieval. Fulfillment endpoints and webhooks deliver shipment and delivery updates.

Crucially, not every endpoint is guaranteed to exist on every merchant. UCP defines a set of required resources and a set of optional ones, and the capability discovery endpoint tells you which optional features a specific merchant has enabled. This is why hardcoding the assumption that an endpoint exists is a common and avoidable mistake. Your client should branch on discovered capabilities and degrade gracefully when an optional endpoint is absent.

The exact URL patterns, request and response schemas, and required headers for each endpoint live in the UCP REST API documentation reference. Read the pagination and error sections alongside the endpoint definitions, because those cross-cutting contracts apply to nearly every endpoint you will call.

How does the REST binding compare to MCP and A2A for performance?

REST is the highest-throughput, lowest-latency binding for stateless commerce operations. In our benchmarks a tuned REST client sustains 400 to 600 catalog reads per second per token with p95 latency under 180 milliseconds, because there is no reasoning step and no long-lived session to coordinate. This makes REST the correct choice for catalog synchronization, inventory polling, and programmatic order placement where your own code controls the call sequence.

MCP performance is dominated by model inference, not transport, because the LLM decides which tools to call during a conversation. You trade throughput for flexibility: the model can handle sequences you could not predict in advance. A2A performance is characterized by long-lived, bidirectional sessions since two agents are negotiating, so it optimizes for correctness of the negotiation outcome rather than raw request rate. The right comparison is not which is fastest in isolation but which fits the initiator and flow of your specific use case.

Because all three bindings share the same data model, the pragmatic approach is to start with REST, keep your client binding-agnostic at the data layer, and add MCP or A2A only when a conversational or negotiating use case genuinely requires it. Our analysis of how AI agents become primary shoppers explains why A2A grows in importance over time even if you do not need it today.

Do I need all three transport bindings to be UCP-compliant?

No. Compliance is about correctly implementing the UCP data model and the semantics of whichever bindings you expose, not about supporting all three. Most merchants and integrators start with the REST binding because it covers the large majority of commerce integration needs and is the easiest to operate, debug, and monitor with standard HTTP tooling. You can be fully useful to a broad range of AI agents with REST alone.

That said, the binding you support determines which agents can transact with you natively. If conversational LLM agents are a meaningful traffic source, adding the MCP binding lets those agents discover and call your operations as tools mid-conversation without a bespoke bridge. If your roadmap includes autonomous agents negotiating terms with your merchant agent, A2A becomes relevant. Plan the sequence deliberately rather than adopting bindings you do not yet need.

The reason we recommend keeping your client binding-agnostic at the data layer is precisely so that expanding coverage later is a transport swap, not a rewrite. Our comparison of UCP versus custom integrations makes the case that standardizing on the protocol, rather than building point solutions per agent, is what keeps this manageable as the ecosystem grows.

How do I handle errors and retries safely with the UCP REST API?

Start by reading the error taxonomy section of the documentation, because UCP classifies errors as retryable or terminal in the response envelope. Retryable errors, transient network issues, temporary server unavailability, and rate limits, should be retried with exponential backoff, while terminal errors, malformed requests, insufficient scope, or validation failures, should not be retried because they will fail identically every time and waste your quota.

For rate limits specifically, honor the retry-after header exactly rather than using your own backoff, and read the remaining-quota headers on every response so you can adapt your cadence and avoid tripping a 429 in the first place. For order creation, always carry an idempotency key and reuse the same key across all retries of the same logical order, so that a retry after a timeout resolves to the original order rather than creating a duplicate. This single practice prevents the most expensive failure mode in commerce automation.

Finally, instrument your error handling. Emit metrics on 4xx and 5xx ratios, retry success rate, and duplicate-idempotency-key occurrences. The most dangerous failures in UCP are not loud errors but clean 200 responses that hide incorrect behavior, so domain-level metrics like orders-per-agent and price-mismatch rate are as important as HTTP status monitoring for catching problems before they compound.