REST

Overview

REST is the primary transport for UCP, enabling direct server-to-server communication using standard HTTP methods. It's ideal for traditional platform integrations and backend services.

Base URL Discovery

The REST base URL is declared in the business profile:

GET /.well-known/ucp/business_profile.json

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

Authentication

REST transport uses OAuth 2.0 Bearer tokens:

GET /checkout/sessions/sess_abc123
Host: api.business.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

Request Format

POST /checkout/sessions
Host: api.business.com
Authorization: Bearer {access_token}
Content-Type: application/json
X-Request-ID: req_unique_123
X-UCP-Version: 2026-01-11

{
  "cart": {
    "items": [
      { "product_id": "SKU-001", "quantity": 2 }
    ]
  },
  "currency": "USD"
}

Response Format

HTTP/1.1 201 Created
Content-Type: application/json
X-Request-ID: req_unique_123
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705312800

{
  "session_id": "sess_abc123",
  "status": "open",
  "cart": { ... },
  "created_at": "2025-01-15T10:30:00Z"
}

HTTP Methods

Core Endpoints

Rate Limiting

Businesses implement rate limiting with standard headers:

• X-RateLimit-Limit - Maximum requests per window
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - Unix timestamp when limit resets

Rate Limited Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retry_after": 60
  }
}

Error Response Format

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "cart.items[0].quantity",
      "reason": "Must be a positive integer"
    }
  }
}

HTTP Status Codes

CORS Configuration

For browser-based clients, businesses configure CORS headers:

Access-Control-Allow-Origin: https://platform.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-ID
Access-Control-Max-Age: 86400

Retry Strategy

Implement exponential backoff for transient failures:

async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3
): Promise<Response> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        await sleep(parseInt(retryAfter || '60') * 1000);
        continue;
      }

      if (response.status >= 500) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }

      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
  throw new Error('Max retries exceeded');
}

Next Steps

• Learn about MCP Transport for AI integration
• See Checkout Capability for session management
• Explore Platform Integration for examples