Booking Lifecycle¶

Capability: dev.usp-protocol.services.bookings

The bookings capability defines the lifecycle of a service booking from creation through completion. For paid services, it also defines the actions array (including payment actions with payment_context) and the confirm-payment operation.

Booking Status Lifecycle¶

stateDiagram-v2
    [*] --> pending
    pending --> confirmed : auto-confirm or manual approve
    pending --> requires_action : payment needed
    pending --> canceled : timeout or cancel

    requires_action --> confirmed : payment confirmed
    requires_action --> canceled : timeout or cancel

    confirmed --> in_progress : service begins
    confirmed --> canceled : cancel

    in_progress --> completed : service delivered
    in_progress --> no_show : client absent

    completed --> [*]
    no_show --> [*]
    canceled --> [*]

Status Descriptions¶

Permitted Transitions by Operation¶

The lifecycle diagram shows which statuses can follow which. It does not say which operation is legal from a given status, which is what a platform needs to know whether a call will be accepted. This table is normative.

Yes means the business MUST accept the call when all other preconditions hold. No means it MUST reject with invalid_transition.

The cells implementations diverge on:

• reschedule from pending is SHOULD. A business that does not allow it MUST reject with invalid_transition rather than silently succeeding.
• reschedule from requires_action is MAY, because an outstanding payment action may be priced against the original slot. A business that allows it MUST apply the reschedule price-change rules.
• confirm from pending is Yes only when confirmation_mode is manual. For an auto-mode booking the operation does not apply: a business MUST return the current booking unchanged when it is already confirmed (idempotent), and MUST reject with invalid_transition otherwise.
• confirm from confirmed is idempotent: it MUST return the current booking, so a retried confirmation is safe.
• update on terminal statuses is No. The booking is a historical record; contact and address edits MUST NOT be accepted on completed, no_show, or canceled bookings. When the booking questions extension is negotiated, this call-level invalid_transition governs and booking_question_update_not_allowed is not also returned.

Transitions to in_progress, completed, and no_show are business-initiated and have no platform-facing operation. They surface via GET /bookings/{booking_id} and the booking.updated webhook.

Booking Schema¶

The booking object represents a scheduled service instance for a specific buyer at a specific time.

Negotiated Extension Actions¶

An entry in actions[] is one of two kinds, distinguished by whether it carries config:

• Handoff Action (no config): a payment action or any action whose extension is not active in the negotiated intersection. continue_url is REQUIRED, and the buyer completes the work on the business surface.
• Negotiated extension Action (config present): type is a reverse-domain Action type declared by an extension active in the negotiated intersection, id is REQUIRED, and config carries the extension-owned processing configuration. continue_url is OPTIONAL and, when present, is the fallback the declaring extension defines.

These semantics are aligned with UCP's common Action contract. A business MUST emit a negotiated extension Action only when its declaring extension is active for the requesting platform, and MUST keep the same type and id while the same work remains outstanding. A platform MUST NOT assume the gated effect succeeded because an Action surface closed or a submission returned transport success; the business's later response is authoritative. A platform that cannot satisfy the declaring extension's complete contract uses continue_url when present and otherwise leaves the Action unresolved. The booking questions buyer-input Action is described in Extensions.

Confirmation Mode and Booking History¶

confirmation_mode is a historical fact about a booking, not a live read of the service. A business MAY change a service's confirmation policy at any time, and doing so MUST NOT change the meaning of bookings already taken under the previous policy.

This makes the field unanswerable for some bookings. A business that does not store the policy alongside the booking has only two values available once the booking is confirmed, and both are wrong:

• the service's current policy, which is not what the field means, and which silently changes for historical bookings every time the policy changes
• a fixed auto, which misreports every booking the merchant actually approved

The field is therefore REQUIRED only while status is pending or requires_action — the states where a business necessarily knows the answer, because the booking is sitting in the flow that policy selected, and the states where the answer is actionable, because the buyer needs to know whether approval is outstanding. Outside those states the field is OPTIONAL, and a business that cannot answer truthfully MUST omit it.

Platforms MUST treat an absent confirmation_mode as unknown. A business that does retain the original policy SHOULD continue to publish the field on confirmed and completed bookings, where it remains useful for audit and buyer-facing history.

Booking Expiry¶

expires_at on Booking is an advertised deadline. Omitting it is conformant when the business does not hold slot capacity for that unconfirmed booking. The numbered rules below apply only when expires_at is present. A business that advertises expires_at MUST honour it.

When a pending or requires_action booking that includes expires_at reaches that deadline without being resolved:

1. The business MUST transition the booking to status: canceled.
2. The business SHOULD send a booking.canceled webhook.
3. The expired booking MUST remain retrievable via GET /bookings/{booking_id} with status: canceled.
4. The business MUST release any underlying slot hold.

Operations¶

Create Booking -- POST /bookings¶

Creates a new booking for a service at a specific time slot. Resource selection is encoded in the slot_id -- the platform selects resources by choosing the appropriate slot at availability query time.

Request Fields:

{
  "service_id": "svc_massage_001",
  "slot_id": "slot_20260316_1400",
  "hold_id": "hold_xyz789",
  "buyer": {
    "first_name": "Alice",
    "last_name": "Williams",
    "email": "alice@example.com",
    "phone_number": "+12125551234"
  },
  "party_size": 1,
  "notes": "First time visit"
}

{
  "service_id": "svc_massage_001",
  "slot_id": "slot_20260316_1400",
  "buyer": {
    "first_name": "Alice",
    "last_name": "Williams",
    "email": "alice@example.com",
    "phone_number": "+12125551234"
  },
  "party_size": 1,
  "notes": "First time visit"
}

{
  "service_id": "svc_haircut_kids",
  "slot_id": "slot_20260316_1600",
  "hold_id": "hold_abc456",
  "buyer": {
    "first_name": "Alice",
    "last_name": "Williams",
    "email": "alice@example.com",
    "phone_number": "+12125551234"
  },
  "recipient": {
    "first_name": "Max",
    "last_name": "Williams"
  },
  "party_size": 1,
  "notes": "He is 7 years old"
}

{
  "usp": {
    "version": "2026-08-20",
    "capabilities": {
      "dev.usp-protocol.services.bookings": [
        { "version": "2026-08-20" }
      ]
    }
  },
  "booking": {
    "id": "bkg_456def",
    "service_id": "svc_massage_001",
    "service_name": "Deep Tissue Massage",
    "slot": {
      "id": "slot_20260316_1400",
      "start": "2026-03-16T14:00:00-04:00",
      "end": "2026-03-16T15:00:00-04:00",
      "duration": "PT60M"
    },
    "buyer": {
      "first_name": "Alice",
      "last_name": "Williams",
      "email": "alice@example.com",
      "phone_number": "+12125551234"
    },
    "party_size": 1,
    "resources": [
      { "id": "staff_jane", "type": "staff", "name": "Jane Smith" }
    ],
    "status": "requires_action",
    "confirmation_mode": "auto",
    "payment": {
      "status": "pending",
      "timing": "at_booking",
      "amount": 12000,
      "currency": "USD",
      "amount_due": 12000
    },
    "actions": [
      {
        "type": "payment",
        "status": "pending",
        "continue_url": "https://business.example.com/pay/bkg_456def",
        "expires_at": "2026-03-16T13:10:00-04:00",
        "message": {
          "type": "info",
          "code": "payment_required",
          "content": "Payment of $120.00 is required to confirm this booking.",
          "severity": "requires_buyer_input"
        },
        "payment_context": {
          "amount_due": 12000,
          "currency": "USD",
          "description": "Deep Tissue Massage - Mar 16, 2:00 PM",
          "line_items": [
            {
              "label": "Deep Tissue Massage (60 min)",
              "amount": 12000,
              "quantity": 1,
              "item_id": "svc_massage_001"
            }
          ],
          "metadata": {
            "booking_id": "bkg_456def",
            "service_id": "svc_massage_001",
            "service_type": "appointment",
            "slot_start": "2026-03-16T14:00:00-04:00"
          }
        }
      }
    ],
    "created_at": "2026-03-14T22:05:00Z",
    "updated_at": "2026-03-14T22:05:00Z",
    "expires_at": "2026-03-16T13:10:00-04:00"
  }
}

{
  "usp": {
    "version": "2026-08-20",
    "capabilities": {
      "dev.usp-protocol.services.bookings": [
        { "version": "2026-08-20" }
      ]
    }
  },
  "booking": {
    "id": "bkg_789ghi",
    "service_id": "svc_yoga_free",
    "service_name": "Community Yoga",
    "slot": {
      "id": "slot_20260318_1000",
      "start": "2026-03-18T10:00:00-04:00",
      "end": "2026-03-18T11:00:00-04:00",
      "duration": "PT60M"
    },
    "buyer": {
      "first_name": "Alice",
      "last_name": "Williams",
      "email": "alice@example.com"
    },
    "party_size": 1,
    "status": "confirmed",
    "confirmation_mode": "auto",
    "created_at": "2026-03-14T22:05:00Z",
    "updated_at": "2026-03-14T22:05:00Z"
  }
}

Get Booking -- GET /bookings/{booking_id}¶

Returns the current state of a booking. Same structure as the booking object above.

Update Booking -- PUT /bookings/{booking_id}¶

Updates mutable fields on a booking. Only buyer, recipient, and notes are mutable after creation, plus booking_question_submissions when the booking questions extension is negotiated. Omitted fields are left unchanged (partial update semantics).

When the booking questions extension is negotiated, update permission for booking_question_submissions depends on status:

{
  "booking": {
    "id": "bkg_456def",
    "notes": "Please use hypoallergenic products",
    "buyer": {
      "first_name": "Alice",
      "last_name": "Williams",
      "email": "alice.new@example.com",
      "phone_number": "+12125551234"
    },
    "updated_at": "2026-03-15T10:00:00Z"
  }
}

Confirm Booking -- POST /bookings/{booking_id}/confirm¶

Business-initiated confirmation for bookings with confirmation_mode: manual. A platform or buyer agent MUST NOT call this operation, and a booking_scoped_credential MUST NOT authorize it. Authentication of the business caller is deployment-defined.

When confirmation_mode is manual and the booking is pending, the business MUST transition it to confirmed. When confirmation_mode is auto and the booking is already confirmed, the business MUST return the current booking unchanged (idempotent). When confirmation_mode is auto and the booking is not already confirmed (including a UCP-Native unpaid booking that remains pending), the business MUST reject with invalid_transition at HTTP 200 OK in messages[].

{
  "booking": {
    "id": "bkg_456def",
    "status": "confirmed",
    "confirmation_mode": "manual",
    "updated_at": "2026-03-15T09:00:00Z"
  }
}

Cancel Booking -- POST /bookings/{booking_id}/cancel¶

Cancels a booking. Eligible from pending, requires_action, or confirmed status. Cancellation fees are applied per the service's cancellation policy.

The response populates cancellation on the booking. When a booking is terminalized because its UCP checkout was canceled and it never reached confirmed, the USP-visible booking MUST carry cancellation.reason_code: checkout_abandoned with canceled_by: system, and canceled_at MUST NOT change across reads. See Cancel Checkout.

{
  "booking": {
    "id": "bkg_456def",
    "status": "canceled",
    "cancellation": {
      "reason": "Schedule conflict",
      "canceled_by": "buyer",
      "fee": 0,
      "refund_amount": 12000,
      "canceled_at": "2026-03-15T08:30:00Z"
    },
    "payment": {
      "status": "refunded",
      "timing": "at_booking",
      "amount": 12000,
      "currency": "USD",
      "amount_due": 0,
      "transaction_id": "txn_abc123"
    },
    "updated_at": "2026-03-15T08:30:00Z"
  }
}

Reschedule Booking -- POST /bookings/{booking_id}/reschedule¶

Moves a booking to a different time slot. Rescheduling preserves the booking id -- this is not a cancel + rebook. The original slot is released and the new slot is occupied.

Eligible statuses: see Permitted Transitions by Operation. Rescheduling a canceled or terminal-state booking MUST be rejected with invalid_transition.

Confirm Payment -- POST /bookings/{booking_id}/confirm-payment¶

The universal callback the platform calls after payment succeeds. This completes the payment action in the booking's actions array. If no pending actions remain, the booking transitions to confirmed.

{
  "payment_result": {
    "status": "paid",
    "provider": "stripe",
    "transaction_id": "txn_abc123",
    "amount_paid": 12000,
    "currency": "USD",
    "order_reference": "ord_xyz789"
  }
}

{
  "usp": {
    "version": "2026-08-20",
    "capabilities": {
      "dev.usp-protocol.services.bookings": [
        { "version": "2026-08-20" }
      ]
    }
  },
  "booking": {
    "id": "bkg_456def",
    "status": "confirmed",
    "payment": {
      "status": "paid",
      "timing": "at_booking",
      "amount": 12000,
      "currency": "USD",
      "amount_due": 0,
      "transaction_id": "txn_abc123",
      "order_reference": "ord_xyz789"
    },
    "updated_at": "2026-03-14T22:06:00Z"
  }
}

payment_result Fields:

Webhooks¶

Businesses SHOULD notify platforms of state changes via webhooks. Webhook payloads MUST be signed.

Booking Webhooks¶

Webhook Payload Schema:

{
  "event": "booking.confirmed",
  "event_id": "evt_789abc",
  "booking_id": "bkg_456def",
  "order_id": "ord_ucp_001",
  "timestamp": "2026-03-15T09:00:00Z",
  "data": {
    "id": "bkg_456def",
    "service_id": "svc_massage_001",
    "service_name": "Deep Tissue Massage",
    "slot": {
      "id": "slot_20260316_1400",
      "start": "2026-03-16T14:00:00-04:00",
      "end": "2026-03-16T15:00:00-04:00",
      "duration": "PT60M"
    },
    "buyer": {
      "first_name": "Alice",
      "last_name": "Williams",
      "email": "alice@example.com"
    },
    "party_size": 1,
    "status": "confirmed",
    "confirmation_mode": "manual",
    "created_at": "2026-03-14T22:05:00Z",
    "updated_at": "2026-03-15T09:00:00Z"
  }
}

Catalog Change Webhooks¶

Businesses SHOULD notify platforms of catalog changes via webhooks. This provides a push-based complement to the pull-based service catalog feed.

Post-Booking Lifecycle¶

After a booking reaches a terminal state (completed, no_show, canceled), additional lifecycle events may occur.

Refund Tracking¶

When a refund is issued, the booking's payment object MUST be updated:

The business MUST send a booking.refund_issued webhook when a refund is processed.

Dispute Resolution¶

When a payment dispute (chargeback) is opened, the business SHOULD update the booking with dispute information and send a booking.dispute_opened webhook.

Dispute Object:

Service Delivery Events¶

For complex services (e.g., multi-step healthcare, ongoing rentals), businesses MAY emit intermediate delivery events:

These events are informational and do not change the booking's primary status.