Checkout

Overview

Checkout is a core capability that every UCP-compatible business must implement. It provides a standardized way to create purchase sessions, manage carts, and complete transactions.

Session Lifecycle

A checkout session follows this lifecycle:

1. Creation - Session is initialized with cart items
2. Configuration - Shipping, payment, and buyer details are added
3. Validation - Business validates the order can be fulfilled
4. Completion - Payment is processed and order is confirmed
5. Expiration - Sessions expire after a configurable timeout

REST API Endpoints

Create Session

POST /checkout/sessions
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "cart": {
    "items": [
      {
        "product_id": "SKU-001",
        "quantity": 2
      }
    ]
  },
  "currency": "USD",
  "return_url": "https://platform.com/callback"
}

Response

{
  "session_id": "sess_abc123",
  "status": "open",
  "cart": {
    "items": [
      {
        "product_id": "SKU-001",
        "quantity": 2,
        "unit_price": 29.99,
        "total": 59.98
      }
    ],
    "subtotal": 59.98,
    "tax": 5.40,
    "total": 65.38
  },
  "expires_at": "2025-01-15T12:00:00Z",
  "checkout_url": "https://checkout.business.com/sess_abc123"
}

Get Session

GET /checkout/sessions/{session_id}
Authorization: Bearer {access_token}

Update Cart

PUT /checkout/sessions/{session_id}/cart
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "operations": [
    { "type": "add", "product_id": "SKU-002", "quantity": 1 },
    { "type": "update", "product_id": "SKU-001", "quantity": 3 },
    { "type": "remove", "product_id": "SKU-003" }
  ]
}

Complete Checkout

POST /checkout/sessions/{session_id}/complete
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "payment": {
    "handler": "stripe",
    "token": "tok_xxx"
  },
  "shipping_address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  }
}

Session States

Payment Handlers

UCP decouples payment processing from the checkout flow using Payment Handlers. Businesses declare supported handlers in their profile:

• Redirect - User is redirected to complete payment
• Token - Tokenized payment (Stripe, PayPal, etc.)
• Invoice - B2B invoice-based payment

Error Handling

{
  "error": {
    "code": "CHECKOUT_SESSION_EXPIRED",
    "message": "The checkout session has expired",
    "details": {
      "session_id": "sess_abc123",
      "expired_at": "2025-01-15T12:00:00Z"
    }
  }
}

Common Error Codes

• CHECKOUT_SESSION_EXPIRED - Session has timed out
• PRODUCT_UNAVAILABLE - Product is out of stock
• PRICE_CHANGED - Product price has changed since session creation
• PAYMENT_FAILED - Payment processing error
• INVALID_SHIPPING_ADDRESS - Cannot ship to provided address

Next Steps

• Learn about Identity Linking for user authentication
• Explore Fulfillment Extension for shipping options
• See REST Transport for complete API details