clientId your server
trusts.
Before you start
Check these once per project. Each missing piece fails at a specific step, with a specific error:
To set the catalog up from code instead of the dashboard, see
Provision your catalog and suppliers.
The flow
Ids to store
Keep a checkout record on your server, keyed by your own checkout session id, and write each id into it as soon as you have it. A checkout that crashes or times out halfway can then resume or clean up instead of starting again.Keep these on the checkout record.
Walk through it
1
Sign in and onboard the client
Sign the client in with hosted login, then call
POST /clients/me from your
BFF with the API key and their token. It’s idempotent: 201 the first time,
200 after. Take data.clientId from the response and keep it on your server.If your checkout collected a name and phone, send them in the body. See
Onboard the client.Fails with: 401 HTTP_ERROR for a missing or expired token (sign in
again), and 403 MEMBERSHIP_INACTIVE when the business removed this
client’s access.2
Search for open times
Search with the client’s coordinates, so in-home suppliers who cover that
address come back:Keep the response’s
searchId. When the client picks a slot, keep the
supplier, the slot’s startUtc and endUtc, and the supplier’s own travel
zone: the supplier.locations[] entry with locationType: "TRAVEL_ZONE" and
an stz_ id. See
Search suppliers by availability.A slot is not a reservation. Someone else can take it until you hold it.3
Hold the slot
Hold the time the moment the client picks it. The hold carries everything the
booking will need, because convert builds the booking from the hold:The
201 gives you reservationId and heldUntil. Store both. Choose a
holdDurationMins that covers a 3-D Secure challenge, and extend the hold
while the payment page is open: re-send the same body with the
reservationId. That heartbeat, and the travel-zone fields, are covered in
Hold slots during checkout.Fails with: 409 SLOT_HELD or 409 SLOT_BOOKED when someone else got
there first. Offer another slot; don’t retry this one. A 400 VALIDATION_ERROR names the location field you left out.4
Create the order
Create one order with one Store
SINGLE_SESSION item. Pass the hold’s
reservationId, so the order prices from exactly the place the booking will
happen. Add attribution and locale:data.order.orderId and data.items[0].orderItemId. Note the nesting:
the id is not at data.orderId. The order starts DRAFT.currencyis the currency you showed the client. It must match what the region resolves to, or the order is a400. See Regional pricing.localeis copied onto every booking this order funds, and decides the language of the links in MarketBox’s emails. See Creating an order.attributionties the purchase to the search it came from. See Attribution.
422 OFFERING_NOT_PRICED, 422 SERVICE_NOT_SOLD_AS and
422 NOT_SELLABLE (a setup problem: see Before you start;
don’t retry), and
404 NOT_FOUND with Client not found for a clientId that isn’t in this
project.5
Take the payment
Create the PaymentIntent from your BFF:Hand
data.clientSecret to the browser, mount Stripe’s Payment Element, and
call stripe.confirmPayment. Card details go straight from the browser to
Stripe. See Accept payments with Stripe.Calling it again for the same order reuses the open PaymentIntent, so a retry
doesn’t create a second charge. If the amount owed has changed since, the old
intent is canceled and a new one is created, so always use the latest
clientSecret. It also records a PENDING payment on the
order, which matters if the client abandons: see
Abandoned checkout.Fails with:409 CONFLICT,Project prj_… is not ready to accept card payments: the business’s Stripe account isn’t connected, or can’t take charges yet.400 BAD_REQUEST,Order ord_… is CANCELLED; cannot take payment: only aDRAFTorPENDINGorder takes a payment.400 BAD_REQUEST,Nothing is owed on this order: it is already paid or comped in full. Skip the payment step.409 PAYMENT_IN_FLIGHT: a card payment on this order is already moving. Don’t start another. Poll the order until it’sPAID.
6
Wait for PAID, then convert the hold
When The
stripe.confirmPayment resolves, the browser tells your BFF. The BFF
polls GET /orders/{orderId} until data.status is PAID, then converts:201 is not wrapped in data. Read created[].bookingId off the
body and store it.The public API sends you no webhooks. Stripe tells MarketBox, and the order
flips to PAID a second or two later. Convert doesn’t check payment, so the
order of these two calls is your choice:- Poll until
PAID, then convert. The safe default. Poll once a second for up to 15 seconds. - Convert as soon as
confirmPaymentresolves, whenheldUntilis close and you can’t wait. This books before the payment is confirmed. Keep polling, and reconcile an order that never reachesPAID: see Tracking state without webhooks.
PAID order to book. A client’s package
credits do, but convert doesn’t enforce that for a package hold either: your
server must see PAID before it converts one. See
Book a client’s package credit.Convert is idempotent on reservationId. A retry after a timeout replays the
same bookings; it never books twice.Fails with:409 HOLD_EXPIRED: you converted afterheldUntil. If the time is still free, hold it again and convert the new hold against the same order item.409 SLOT_BOOKED: someone took the time after your hold lapsed. Offer the client a new time and convert a new hold against the same order item.409 ORDER_CANCELLED: the order was cancelled. Don’t retry.422 NOT_SELLABLE: the offering was setINACTIVEor deleted after the order was placed. A service that leftLIVEdoesn’t block convert.
7
Show the confirmation
Read the booking in full for the confirmation page:It returns the booking, its service lines and both parties’ names, so the page
can say “Tuesday at 9:30 with Priya” without another call. The booking is
SCHEDULED.Don’t send your own confirmation email. Convert already sent the client their
confirmation, and the supplier their new-booking notice. See
Emails.Abandoned checkout
A client who closes the tab leaves a hold and, often, aDRAFT order. Clean
both up when your checkout session expires.
-
Release the hold.
POST /holds/{reservationId}/releasefrees the supplier’s time at once. It answers200for a released, converted or unknown hold, so it’s safe to call blindly. Retry a409 OCCUPANCY_CONTENTION. -
Delete or cancel the order. An order that booked nothing and took no
money is noise:
DELETE /orders/{orderId}removes it. If it holds a booking, or aPENDINGorSUCCEEDEDpayment, delete refuses it. Once you’ve created a PaymentIntent, the order holds aPENDINGpayment, so an order abandoned on the payment page can’t be deleted:Cancel it instead, with a reason:
PENDING payment means the client may still finish paying, for example
after a bank redirect. Check the order before you cancel it: if it reads
PAID, convert instead, or hold again if the hold has lapsed.
For what happens to an order after checkout, such as changing its items or
cancelling it later, see
Order lifecycle after checkout.
Reference
Endpoints used in this guide
Where each failure lands
See Errors for the envelope and retry rules.