Skip to content
UCP
Menu

Technical Guide · Implementation

Implementing UCP: complete guide for merchants and developers

Want to make your store compatible with the Universal Commerce Protocol to be accessible to AI agents? This technical guide covers prerequisites, endpoints to expose, AP2 payment integration, validation testing, and common mistakes to avoid.

Editorial team · Updated : April 2026 · Primary query : implement UCP

Prerequisites before you start

Platform compatibility

Shopify provides its own agent and Catalog surfaces. Merchants should use the current Shopify documentation because exposed capabilities and authentication depend on the surface and account.

For WooCommerce, Magento, PrestaShop, Salesforce Commerce, BigCommerce, or a custom stack, integration effort depends on existing catalog, checkout, identity, payment and order systems. The open UCP schemas and bindings are the implementation source of truth; the specification does not publish a universal delivery estimate.

Required product data quality

  • Complete: name, description, price, currency, variants (size, color), weight, dimensions
  • Identified: GTIN/EAN or proprietary SKU documented per product
  • Up-to-date: stock synchronized in near-real-time (maximum delay: a few minutes)
  • Enriched: structured return policies, delivery times by zone, category-specific attributes

Payment and AP2 scope

UCP supports multiple payment handlers. AP2 is an optional checkout extension that adds signed Checkout and Payment Mandates. Confirm product support and integration requirements directly with each payment provider rather than inferring compatibility from coalition membership.

Step 1: Expose catalog endpoints

UCP defines standardized REST endpoints that your server must expose for AI agents to query your catalog.

POST /catalog/search

Searches the catalog using the versioned UCP JSON schema. Product and variant identifiers, descriptions, prices, media and availability follow the fields defined by the negotiated Catalog capability.

POST /catalog/lookup

Looks up products or variants by identifier. Availability is carried on variants and checkout remains authoritative for price, eligibility and availability. Set a performance budget from your own service objectives; the UCP specification does not impose the latency or uptime figures previously stated here.

POST /checkout-sessions

Creates a checkout session relative to the REST base URL advertised in the business profile. Updating, completing and cancelling use the checkout-session operations defined by the negotiated binding.

Step 2: Implement Identity Linking

Identity Linking allows an AI agent to associate a user's identity with your merchant system without the user needing to manually log in to your site at each purchase.

Identity Linking uses OAuth 2.0 authorization and declared scopes. Implement the current capability specification and minimize the data requested; there is no generic UCP verification API that replaces your authorization-server checks.

Step 3: Configure AP2 payments

If AP2 is negotiated, the Shopping Agent, Merchant, Credential Provider and Merchant Payment Processor must validate the mandates, checkout binding and receipts assigned to their roles. Provider-specific availability and setup must be checked in that provider's current documentation.

Step 4: Expose Order Management endpoints

The current REST binding exposes the current order snapshot and uses the business permalink as the authoritative post-purchase experience:

  • GET /orders/{id} returns the current order, including fulfillment events and adjustments.
  • Order Event Webhooks can push lifecycle changes from the business to the platform.
  • Returns, cancellations and other post-purchase actions remain governed by the business and its advertised capabilities.

Step 5: Testing and validation

Before going live, validate against the exact schemas and binding negotiated by both profiles:

  1. Test profile discovery, cache headers, version selection and capability pruning
  2. Validate success and error envelopes against the versioned schemas
  3. Test authentication, scopes and HTTP Message Signatures where used
  4. Load-test catalog and checkout operations against your service objectives
  5. Run direct and autonomous purchase scenarios for the capabilities you actually support

Common mistakes to avoid

Unmanaged timeouts. Set explicit client and server timeouts, monitor latency and avoid serving stale catalog data as a transactional commitment.

Unsynchronized stock. Revalidate price and availability during checkout because catalog responses are not commitments.

Incomplete capability metadata. Advertise only the versions, transports and extensions that the business really supports.

Ignored business outcomes. Inspect the UCP messages array before consuming operation data.

Official resources