> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client checkout, end to end

> The whole client booking flow on one page — sign in, search, hold, order, pay, convert, confirm — with the ids to keep and where each failure is handled.

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)](https://docs.gomarketbox.com/guides/booking-flow-auth.md#the-bff-pattern). 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:

| You need | Without it |
| - | - |
| A service with `status: "LIVE"`. | `POST /orders` is `422 NOT_SELLABLE`. Supplier profiles also leave it out of their `services`, in `GET /suppliers` and on every search result, so your storefront can't show who offers it. |
| An `ACTIVE` offering of that service, with exactly one `DEFAULT` price rule. | `POST /orders` is `422 OFFERING_NOT_PRICED`, or `422 NOT_SELLABLE` for an offering that isn't `ACTIVE`. |
| An `ACTIVE` `SINGLE_BOOKING` business model on the service (`PACKAGE` to sell packages). | `POST /orders` is `422 SERVICE_NOT_SOLD_AS`. |
| A supplier linked to the service, with an `ACTIVE` schedule for the offering. | Search doesn't offer that supplier. |
| A place: a `PHYSICAL` Location for venue sessions, or a travel zone on the supplier's schedule for in-home ones. | Search returns nobody for that place. See [Set up a mobile supplier's service area](https://docs.gomarketbox.com/guides/set-up-a-mobile-supplier-service-area.md). |
| A connected Stripe account with charges enabled. | `POST /orders/{orderId}/payment-intent` is `409 CONFLICT`. See [Accept payments with Stripe](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md#prerequisites). |
| An API key with Standard API access. | `403 CAPABILITY_NOT_GRANTED` on every call. |
| An Application with hosted sign-in, whose tokens your BFF forwards. | `401` on `POST /clients/me` for a token from another Application. See [Build a booking flow](https://docs.gomarketbox.com/guides/booking-flow-auth.md). |

To set the catalog up from code instead of the dashboard, see
[Provision your catalog and suppliers](https://docs.gomarketbox.com/guides/provision-catalog-and-suppliers.md).

## The flow

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant BFF as Your BFF
    participant MB as MarketBox API
    participant S as Stripe
    B->>BFF: Sign in (hosted login, PKCE)
    BFF->>MB: POST .../clients/me
    MB-->>BFF: { data: { clientId } }
    B->>BFF: Search this address, this week
    BFF->>MB: POST .../availability/suppliers
    MB-->>BFF: { searchId, data: [{ supplier, days }] }
    B->>BFF: Pick a slot
    BFF->>MB: POST .../holds { intervals, heldBy }
    MB-->>BFF: { reservationId, heldUntil }
    BFF->>MB: POST .../orders { reservationId, attribution, locale, items }
    MB-->>BFF: { data: { order, items } }
    BFF->>MB: POST .../orders/{orderId}/payment-intent
    MB-->>BFF: { data: { clientSecret } }
    B->>S: stripe.confirmPayment
    S-->>MB: Webhook: order → PAID
    BFF->>MB: GET .../orders/{orderId} (poll until PAID)
    BFF->>MB: POST .../holds/{reservationId}/convert
    MB-->>BFF: { created: [{ bookingId }] }
    BFF->>MB: GET .../bookings/{bookingId}/aggregate
    BFF-->>B: Confirmation
```

## 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.

> [!NOTE]
>
> **Keep these on the checkout record.**
>
> | Id | From | Needed for |
> | - | - | - |
> | `clientId` | `POST /clients/me` | The order. Never from the browser. |
> | `heldBy` | You: your checkout session id | Every heartbeat, and convert. Keep it stable for the whole checkout. |
> | `reservationId` | `POST /holds` | The order, the heartbeat, convert, release. |
> | `searchId` | The search response | The order's `attribution`. |
> | `orderId` | `POST /orders`, at `data.order.orderId` | The payment intent, polling, convert, cancel. |
> | `orderItemId` | `POST /orders`, at `data.items[0].orderItemId` | Convert. |
> | `bookingId`s | Convert, at `created[].bookingId` | The confirmation page, and every later change. |
> | `idempotencyKey` | You, once per attempt | Only when you book package credits with `.../package-bookings`, or record a payment with `.../transactions`. Reuse it on a retry. |

## 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](https://docs.gomarketbox.com/guides/booking-flow-auth.md#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:

```json theme={null}
// POST /v1/projects/{projectId}/availability/suppliers
{
  "serviceId": "srv_01kv60qg12e82acr78edfnjhvv",
  "offeringId": "off_01kv60qge5eh59ap0gw0pqrrys",
  "lat": 43.6532,
  "lng": -79.3832,
  "lookAheadStartDate": "2026-07-09T00:00:00-04:00",
  "lookAheadDays": 7,
  "timezone": "America/Toronto"
}
```

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](https://docs.gomarketbox.com/guides/search-suppliers-by-availability.md).

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:

```json theme={null}
// POST /v1/projects/{projectId}/holds
{
  "intervals": [
    {
      "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
      "startUtc": "2026-07-09T13:30:00.000Z",
      "endUtc": "2026-07-09T14:00:00.000Z",
      "bookingTz": "America/Toronto",
      "locationType": "TRAVEL_ZONE",
      "locationId": "stz_01kv60qgs4e4nbjhzradnqtj0h",
      "latitude": 43.6532,
      "longitude": -79.3832,
      "address": {
        "addressOneLine": "100 Queen St W, Toronto, ON M5H 2N2, Canada",
        "streetNumber": "100",
        "streetName": "Queen St W",
        "city": "Toronto",
        "state": "ON",
        "country": "CA",
        "zipCode": "M5H 2N2"
      }
    }
  ],
  "heldBy": "checkout_9f2c1b",
  "holdDurationMins": 15
}
```

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](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md).

**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`:

```json theme={null}
// POST /v1/projects/{projectId}/orders
{
  "clientId": "cli_01kx16f0a1c7b2sd91xzq3mn5p",
  "currency": "CAD",
  "locale": "en-CA",
  "reservationId": "resv_01kx16f0a1c7b2sd91xzq3mn5p",
  "attribution": {
    "searchId": "<searchId from the search response>",
    "sessionKey": "sess-4f9a2c",
    "surface": "results"
  },
  "items": [
    {
      "skuType": "SINGLE_SESSION",
      "serviceId": "srv_01kv60qg12e82acr78edfnjhvv",
      "offeringId": "off_01kv60qge5eh59ap0gw0pqrrys",
      "quantity": 1
    }
  ]
}
```

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](https://docs.gomarketbox.com/concepts/regional-pricing.md).
* `locale` is copied onto every booking this order funds, and decides the
  language of the links in MarketBox's emails. See
  [Creating an order](https://docs.gomarketbox.com/resources/orders.md#creating-an-order).
* `attribution` ties the purchase to the search it came from. See
  [Attribution](https://docs.gomarketbox.com/resources/orders.md#attribution).

**Fails with:** `422 OFFERING_NOT_PRICED`, `422 SERVICE_NOT_SOLD_AS` and
`422 NOT_SELLABLE` (a setup problem: see [Before you start](#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:

```
POST /v1/projects/{projectId}/orders/{orderId}/payment-intent
```

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](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md).

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](#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:

```json theme={null}
// POST /v1/projects/{projectId}/holds/{reservationId}/convert
{
  "orderId": "ord_01kx16ek2jf4r9da74adf6m4h0",
  "orderItemId": "oi_01kx16ek2kf2fsc9x7b2n1dfc9",
  "heldBy": "checkout_9f2c1b"
}
```

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](https://docs.gomarketbox.com/concepts/tracking-state-without-webhooks.md).

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](https://docs.gomarketbox.com/guides/book-a-package-credit.md).

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:

```
GET /v1/projects/{projectId}/bookings/{bookingId}/aggregate
```

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](https://docs.gomarketbox.com/concepts/emails.md).

## 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:

   ```json theme={null}
   {
     "code": "ORDER_NOT_DELETABLE",
     "message": "Order ord_01kx16ek2jf4r9da74adf6m4h0 has 0 booking(s) and 1 payment or refund record(s) against it, so it cannot be deleted. Cancel it instead (status CANCELLED).",
     "statusCode": 409,
     "requestId": "1e6b9d3a-5c2f-4a87-b0d4-7f3e1a8c6b52"
   }
   ```

   Cancel it instead, with a reason:

   ```json theme={null}
   // POST /v1/projects/{projectId}/orders/{orderId}/status
   {
     "status": "CANCELLED",
     "cancellationReason": "Checkout abandoned"
   }
   ```

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](https://docs.gomarketbox.com/guides/order-lifecycle-after-checkout.md).

## Reference

### Endpoints used in this guide

| Step | Endpoint | Method | Auth |
| - | - | - | - |
| Onboard | `/v1/projects/{projectId}/clients/me` | `POST` | `x-api-key` + `Bearer` |
| Search | `/v1/projects/{projectId}/availability/suppliers` | `POST` | `x-api-key` |
| Hold, heartbeat | `/v1/projects/{projectId}/holds` | `POST` | `x-api-key` |
| Order | `/v1/projects/{projectId}/orders` | `POST` | `x-api-key` |
| Pay | `/v1/projects/{projectId}/orders/{orderId}/payment-intent` | `POST` | `x-api-key` |
| Poll | `/v1/projects/{projectId}/orders/{orderId}` | `GET` | `x-api-key` |
| Convert | `/v1/projects/{projectId}/holds/{reservationId}/convert` | `POST` | `x-api-key` |
| Confirm | `/v1/projects/{projectId}/bookings/{bookingId}/aggregate` | `GET` | `x-api-key` |
| Abandon | `/v1/projects/{projectId}/holds/{reservationId}/release` | `POST` | `x-api-key` |
| Abandon | `/v1/projects/{projectId}/orders/{orderId}` | `DELETE` | `x-api-key` |
| Abandon | `/v1/projects/{projectId}/orders/{orderId}/status` | `POST` | `x-api-key` |

### Where each failure lands

| Step | Status and `code` | What to do |
| - | - | - |
| Onboard | `401 HTTP_ERROR` | Sign the client in again. |
| Onboard | `403 MEMBERSHIP_INACTIVE` | The client asks the business to invite them again. |
| Hold | `409 SLOT_HELD`, `409 SLOT_BOOKED` | Offer another slot. |
| Hold | `400 VALIDATION_ERROR` | Send every location field the `locationType` needs. See [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md#troubleshooting). |
| Order | `422 OFFERING_NOT_PRICED` | The offering needs a `DEFAULT` price rule. Fix the setup. |
| Order | `422 SERVICE_NOT_SOLD_AS` | The service needs an active `SINGLE_BOOKING` business model. Fix the setup. |
| Order | `422 NOT_SELLABLE` | The service isn't `LIVE`, or the offering isn't `ACTIVE`. Fix the setup. |
| Order | `400 BAD_REQUEST`, `Item … currency … does not match order currency …` | The region resolved a different price. Pass `reservationId`. |
| Pay | `409 CONFLICT` | The business finishes Stripe onboarding. |
| Pay | `400 BAD_REQUEST` | The order isn't `DRAFT` or `PENDING`, or nothing is owed. |
| Pay | `409 PAYMENT_IN_FLIGHT` | A card payment on the order is already moving. Poll the order. |
| Convert | `409 HOLD_EXPIRED` | Hold again, then convert. |
| Convert | `409 SLOT_BOOKED` | Offer a new time; convert a new hold against the same order item. |
| Convert | `409 ORDER_CANCELLED` | Don't retry. |
| Convert | `422 NOT_SELLABLE` | The offering is no longer `ACTIVE`. Set it `ACTIVE`, or refund from the dashboard. |
| Convert | `404 NOT_FOUND`, `Location stz_… not found` | The hold has the wrong `locationType`. See [the travel-zone walkthrough](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md#a-travel-zone-checkout-end-to-end). |
| Any | `409 OCCUPANCY_CONTENTION` | Retry after a short backoff. |
| Abandon | `409 ORDER_NOT_DELETABLE` | Cancel the order with a `cancellationReason` instead. |

See [Errors](https://docs.gomarketbox.com/concepts/errors.md) for the envelope and retry rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.