Skip to main content
A client is the person a service is for. Every order and booking names one by clientId, cli_…. A client belongs to one project. Clients are reached two ways, and the difference matters for security:
  • The client plane, under /clients/me. Your server sends the API key and the signed-in client’s user token. MarketBox works out which client it is from the token. It never takes a client id from the URL.
  • API-key routes, under /clients/{clientId}. Your server sends the API key alone and names the client. They return whatever client you ask for in the project, so your server must check the client is the one signed in.

Which routes need which credentials

Every path is relative to the project: POST /clients/me is POST /v1/projects/{projectId}/clients/me. Send the API key as x-api-key and the user token as Authorization: Bearer <token>. Both come from your server: see The BFF pattern and End-user authentication. No API-key route creates, reads or lists clients. A client is created when a person signs in to your booking flow and you onboard them, or by the business in the MarketBox dashboard. A key-only integration gets a clientId from those places, or from an order or booking that names it.
The API-key routes don’t know who is signed in. A server that takes the clientId from the browser shows one client another client’s bookings, names and addresses. Resolve the clientId from the user token with POST /clients/me, and use that one. See Show booking and order history.

Anatomy of a client

The client plane returns the client’s profile in data:

Onboarding a client

POST /clients/me makes the signed-in person a client of the project. Call it after every sign-in. It’s idempotent: A person who is already a member of the project, such as an admin or a supplier, becomes a client too. Onboarding adds the CLIENT role to their membership and keeps their other roles. The response is the same as for anyone else. There is no GET /clients/me. To read the profile, call POST /clients/me with no body. It writes nothing and returns the profile. The body is optional. Send firstName, lastName and phone to record what your checkout collected:
Each field you send overwrites the stored value, on every path. A blank or null field counts as not sent, so onboarding never clears anything. Without names, a client who signed up with an email and password is recorded under the part of their email before the @. See Onboard the client. An email already linked to another person returns a 409:
A person whose access the business removed is refused before anything is read or written:

The rest of the client plane

Every client-plane route except POST /clients/me needs the person to be onboarded first. Before that, they have no membership of the project, and each route returns a 403:
A member of the project with no client profile, such as a staff member who hasn’t called POST /clients/me, gets 404 NOT_FOUND, No client profile for this project, instead. On PATCH /clients/me the message adds POST /clients/me first. The profile and address routes are covered in full in Manage a client’s account. In short:
  • PATCH /clients/me changes the name or phone. A name can be changed but not cleared. phone: null clears the phone.
  • An address id is derived from the address. Saving the same address twice returns the same id, and an edit can change the id. Re-read ids from each response.
  • The first address a client saves becomes their default. Later ones don’t replace it.
  • The default address decides the region an order is priced in when the order names no place. See Choose the default address.

A client’s package credits

GET /clients/me/credits lists the package sessions the signed-in client can still book. Each entry is one PACKAGE order item the client owns:
  • quantityRemaining is the live balance. Show this one.
  • quantityReturned counts sessions that cancellations gave back, ever. They are already inside quantityRemaining.
  • Only PAID orders count. A package on an unpaid order isn’t listed.
  • Expired packages and packages with nothing left are left out. Send includeExpired=true to keep expired ones.
The client books from a listed credit with POST /clients/me/orders/{orderId}/package-bookings. It takes the same body as POST /orders/{orderId}/package-bookings, plus two refusals of its own:
  • Another client’s order, or one that doesn’t exist, is 404 NOT_FOUND, Order ord_… not found.
  • A credit the credits list wouldn’t show is a 409. That covers an unpaid order and a used-up or expired package. A removed order item is a 404 NOT_FOUND instead, and a cancelled order is 409 ORDER_CANCELLED:
This is where payment is enforced: a client books package sessions only from a PAID order. The API-key route POST /orders/{orderId}/package-bookings doesn’t check payment. See Book a client’s package credit.

A client’s history

GET /clients/{clientId}/bookings and GET /clients/{clientId}/orders take the API key alone. Both are paginated with limit and cursor: see Pagination.
  • Bookings are listed by date. Filter with startDate, endDate (UTC) and status. See Bookings.
  • Orders are listed newest first, in every status. See Orders.
Neither route checks the clientId. A client id that doesn’t exist, or belongs to another project, returns 200 with an empty data. An empty list doesn’t prove the id was right.

Endpoint index

  • POST /v1/projects/{projectId}/clients/me
  • PATCH /v1/projects/{projectId}/clients/me
  • POST /v1/projects/{projectId}/clients/me/addresses
  • PATCH /v1/projects/{projectId}/clients/me/addresses/{addressId}
  • DELETE /v1/projects/{projectId}/clients/me/addresses/{addressId}
  • PUT /v1/projects/{projectId}/clients/me/addresses/{addressId}/default
  • GET /v1/projects/{projectId}/clients/me/credits
  • POST /v1/projects/{projectId}/clients/me/orders/{orderId}/package-bookings
  • GET /v1/projects/{projectId}/clients/{clientId}/bookings
  • GET /v1/projects/{projectId}/clients/{clientId}/orders
  • GET /v1/projects/{projectId}/clients/{clientId}/reviews — see Reviews
  • GET /v1/projects/{projectId}/clients/{clientId}/review-summary — see Reviews