Bookings

Confirm a hold, then read it back.

Auth: x-api-key. You only see bookings your partner owns.

Confirm

POST /api/v1/bookings/confirm
Content-Type: application/json
x-api-key: <your-api-key>

{
  "hold_id": "…",
  "payment_reference": "pay_example_ref",
  "customer_name": "Aarav Sharma",
  "customer_phone": "9876543210",
  "idempotency_key": "confirm-9f2a-4c1e-8b7d-1a2b3c4d5e6f"
}

payment_reference is opaque — CBMS does not charge a card on this call. Optional: customer_email, use_package_credit.

201: booking_id, slot_id, status: "BOOKED", booked_at, price_rupees. If you set use_package_credit, the booking was paid with one credit from a package you sold to this customer, and the response also carries package_credit_consumed: true (a replay of the same confirm reports it too). See Paying with a package credit.

Must run before the hold’s hold_expiry_at.

HTTP	error	Meaning
403	UNAUTHORIZED	The hold belongs to another partner.
404	HOLD_NOT_FOUND	Unknown hold id.
409	HOLD_EXPIRED	The hold's window passed. Not booked.
409	SLOT_NOT_AVAILABLE	The held slot can no longer be booked (its state changed, or the venue blacked it out). Not booked.
409	TRANSFORMATION_CONFLICT	A linked court sharing the same physical space is now reserved. Not booked.
409	INVALID_HOLD_STATE	The hold is already confirmed, cancelled, or expired.
409	IDEMPOTENCY_KEY_MISMATCH	This confirm key was already used for a different hold.
409	PACKAGE_CREDIT_UNAVAILABLE	You set use_package_credit, and no active credit from a package you sold to this customer is available at this venue. Not booked, nothing deducted, and the hold is still active until it expires.

You take payment before confirm, so the three Not booked answers can leave you with a customer's payment and no booking. Do not show the booking as confirmed, do not retry the same confirm, do not ask the customer to pay again, and refund or reconcile the payment in your own payment flow — CBMS moves no money. Step by step: If confirm fails after you took payment.

Reusing this confirm key for a different hold is 409. Same key and same hold → the original booking_id (201), even if the rest of the body differs: the retry does not update the customer or payment_reference. If you need to correct those, there is no partner update call; contact support.

Get one

GET /api/v1/bookings/{bookingId}
x-api-key: <your-api-key>

Missing id and another partner’s booking both return 404 BOOKING_NOT_FOUND.

200 (the booking object itself, not wrapped):

{
  "booking_id": "…",
  "hold_id": "…",
  "slot_id": "…",
  "venue_id": "a0000000-0000-4000-8000-000000000001",
  "partner_id": "your-partner-id",
  "resource_id": "badminton-court-1",
  "slot_start": "2026-09-20T12:30:00.000Z",
  "slot_end": "2026-09-20T13:30:00.000Z",
  "status": "BOOKED",
  "booked_at": "2026-09-20T12:12:43.812Z",
  "price_rupees": 600,
  "payment_reference": "pay_example_ref",
  "payment_method": "…",
  "customer_name": "Aarav Sharma",
  "customer_phone": "9876543210"
}

status is BOOKED, CANCELLED or REFUNDED. Field-level detail is in the OpenAPI reference.

List

GET /api/v1/bookings?venue_id=<uuid>&from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50
x-api-key: <your-api-key>

Newest booked_at first. venue_id filters within your bookings. Optional customer_phone, customer_name and status. partner_id in the query is ignored.

• limit is at most 100.
• from / to are read as UTC days by default. Add date_basis=venue_local (with venue_id) to read them as the venue's local calendar days.
• Paging: the response carries bookings, has_more and next_cursor. Send cursor=<next_cursor> with the same other parameters to get the next page.

{
  "bookings": [ { "booking_id": "…", "status": "BOOKED", "slot_start": "…", "slot_end": "…", "price_rupees": 600, "…": "…" } ],
  "has_more": false,
  "next_cursor": null,
  "applied_filters": { "…": "…" }
}

This list is what you reconcile against (see Webhooks).

To undo a booking: Cancellations.