bookings

Book a slot from availability.get (classes need session_id, a course its series_id; appointments and rentals need starts_at). Pass hold_minutes to hold it instead, and idempotency_key so retries never book twice.

post/bookings

Request

  • Base URL: https://daybag.io/api/v1
  • URL: https://daybag.io/api/v1/bookings
  • Auth: HTTP bearer

Request body

offering_idstring uuid required
session_idstring uuid
series_idstring uuid

A course (offering course: true): the entry availability.get gives, booked whole from its first time to come

starts_atstring

ISO 8601 instant, e.g. 2026-10-03T15:00:00Z

quantityinteger

class: seats · appointment: people, 1 for one-on-one · rental: items

periodsinteger

Rentals: how many periods (e.g. days)

customer_idstring uuid
notesstring
answersobject

Answers to the offering's questions (offerings.get), keyed by each question's id: text, a choice's option exactly as listed, or true/false for yes_no. A required one left out answers 400 answers_required with its question_id

promo_codestring

A promo code the guest gave, in any case: taken off total_cents, or refused with 400 code_invalid, code_expired or code_used_up

gift_card_codestring

A gift card's code the guest gave, in any case, spaced or not: it pays what's due at booking (after promo_code, and the offering's deposit where it asks one), all it has at most, and the booking keeps gift_card_id and gift_cents. Refused with 400 gift_card_invalid or gift_card_empty, or 409 gift_card_short when its balance moved

hold_minutesinteger

Hold the place this many minutes (status held) instead of confirming; then call bookings.confirm

idempotency_keystring uuid

A UUID you generate per booking: retrying with it returns the same booking instead of booking twice

Response

Success

idstring required
org_idstring required
offering_idstring required
session_idstring nullable required

Classes only; a course's, the first time it was booked from

series_idstring nullable

A course's booking: the calendar entry it holds a seat in every time of, from session_id's on. Null for a booking of one time

customer_idstring required
starts_atstring required

ISO 8601 timestamp (UTC)

ends_atstring required

ISO 8601 timestamp (UTC)

quantityinteger required

class: seats · appointment: people, 1 for one-on-one · rental: items

total_centsinteger required

In the org's currency, in the currency's minor units (cents; whole yen for zero-decimal currencies): what's left to pay after a promo code

promo_codestring nullable

The promo code it was booked with, as stored; kept after the code is deleted. Null without one

discount_centsinteger

What the promo code took off, in the currency's minor units (cents; whole yen for zero-decimal currencies); 0 without one

gift_card_idstring nullable

The gift card that paid part of it (gift_cards_get); null without one

gift_centsinteger

What the gift card paid, in the currency's minor units (cents; whole yen for zero-decimal currencies), counted as paid: taken off the card once the booking is confirmed, back on it if it's cancelled; 0 without one

referencestring required

Short code the guest sees, e.g. 0GWYRZ2V

status'held' | 'confirmed' | 'cancelled' required

held, confirmed or cancelled; a hold keeps its place until expires_at

sourcestring required

Where it was made: dashboard, api, mcp, widget, octo (a reseller, over /api/octo), or assistant (held for a guest over /api/mcp/book/{slug}, who confirms it)

notesstring required
answersobject

The guest's answers to its offering's questions, keyed by question id: text (a choice's option, as listed), or true or false for a yes or no

metadataunknown required
cancelled_atstring nullable required

ISO 8601 timestamp (UTC)

created_atstring required

ISO 8601 timestamp (UTC)

expires_atstring nullable required

ISO 8601 timestamp (UTC)

handlestring required

Opens the guest's own page, /b/{handle}: their messages, bookings and cancel. daybooked sends it only to the guest's email; never give it to whoever is booking, who may have typed someone else's email. bookings.resend emails it to the guest again

checkout_urlstring nullable required

Stripe Checkout for a hold being paid online

paid_atstring nullable required

ISO 8601 timestamp (UTC)

paid_centsinteger nullable

What's been paid so far, online and by hand, in the currency's minor units (cents; whole yen for zero-decimal currencies): less than total_cents after a deposit, the rest due at the start. Null on bookings from before deposits: the whole total once paid_at is set

payment_intent_idstring nullable required

The Stripe payment, when paid online

charged_centsinteger nullable

What its Stripe Checkout charged, a deposit or the whole total, in the currency's minor units (cents; whole yen for zero-decimal currencies): all that cancelling can refund. Null when not paid online, and on bookings from before deposits (the whole total)

refund_idstring nullable required

The Stripe refund of a payment made online, once Stripe took it (cancelling refunds in full, unless refund_cents says otherwise)

refund_centsinteger nullable

What cancelling refunds of a payment made online, as bookings.cancel's refund chose, in the currency's minor units (cents; whole yen for zero-decimal currencies): null the whole payment, 0 none (the business kept it), otherwise that part

refunded_atstring nullable required

ISO 8601 timestamp (UTC)

refund_failed_atstring nullable required

ISO 8601 timestamp (UTC)

refund_errorstring nullable required

Why the refund failed, as Stripe said

refund_next_atstring nullable required

ISO 8601 timestamp (UTC)

guest_cancel_hoursinteger nullable

The window promised when it was booked: the guest may cancel on their page, or change its time, until this many hours before the start (or by the org's rule now, if kinder)

nudged_atstring nullable

ISO 8601 timestamp (UTC)

choose_bystring nullable

ISO 8601 timestamp (UTC)

waiver_tokenstring nullable

When its offering asks guests to sign your waiver: the signing link for everyone on the booking, /w/{waiver_token}. It only lets someone sign

confirmed_atstring nullable

ISO 8601 timestamp (UTC)

updated_atstring nullable

ISO 8601 timestamp (UTC)

reseller_referencestring nullable

A reseller's own reference for a booking it made over OCTO

cancel_reasonstring nullable

Why a reseller cancelled it, in its words

checked_in_atstring nullable

ISO 8601 timestamp (UTC)

no_show_atstring nullable

ISO 8601 timestamp (UTC)

Changes

No recorded changes to this operation across all 1 revision of this API.