Skip to main content
This guide covers changing a booking after it’s made, from your server with the API key:
  • 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.
None of these moves money. The public API has no refund endpoint. A refund is made by the business in the MarketBox dashboard.
A client can’t cancel or reschedule through the client plane. There is no /clients/me route for it. If your client account page offers either, your server makes the change with the API key, and your server is the only thing checking that the booking is the client’s. Resolve the client from their token with POST /clients/me, read the booking, and refuse when its clientId isn’t theirs. See Show booking and order history.
Your API key acts for the business. The service’s participant settings don’t restrict it: no notice window, no “clients may not cancel”. When a client asks for a change in your app, apply the business’s rules yourself before you call. Read them from 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

The 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.
  • cancellationReason is required. Leave it out and nothing is cancelled: 400 VALIDATION_ERROR, cancellationReason: cancellationReason is required when status is CANCELLED.
  • creditTreatment is 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:
A returned session shows up in 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:
Once 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:
Send both ends: the booking doesn’t keep its length for you. The 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.
A reschedule checks only that the supplier is free. It refuses a time that overlaps another booking or a hold of that supplier. It doesn’t check the supplier’s working hours or blocked time, so a PATCH can put a session at 3 a.m., or on the supplier’s day off.So find the new time with search first, and send only a slot it returned: POST /availability/suppliers with the booking’s service, offering and location, and the supplier’s entry in the results. See Search suppliers by availability.
Only a SCHEDULED or STARTED booking can move. Changing the time or supplier of any other booking is refused, and nothing is written:
The booking’s other fields, such as 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:
The order is 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:
Deleting a booking that’s already 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.