Integration Guide: Businesses | UCP Documentation

Overview

Integrating your business with UCP enables AI agents and platforms to discover, interact with, and purchase from your store without custom integrations. This guide walks you through the process of becoming UCP-compatible.

Prerequisites

An existing e-commerce store (Shopify, WooCommerce, custom, etc.)
HTTPS-enabled domain
OAuth 2.0 authentication infrastructure
Webhook endpoint for order events

Step 1: Create Your Business Profile

The business profile is a JSON document that describes your store's capabilities and endpoints. It must be served at /.well-known/ucp/business_profile.json:

{
  "schema_version": "1.0",
  "identifier": "urn:ucp:business:your-store-id",
  "name": "Your Store Name",
  "description": "Brief description of your store",
  "protocol_version": "1.0",

  "capabilities": [
    "dev.ucp.shopping.checkout",
    "dev.ucp.common.identity_linking",
    "dev.ucp.shopping.order"
  ],

  "extensions": [
    "dev.ucp.shopping.fulfillment",
    "dev.ucp.shopping.discount"
  ],

  "transports": {
    "rest": {
      "base_url": "https://api.yourstore.com/ucp/v1",
      "auth_url": "https://auth.yourstore.com/oauth",
      "documentation": "https://docs.yourstore.com/ucp"
    }
  },

  "payment_handlers": [
    {
      "type": "stripe",
      "supported_currencies": ["USD", "EUR", "GBP"]
    }
  ]
}

Step 2: Implement Core Capabilities

Checkout Capability

Implement the following REST endpoints:

POST/checkout/sessionsCreate session

GET/checkout/sessions/:idGet session

PUT/checkout/sessions/:id/cartUpdate cart

POST/checkout/sessions/:id/completeComplete checkout

Identity Linking Capability

Implement OAuth 2.0 authorization code flow to allow platforms to act on behalf of users. This enables personalized pricing, loyalty rewards, and saved payment methods.

Order Capability

Set up webhook endpoints to send order lifecycle events:

order.created - When a new order is placed
order.updated - When order status changes
order.shipped - When items are shipped
order.delivered - When items are delivered
order.cancelled - When order is cancelled

Step 3: Configure Payment Handlers

UCP supports multiple payment handler patterns. Choose based on your compliance requirements:

Redirect Handler

Agent redirects to your checkout page for payment. Best for PCI compliance.

PCI-DSS Compliant

Token Handler

Accept tokenized payment methods (Stripe, PayPal tokens) via API.

Seamless Flow

Step 4: Testing

Use the UCP test suite to validate your implementation:

# Install UCP CLI
npm install -g @ucp/cli

# Run validation tests
ucp validate https://yourstore.com

# Run integration tests
ucp test --suite=checkout https://yourstore.com

Integration Checklist

Business profile served at /.well-known/ucp/business_profile.json

HTTPS enabled with valid certificate

Checkout session endpoints implemented

OAuth 2.0 authorization flow configured

Webhook endpoints receiving events

Payment handler configured

CORS headers set for allowed origins

Rate limiting implemented

Error responses follow UCP format

Next Steps

Once your integration is complete:

Register with UCPStore for enhanced discovery
Set up monitoring and analytics for UCP traffic
Implement optional Extensions for advanced features

For Businesses