- Cancel one booking, and decide what happens to its package session.
- Reschedule it to another time or supplier.
- Cancel a whole order, and every session it still has.
- Delete a booking that was made by mistake.
participantSettings.client on
GET /services/{serviceId}. canRescheduleBookings and
rescheduleNoticeHours say whether, and until when, a client may move a
session. Clients can’t cancel in MarketBox’s own flows, so offering it is your
business’s decision.
A supplier changes their own bookings through the
supplier plane, where
those settings do apply.
Cancel a booking
200 returns the booking in data, status: "CANCELLED". In the same
write, MarketBox frees the supplier’s time and settles the session the
booking drew on. Then it emails the client, the supplier and the business’s
staff. Your cancellationReason stays on the booking and isn’t in the email.
cancellationReasonis required. Leave it out and nothing is cancelled:400 VALIDATION_ERROR,cancellationReason: cancellationReason is required when status is CANCELLED.creditTreatmentis for package sessions only.
What happens to the session
Your key can cancel only a session still to come, so the default for your
cancel is
RETURN. A session that has already taken place
(AWAITING_CONFIRMATION, DISPUTED) defaults to FORFEIT instead. Only an
operator can cancel one of those.
A single session has no credit to return or forfeit, so naming one is refused,
and nothing is cancelled:
quantityRemaining on the client’s credit,
and in quantityReturned. See
Cancelling and the package credit.
Cancelling refunds nothing, whether the session was a single session or a
package session you returned or forfeited. If the client should get money
back, the business refunds them in the dashboard.
When a booking can be cancelled
Anything else is a
400 that names the booking’s current status:
bookingEndUtc has passed, your key can’t cancel. It doesn’t matter
what the booking reads. A booking moves to AWAITING_CONFIRMATION in an
hourly sweep, not at bookingEndUtc. Until the sweep reaches it, it still
reads SCHEDULED or STARTED, and a cancel is the same 400, such as
from STARTED to CANCELLED. Waiting for the sweep doesn’t help. See
Tracking state without webhooks.
Settle a session that ended instead, with
POST /bookings/{bookingId}/status:
A
SUPPLIER attendance report, POST /bookings/{bookingId}/reports, settles
any of the three as well. See
Attendance and disputes.
If the session really didn’t happen, an operator can cancel it in the
MarketBox console. An operator’s cancel of a session that has taken place
forfeits its package session by default. The operator chooses RETURN to
give it back.
409 VERSION_CONFLICT means something else changed the booking at the same
moment, for example the supplier’s own cancel, or an order cascade. Re-read
the booking and decide again. If it’s already CANCELLED, you’re done.
Reschedule a booking
PATCH /bookings/{bookingId} moves the time, the supplier, or both:
200
returns the booking, with its bookingLocal* fields worked out again in its
bookingTz. MarketBox emails the client, the supplier and the business
about the move. A reassigned booking also tells the previous supplier.
You can also send supplierId, bookingTz, capacity, and for an in-home
booking latitude, longitude and address. You can’t change the
locationType or the locationId, or the client. To move a session to
another venue, cancel it and book a new one.
Only a SCHEDULED or STARTED booking can move. Changing the time or
supplier of any other booking is refused, and nothing is written:
capacity, can still be edited.
A reschedule doesn’t touch the order: the price, the order item and the
package session stay as they were.
To move a session of a package plan before it’s booked, adjust the slate
instead. See Let clients adjust a proposed slate.
When a reschedule is refused
Nothing is written when:
The
409 bodies carry conflicts[] and a hint. See
The three supplier-time conflicts.
Cancel a whole order
To call off everything a client bought, cancel the order:CANCELLED when the call returns. Its bookings are cancelled a
few seconds later, and their package sessions released. Only SCHEDULED
and STARTED bookings whose session is still ahead are cancelled. Sessions
that already happened are left alone. The client gets one email listing every
cancelled session. See
A cancelled order’s bookings.
A CANCELLED order is final, and nothing more can be booked from it: every
route that creates a booking answers 409 ORDER_CANCELLED. Cancelling doesn’t refund the
order. For everything else that happens to an order after it’s placed, see
Order lifecycle after checkout.
Cancel or delete?
A delete is a cancel first. You can delete only a booking your key could
cancel through
/status. A booking that has taken place or been settled
(AWAITING_CONFIRMATION, COMPLETED, a no-show) is refused, and nothing
changes:
CANCELLED keeps that cancel’s settlement,
and sends no second cancellation email. Delete only bookings that shouldn’t
have existed. For anything that was called off, cancel.
An order has the same pair. Delete an order only when it books nothing and
took no money. Otherwise DELETE /orders/{orderId} is 409 ORDER_NOT_DELETABLE, and you cancel it instead. See
The order lifecycle.
Reference
Endpoints used in this guide
All take the API key alone.
Errors and edge cases
See Errors for the envelope, and
Concurrency for the
409s.