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.
Anatomy of a client
The client plane returns the client’s profile indata:
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:
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:
The rest of the client plane
Every client-plane route exceptPOST /clients/me needs the person to be
onboarded first. Before that, they have no membership of the project, and
each route returns a 403:
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/mechanges the name or phone. A name can be changed but not cleared.phone: nullclears 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:
quantityRemainingis the live balance. Show this one.quantityReturnedcounts sessions that cancellations gave back, ever. They are already insidequantityRemaining.- Only
PAIDorders count. A package on an unpaid order isn’t listed. - Expired packages and packages with nothing left are left out. Send
includeExpired=trueto keep expired ones.
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 a404 NOT_FOUNDinstead, and a cancelled order is409 ORDER_CANCELLED:
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) andstatus. See Bookings. - Orders are listed newest first, in every status. See Orders.
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/mePATCH /v1/projects/{projectId}/clients/mePOST /v1/projects/{projectId}/clients/me/addressesPATCH /v1/projects/{projectId}/clients/me/addresses/{addressId}DELETE /v1/projects/{projectId}/clients/me/addresses/{addressId}PUT /v1/projects/{projectId}/clients/me/addresses/{addressId}/defaultGET /v1/projects/{projectId}/clients/me/creditsPOST /v1/projects/{projectId}/clients/me/orders/{orderId}/package-bookingsGET /v1/projects/{projectId}/clients/{clientId}/bookingsGET /v1/projects/{projectId}/clients/{clientId}/ordersGET /v1/projects/{projectId}/clients/{clientId}/reviews— see ReviewsGET /v1/projects/{projectId}/clients/{clientId}/review-summary— see Reviews