Extensions¶

USP is designed to be extensible. Extensions augment core capabilities via the extends field, using JSON Schema composition (allOf, $defs) to layer additional fields onto base capability schemas.

How Extensions Work¶

Extensions follow three rules:

1. Declared via extends — Each extension capability declares which base capability it augments.
2. JSON Schema composition — Extensions use allOf to add fields to base schemas without modifying them.
3. Versioned independently — Extensions have their own version (YYYY-MM-DD) and may declare version requirements on the base capability.

{
  "name": "dev.usp-protocol.services.waitlist",
  "version": "2026-08-20",
  "extends": "dev.usp-protocol.services.bookings",
  "spec": "https://usp-protocol.dev/specification#waitlist-extension",
  "schema": "https://usp-protocol.dev/schemas/services/waitlist.json"
}

Version Requirements¶

Extension schemas SHOULD declare a requires object specifying minimum protocol and capability versions:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://usp-protocol.dev/schemas/services/waitlist.json",
  "requires": {
    "protocol": { "min": "2026-08-20" },
    "capabilities": {
      "dev.usp-protocol.services.bookings": { "min": "2026-08-20" }
    }
  }
}

Waitlist Extension¶

Capability: dev.usp-protocol.services.waitlist
Extends: dev.usp-protocol.services.bookings

The waitlist extension enables platforms to join a waitlist when a desired time slot or service is fully booked, and receive notifications when spots open up.

Waitlist Entry Schema¶

Waitlist Status Lifecycle¶

stateDiagram-v2
    [*] --> waiting : Join waitlist
    waiting --> offered : Slot available
    offered --> converted : Buyer accepts
    offered --> waiting : Buyer declines / offer expires
    waiting --> canceled : Buyer cancels
    offered --> canceled : Buyer cancels
    waiting --> expired : Waitlist TTL exceeded

Operations¶

Webhooks¶

Pay-at-Service Settlement Extension¶

Capability: dev.usp-protocol.services.pay_at_service (extends dev.ucp.shopping.checkout)

Lets a UCP checkout complete when the buyer owes money that is settled in person rather than through the protocol. Required for payment_timing: at_service in UCP-Native Mode.

Why it exists¶

UCP's payment terms extension already expresses an obligation falling due after checkout completes, and carries it onto the order so it stays machine-readable. What it assumes is that an instrument will eventually be charged: UCP requires the instrument funding a term to be capable of every schedule on it, and forbids advertising one that is not.

That assumption holds for trade credit and installments. It does not hold for the ordinary case in local time-based services, where the buyer books now and pays cash or taps a terminal at the counter. There the obligation is real and disclosed at checkout, but it is discharged by a channel the protocol does not model.

This extension adds exactly one thing: a declaration that a named payment term is settled outside UCP. The amount, the due time, and the buyer-facing statement of the obligation all remain the payment term's, so they cannot drift.

Settlement Declaration¶

settlement is a member of the checkout root, a sibling of payment rather than a member of it, because it does not describe a payment being taken.

Pay-at-Service Term¶

Every schedule on a pay-at-service term carries type: "at_service" and a due_at equal to the start of the booked slot. USP requires due_at even though UCP makes it optional: a booked slot is a known time, which is the whole point of scheduling, so a platform can set a reminder rather than parse prose.

{
  "totals": [
    { "type": "subtotal", "amount": 7500 },
    { "type": "total", "display_text": "Due at your appointment", "amount": 7500 }
  ],
  "payment": {
    "selected_term_id": "pt_at_service",
    "terms": [
      {
        "id": "pt_at_service",
        "title": "Pay at your appointment",
        "schedules": [
          {
            "id": "sched_at_service",
            "type": "at_service",
            "description": { "plain": "Due at your appointment on 14 October 2026 at 10:00 AM EDT." },
            "due_at": "2026-10-14T10:00:00-04:00",
            "amount": 7500
          }
        ]
      }
    ]
  },
  "settlement": {
    "mode": "offline",
    "term_id": "pt_at_service",
    "accepted_methods": ["cash", "card_in_person"]
  }
}

The checkout total is the full price, because UCP requires the selected term's schedules to sum to it. The amount collected at completion is zero.

Rules¶

Out of scope¶

• Amounts not determinable at checkout. A tip or an add-on chosen in the chair is an order adjustment, not a schedule.
• Payment execution and proof. No capture, no confirmation call, no receipt. A platform MUST NOT infer that an offline obligation can be inspected, settled, or cancelled through USP.
• Enforcement. A buyer who does not show is a no_show, handled by the business's cancellation and no-show policy.

Vendor Extensions¶

Vendors define custom capabilities under their reverse-domain namespace:

com.{vendor}.services.{capability_name}

Example: Custom Courses Capability¶

{
  "name": "com.wix.services.courses",
  "version": "2026-03-01",
  "extends": "dev.usp-protocol.services.bookings",
  "spec": "https://wix.com/services/courses/spec",
  "schema": "https://wix.com/services/courses/schema.json"
}

Requirements for Vendor Extensions¶

1. Must use vendor's reverse-domain namespace — Never use dev.usp-protocol.*.
2. Must publish a specification (spec URL) and schema (schema URL) that define the additional fields and semantics.
3. URLs must match namespace authority — com.wix.* capabilities must reference https://wix.com/....
4. Should declare version requirements on parent capabilities.