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.

Updated : April 2026 · Primary query : implement UCP

Prerequisites before you start

Platform compatibility

If you use Shopify: you have a head start. Shopify is a UCP co-founder and offers native support since the protocol launched in January 2026. The key is to activate UCP features in your Admin and complete your product data.

For WooCommerce, Magento, PrestaShop, Salesforce Commerce, or BigCommerce: specifications are open on the official UCP GitHub. A backend developer familiar with REST and JSON-RPC can implement a basic integration in 2 to 3 days of work.

For a custom solution: direct implementation is possible and documented at ucp.dev. Allow 5 to 10 development days for a complete integration with tests.

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

AP2-compatible payment processor

UCP relies on the Agent Payments Protocol (AP2). Compatible processors are Stripe, Adyen, Mastercard, Visa, and American Express, all UCP founding partners. If you use one of these processors with an up-to-date integration, AP2 support requires activation, not a technical overhaul.

Step 1: Expose catalog endpoints

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

GET /ucp/v1/catalog

Returns your product list in UCP JSON-LD format. Each product must include: @type: "Product", sku or gtin, name, description, offers (with price, currency, availability), shippingDetails, and returnPolicy.

GET /ucp/v1/inventory/{sku}

Real-time availability of a specific product. Critical performance requirements: response under 200ms, minimum 99.5% uptime. A timeout directly excludes your product, the AI agent moves to a competitor.

POST /ucp/v1/checkout

Receives purchase instructions from the AI agent and initiates the order process. Must handle: identity validation (UCP Identity Linking), stock reservation, AP2 payment initiation, and order confirmation generation with tracking number.

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.

The user authorizes once (in the AI agent's interface) to share their delivery and contact information. This information is then transmitted via cryptographically signed tokens that you verify via the UCP verification API. Your system never stores banking data, only the verified identity token.

Step 3: Configure AP2 payments

For Stripe: Dashboard → Settings → Agentic Payments → Enable Agent Payments Protocol. Configure transaction limits for agent-initiated payments (max amount, eligible categories).

For Adyen: contact your account manager to enable the AP2 profile. Adyen requires prior validation of your catalog and inventory endpoints before activating agentic payments.

Step 4: Expose Order Management endpoints

UCP requires a set of post-purchase management endpoints that AI agents use to keep the user informed:

  • GET /ucp/v1/orders/{order_id}, real-time order status
  • POST /ucp/v1/orders/{order_id}/cancel, AI agent-initiated cancellation
  • GET /ucp/v1/orders/{order_id}/tracking, delivery tracking

Step 5: Testing and validation

The official GitHub repository (github.com/Universal-Commerce-Protocol/ucp) includes a conformance test suite and an AI agent simulator. Before going live:

  1. Run the UCP test suite on all endpoints
  2. Test error scenarios (out of stock, payment declined, timeout)
  3. Validate Identity Linking with an official test token
  4. Check inventory endpoint response times under load
  5. Simulate a complete end-to-end purchase with the agent simulator

Common mistakes to avoid

Unmanaged timeouts. An inventory endpoint responding beyond 500ms will be flagged as unreliable. Use Redis or equivalent cache for frequently queried inventory data.

Unsynchronized stock. Showing "available" for an out-of-stock product creates a poor experience and degrades your agentic reputation score.

Missing return policy. AI agents actively compare return policies between merchants. A missing or empty returnPolicy field puts you at a disadvantage.

No error handling at checkout. The AI agent must receive standardized error codes (out of stock, unverified identity, payment declined) to offer alternatives to the user.

Official resources