Core Concepts¶

USP enables interoperability between platforms, businesses, and payment providers for service commerce. This page introduces the key roles, architectural principles, and protocol constructs.

Roles and Participants¶

USP defines interactions between four participants:

Platform (Application / Agent)¶

The consumer-facing surface acting on behalf of the user. Platforms orchestrate the full journey: discovering services, presenting availability, and facilitating booking and payment.

• Responsibilities: Discovering business capabilities via /.well-known/usp or /.well-known/ucp, querying availability, creating bookings, processing payment through whichever checkout system is available.
• Examples: AI scheduling assistants, super apps, search engines, marketplace platforms.

Business¶

The entity offering time-based services. The business owns the schedule, resources, and booking policies. For payment, the business remains the Merchant of Record.

• Responsibilities: Publishing a USP profile, exposing a service catalog, computing real-time availability, managing the booking lifecycle, providing payment actions with payment_context for paid services.
• Examples: Salons, clinics, fitness studios, restaurants, rental companies, consultancies.

Credential Provider (CP)¶

A trusted entity that securely manages user payment instruments and identity. When buyers pay with a wallet or tokenized instrument, the credential provider — not the platform or business — often holds the sensitive payment credentials.

• Examples: Google Wallet, Apple Pay, digital identity providers.

Payment Service Provider (PSP)¶

The financial infrastructure that processes payments. USP delegates all payment processing to the checkout system, which in turn interacts with the PSP.

• Examples: Stripe, Adyen, PayPal, Braintree.

High-Level Architecture¶

USP supports two deployment modes. Both share the same scheduling layer (catalog, availability, booking). The payment path diverges based on the deployment mode:

graph TD
    subgraph USP ["USP — Scheduling (shared)"]
        direction LR
        P[Platform / Agent] -- "catalog + availability + booking" --> B[Business]
    end

    subgraph UCP_Mode ["UCP-Native Mode"]
        direction LR
        P1[Platform] -- "create_checkout\n(booking extension)" --> UCP[UCP Checkout]
        UCP -- "complete_checkout\n(atomic)" --> PSP1[PSP]
    end

    subgraph Standalone_Mode ["Standalone Mode"]
        direction LR
        P2[Platform] -- "payment_context" --> CS[Checkout System]
        CS -- "process payment" --> PSP2[PSP]
        P2 -- "confirm-payment" --> B2[Business]
    end

    USP -- "paid booking\n(UCP platform)" --> UCP_Mode
    USP -- "paid booking\n(non-UCP platform)" --> Standalone_Mode

UCP-Native Mode: Platforms that already support UCP register USP scheduling capabilities directly in their /.well-known/ucp profile. Paid bookings use UCP's atomic checkout.

Standalone Mode: Platforms that do not use UCP discover businesses via /.well-known/usp. For paid bookings, the business returns a payment_context that any checkout system can process.

Both modes share the same scheduling operations and transport bindings. For free services, no checkout system is needed in either mode.

Commerce and Non-Commerce Services¶

USP supports both paid services that require payment integration and free or pay-later services that operate without any payment infrastructure.

Core Constructs¶

USP is built on three constructs:

Namespace Governance¶

USP uses reverse-domain notation for capability names:

{reverse-domain}.{service}.{capability}

The spec and schema URLs on each capability entry MUST use origins that match the reverse-domain namespace authority. For example, dev.usp.* capabilities must reference https://usp.dev/....

Within the dev.usp.* namespace:

• dev.usp.services.* — Business-facing capabilities (catalog, availability, bookings)
• dev.usp.platform.* — Platform-scoped capabilities (e.g., calendar free/busy)

Multi-Location Businesses¶

For businesses with multiple locations, a single USP endpoint MAY serve all locations through a unified profile:

{
  "usp": {
    "version": "2026-02-21",
    "business": {
      "name": "Sunrise Wellness Studio",
      "timezone": "America/New_York",
      "currency": "USD",
      "locations": [
        { "id": "loc_nyc", "name": "NYC Downtown",
          "address": "123 Main St, New York, NY 10001" },
        { "id": "loc_la", "name": "LA West",
          "address": "456 Sunset Blvd, Los Angeles, CA 90028" }
      ]
    }
  }
}

Operations accept an optional location_id filter to scope requests. Alternatively, each location MAY publish its own independent /.well-known/usp profile.

Error Handling¶

USP separates business outcome feedback from protocol failures:

• Business outcomes: Successful HTTP exchanges where the business reports a scheduling or policy result using a messages[] array. Each message uses type, code, content, and optional severity.
• Protocol errors: HTTP status codes with RFC 9457 Problem Details (REST) or JSON-RPC error objects (MCP).

State-changing operations SHOULD use an idempotency key to prevent duplicate bookings on retry. See Transport Bindings for details.