Skip to main content
A client account page in your booking flow does three jobs:
  • shows and edits the client’s name and phone;
  • manages their saved service addresses, and which one is the default;
  • lists their bookings and orders.
The first two run on the client plane: your BFF sends your API key and the signed-in client’s token, and MarketBox works out which client it is from the token. History is different. The routes that list a client’s bookings and orders take a clientId in the path and need only the API key, so your server must make sure the signed-in client only ever sees their own. This guide assumes you have hosted sign-in and the BFF pattern working, and that you already call POST /clients/me after sign-in. See Onboard the client. For the client profile and every client route on one page, see Clients.

The client plane at a glance

Each path above is relative to the project: POST /clients/me is POST /v1/projects/{projectId}/clients/me. Every one takes both credentials: x-api-key from your server, and Authorization: Bearer with the client’s access token. There is no GET /clients/me. Read the profile by calling POST /clients/me again: it’s idempotent, writes nothing when you send no body, and returns 200 with the profile. Every route except POST /clients/me needs the client to be onboarded first. Before that, the person has no membership of the project, and each returns 403:
A 404 NOT_FOUND, No client profile for this project, comes back only for someone who is a member of the project, such as staff, but has no client profile there. Call POST /clients/me for them: it adds the CLIENT role to their membership, keeps their other roles, and creates the profile.

Show the profile

The profile, abridged to the fields an account page uses:
  • email comes from the client’s sign-in. No client-plane route changes it.
  • lastPayment is a display-only snapshot of the card they last paid with. See Show the card a client last paid with.
  • addresses[].source is MANUAL for an address saved through the routes below, and BOOKING for one MarketBox saved from an in-home booking.
  • latitude and longitude may be absent or null. An address typed by hand may never have been geocoded. Treat a missing pair as unknown, not as a location.

Edit the name and phone

PATCH /clients/me changes firstName, lastName or phone. Send only the fields to change:
  • Names are trimmed and must be 1–80 characters. You can change a name but not clear it, so a blank or null name is a 400.
  • phone: null clears the phone. The phone is stored in E.164 form (+14165550199). A North American number may be sent in national form; any other must start with + and the country code.
  • A body with none of firstName, lastName or phone is a 400 VALIDATION_ERROR. Sending the values already stored is a 200 that writes nothing.
The response is the whole profile, as above. The change is also copied to the client’s record in Stripe. If that copy fails, the profile is still updated and you still get 200. Make the change before you create an order, so the order and booking emails carry the new name. Full rules: Change the name or phone later.

Manage saved addresses

Save an address

POST /clients/me/addresses takes one structured address. The fields are the same as a booking’s address: see The address object.
The 201 response carries the whole profile in data, and the address you just saved beside it in address:
country is stored as an ISO 3166-1 alpha-2 code. You can send "CA", "CAN" or "Canada". Anything else is refused:
state is coerced to an ISO 3166-2 code when it can be, and kept as you typed it when it can’t.

An address id is derived from the address

An address id starts with addr_ and is a hash of the structured fields: street number, street name, unit, city, state, country and zip code. It isn’t a random id. Three things follow from that:
  • Saving the same address twice is an upsert. You get the same id back and the client still has one record. addressOneLine isn’t part of the hash, so the same street address formatted differently is still one record.
  • Editing an address can change its id. If a PATCH changes any hashed field, the record moves to a new id and the old id stops existing. If that address was the default, the default moves with it. Edit only addressOneLine and the id stays.
  • An edit can merge two addresses. Edit one address until it matches another saved address, and they become one record.
So re-read every address id from the response after a PATCH. Don’t keep an addressId in your own database across edits. A stale id is a 404:
An edit that changes the address id drops the stored coordinates, because they described the old address. An edit that merges into another saved address keeps that address’s coordinates.

Change or remove an address

PATCH /clients/me/addresses/{addressId} takes any subset of the address fields and merges them over the stored address. It returns the whole profile. DELETE /clients/me/addresses/{addressId} removes it for good: there is no soft delete. Bookings already made at that address keep their own copy, so they’re unaffected. It returns the whole profile too. You can delete the default address. MarketBox then promotes the oldest remaining address to default, or clears defaultAddressId when none is left. Read defaultAddressId off the response rather than assuming which address won.

Choose the default address

PUT /clients/me/addresses/{addressId}/default points defaultAddressId at an address the client has already saved. It takes no body and returns the whole profile. An id that isn’t one of theirs is 404 Address not found. The first address a client saves with POST /clients/me/addresses becomes their default. Later ones don’t replace it, so set the default on purpose when the client picks one.
The default address decides prices. An order that names no reservationId, locationId or address prices against the region of the client’s default address. Without a default, it uses one of their saved addresses, and which one isn’t defined. Without any address, it uses the offering’s DEFAULT price rule and that rule’s currency.An address MarketBox saves from an in-home booking doesn’t become the default. A client whose only addresses came from bookings has no default until you set one.So moving the default from Toronto to Seattle changes what the same client is quoted for the same offering, and in which currency. Orders already placed keep the region they were priced in.An order whose currency doesn’t match what its region resolves to is refused. A checkout that names where the session happens never depends on the default: pass the hold’s reservationId on POST /orders. See Regional pricing.
Use the client’s saved addresses to pre-fill the in-home address step of your checkout. A saved address with latitude and longitude is ready to search with. One without them needs geocoding first, because travel zones match on coordinates, not postal codes.

Show booking and order history

There is no client-plane route for history. Use the API-key routes, with the clientId your server resolved from the client’s token: The two lists are paginated with limit and cursor. See Pagination. The two aggregates return one record.
These routes don’t know who is signed in. They return whatever clientId, bookingId or orderId you ask for in the project. A BFF that takes the clientId from the browser, or that fetches a booking by an id from the URL without checking it, shows one client another client’s bookings, names and addresses.Always resolve the clientId from the token with POST /clients/me. For a single booking or order, compare its clientId with that one, and answer 404 when they differ.
signedInClientId is the helper from Create a single booking. It calls POST /clients/me with the client’s token and returns data.clientId. For the list, put the resolved clientId in the path yourself:
For an “upcoming” tab, ask for SCHEDULED bookings from now on. For a “past” tab, ask for an endDate of now and show every status, including AWAITING_CONFIRMATION: that is a session that has ended and not been settled yet. See The booking lifecycle.
A client can’t cancel or move a booking from the client plane. If your page offers that, your server does it with the API key, after the same ownership check. See Cancel or reschedule a booking. To let the client rate a past booking from this page, use the same ownership check, then post a review. See Collect reviews and show ratings.

Reference

Endpoints used in this guide

Errors and edge cases

See Errors for the envelope.