What changes on its own
Two things never change on their own:
- Nothing completes a booking. It waits in
AWAITING_CONFIRMATIONuntil the supplier reports attendance, the business settles it, or your key sets an outcome. No timer completes it. See The booking lifecycle. - Package credits don’t expire by themselves. A credit’s
expiresAtis checked when someone tries to book it. Nothing changes on the order at that instant.
An order becomes PAID
A card payment settles when Stripe tells MarketBox, not when the browser says
so. Poll the order:
- During checkout, once a second for about 15 seconds after
stripe.confirmPaymentresolves. That covers almost every payment. See Accept payments with Stripe. - After that, keep the
orderIdon your server and check it again: every few minutes for the first hour, then hourly for a day. A payment whose webhook was missed is settled by MarketBox’s nightly reconciliation, so it can take up to a day.
GET /transactions?orderId=… shows the payment itself: a STRIPE row that is
PENDING until Stripe confirms it, then SUCCEEDED.
A cash, bank-transfer or comp payment you record with
POST /orders/{orderId}/transactions settles in the same request. Its
response is already the answer. See
Record offline payments.
A cancelled order’s bookings
POST /orders/{orderId}/status with CANCELLED returns as soon as the order
is cancelled. The order’s bookings are cancelled afterwards, by a cascade
that usually finishes within seconds. A booking you read straight after the
call can still say SCHEDULED.
The cascade:
- cancels
SCHEDULEDandSTARTEDbookings, and returns their package sessions to the order item; - leaves
AWAITING_CONFIRMATIONandDISPUTEDbookings alone, because those sessions have already happened; - leaves settled bookings alone;
- sends the client one email listing every cancelled session, and each supplier one listing theirs.
SCHEDULED because the hourly sweep hasn’t reached it. That booking becomes
AWAITING_CONFIRMATION and waits for its outcome, like any session that
happened.
To confirm the cascade finished, read each booking the order funded. For
cancelling an order and the rest of its life after checkout, see
Order lifecycle after checkout. The
bookingIds are the ones convert or POST /bookings returned. For a package
line, GET /orders/{orderId}/package-bookings?orderItemId=… lists them.
A hold lapses
Nothing happens atheldUntil. The hold simply stops blocking the supplier’s
time, and anyone can book it. GET /holds/{reservationId} can still say
HELD afterwards, so compare heldUntil with the current time rather
than trusting status.
You don’t need to poll a hold. Keep it alive with the heartbeat while the
client pays, and expect 409 HOLD_EXPIRED if you convert too late. See
Hold slots during checkout.
A session ends
A booking doesn’t change atbookingEndUtc. An hourly sweep moves
SCHEDULED and STARTED bookings that have ended to AWAITING_CONFIRMATION,
so the change shows up to about an hour later.
In that gap the booking still reads SCHEDULED or STARTED, and two things
behave differently:
-
Your key can’t cancel it. Your key can cancel only before
bookingEndUtc:Waiting for the sweep doesn’t help: your key can’t cancel anAWAITING_CONFIRMATIONbooking either. Settle it instead, withCOMPLETED(fromSTARTED) or a no-show. See When a booking can be cancelled. -
Attendance can already be reported, by the supplier or by your key, and
a
SUPPLIERreport settles the booking directly.
A booking is settled, or disputed
The supplier’s attendance report settles a booking:COMPLETED when they
attended, SUPPLIER_NO_SHOW when they didn’t. A SUPPLIER report your key
files through POST /bookings/{bookingId}/reports does the same. A client’s report that they
didn’t attend turns the booking DISPUTED when the supplier says they did. It
also turns a COMPLETED booking DISPUTED within 24 hours of it
becoming COMPLETED, whoever completed it.
So don’t treat COMPLETED as final until 24 hours after its
statusUpdatedAt. If you pay suppliers, or report revenue, from completed
bookings, run that 24 hours later. An operator resolves a DISPUTED booking
in the MarketBox console. Your key can’t. See
Attendance and disputes.
A supplier portal can prompt for overdue reports with the MY_REPORTS_OVERDUE
alert condition. See
Overdue reports.
How to poll
There’s no “changed since” filter. Bookings and orders carryupdatedAt and
version, but no list filters on them. Two patterns cover most needs:
- Re-read the ids you’re waiting on. For a checkout, a cancellation or a
dispute window, poll
GET /orders/{orderId}orGET /bookings/{bookingId}until it reaches the state you expect. - Re-read a window, and compare. For “what changed today”, list
GET /bookings?startDate=…&endDate=…and compare each booking’sversionwith the one you stored. A higherversionmeans something changed.startDateandendDatefilter on when the session starts, in UTC, not on when it changed, so choose a window that covers the sessions you care about.
- A read straight after a write can be a second behind. If a value looks unchanged right after you changed it, read again.
- Back off on
429. Wait before you retry, for as long as theRetry-Afterheader says when there is one. See Retry guidance. - Poll by what you’re waiting for. Once a second for a checkout’s payment, every 15 minutes for the day’s bookings, hourly for disputes. Polling every booking every second spends your quota on nothing.
Suggested cadence
MarketBox emails the client and the supplier about confirmations,
cancellations and moves. You don’t need to poll in order to notify them. See
Emails.