Skip to main content
This page is the map. It walks one in-home session from sign-in to the confirmation screen, names every call in order, and says where each common failure lands. Each step links to the guide that covers it in depth. The flow, in one line: sign in → onboard → search → hold → order → pay → convert → confirm. Every call below goes through your backend-for-frontend (BFF). The browser never holds the API key, and never sends a 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 SINGLE_SESSION item. Pass the hold’s reservationId, so the order prices from exactly the place the booking will happen. Add attribution and locale:
Store data.order.orderId and data.items[0].orderItemId. Note the nesting: the id is not at data.orderId. The order starts DRAFT.
  • currency is the currency you showed the client. It must match what the region resolves to, or the order is a 400. See Regional pricing.
  • locale is copied onto every booking this order funds, and decides the language of the links in MarketBox’s emails. See Creating an order.
  • attribution ties the purchase to the search it came from. See Attribution.
Fails with: 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 a DRAFT or PENDING order 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’s PAID.
6

Wait for PAID, then convert the hold

When stripe.confirmPayment resolves, the browser tells your BFF. The BFF polls GET /orders/{orderId} until data.status is PAID, then converts:
The 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 confirmPayment resolves, when heldUntil is close and you can’t wait. This books before the payment is confirmed. Keep polling, and reconcile an order that never reaches PAID: see Tracking state without webhooks.
A single session doesn’t need a 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 after heldUntil. 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 set INACTIVE or deleted after the order was placed. A service that left LIVE doesn’t block convert.
If the client paid and you can’t book them, the money stays on the order. The public API has no refund endpoint: the business refunds from the MarketBox dashboard. Keeping the heartbeat running until convert returns is what keeps you out of this case.
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, a DRAFT order. Clean both up when your checkout session expires.
  1. Release the hold. POST /holds/{reservationId}/release frees the supplier’s time at once. It answers 200 for a released, converted or unknown hold, so it’s safe to call blindly. Retry a 409 OCCUPANCY_CONTENTION.
  2. 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 a PENDING or SUCCEEDED payment, delete refuses it. Once you’ve created a PaymentIntent, the order holds a PENDING payment, so an order abandoned on the payment page can’t be deleted:
    Cancel it instead, with a reason:
A 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.