CBMS Partner API changelog

The Partner API is /api/v1.

• Additive, backward-compatible changes (new optional fields, new endpoints, new webhook event types) ship in v1. Ignore fields you do not recognize.
• A breaking change (removing or renaming a field, changing a field's meaning or type, changing required parameters) requires a new version prefix. It will not be a silent change to v1.
• Deprecated behaviour is announced here with a transition period before removal.

The field-level contract is GET /api/v1/openapi.json (unauthenticated).

---

2026-09-05 — contract hygiene

Documentation and OpenAPI alignment with the already-implemented Partner API. No new booking behaviour.

Added

• GET /api/v1/openapi.json is the public, unauthenticated OpenAPI document. GET /openapi.json remains as a compatibility alias.
• OpenAPI servers list production (https://cbms.venuesetu.com/api/v1), sandbox (https://stage.cbms.venuesetu.com/api/v1), and local development.
• OpenAPI now includes partner-facing waitlist (POST/GET /waitlist, DELETE /waitlist/{id}), package purchase lookup (GET /packages/purchases/{id}, GET /packages/active), hold customer_phone, confirm use_package_credit / package_credit_consumed, booking list filters customer_phone / customer_name, and webhook secret_key on create and rotate responses.
• OpenAPI info records x-api-version: v1 and the additive-in-v1 policy. This changelog is the version lifecycle.

Changed

• Hold, confirm, and webhook examples no longer send partner_id in the body. Partner identity is the API key.
• Examples no longer use a pk_live_… key prefix. Issued keys are opaque hex.
• Webhook event for a confirmed booking is documented as booking_created (not booking_confirmed, which is an internal notification template name).
• List-webhooks response shape is documented as { success, partner_id, count, data }.
• Error schema documents request_id and details.
• Default rate limit is documented: 60 requests / 60 seconds per API key. Webhook delivery: 5 attempts, 10s timeout, backoff 5 / 15 / 30 / 60 minutes, then dead-letter.
• Idempotency docs distinguish hold creation (same key returns the original hold, including a different slot) from confirm/cancel/refund/package purchase (409 on mismatch).

Fixed

• The documented OpenAPI URL (GET /api/v1/openapi.json) was not mounted. /api/v1 is behind the API-key validator; only GET /openapi.json at the process root actually served the spec. Both URLs now serve the same document without authentication.

Deprecated

• None.

Breaking

• None in this entry. /api/v1 is unchanged as the version prefix.

---

2026-09-05 — sandbox-first servers

Documentation metadata only. No endpoint behaviour changed.

Changed

• OpenAPI servers lists sandbox (https://stage.cbms.venuesetu.com/api/v1) first, then production, then local. Sandbox is the recommended integration host; production is for certified partners only.

---

Previously shipped (before this changelog)

Recorded so a new partner is not surprised. These were already true of the live Partner API when this file started; dates are not reconstructed.

Added (already live)

• Venue and resource discovery: GET /partner/venues, GET /partner/venues/{venueId}, GET /partner/venues/{venueId}/resources.
• Partner hold release: POST /partner/holds/{id}/cancel with required idempotency_key.
• Booking refund: POST /bookings/{id}/refund.
• Durable per-partner idempotency on hold, confirm, cancel, refund, and package purchase. Redis is a 1-hour fast path; retries after a Redis flush still replay from Postgres. Confirm/cancel/refund/package-purchase reuse of a key for a different logical request is 409. Hold creation returns the original hold (201) even if the reused key is sent with a different slot.
• Canonical webhook signing: X-CBMS-Signature: sha256=<hex> over {timestamp}.{rawBody}; X-CBMS-Timestamp is the send time of that delivery attempt; 5-minute replay window.
• Webhook event type hold_cancelled.
• Isolated sandbox host: https://stage.cbms.venuesetu.com (GET /health → {"sandbox": true}).

Changed (already live)

• partner_id on hold/confirm/webhook bodies is ignored. The API key is the partner identity.
• Hold creation does not require partner_id in the body (it used to 400 even though the spec never required it).
• Missing hold/booking ids return 404, not 500.

Fixed (already live)

• OpenAPI availability path is /slots/availability (it previously documented a non-existent /bookings/availability).
• Webhook signature scheme in the guide matches what the server sends.
• Partner venue/resource discovery, package purchase, and waitlist join are reachable with a partner API key (a router mount-order bug had required a manager session).