# MarketBox API > Reference and guides for the MarketBox public API - [MarketBox API](https://docs.gomarketbox.com/index.md): Programmatic access to bookings, orders, suppliers, and service offerings. - [Quickstart](https://docs.gomarketbox.com/quickstart.md): Sign up, create a project, mint an API key, make your first call, and create your first booking. - [Glossary](https://docs.gomarketbox.com/glossary.md): MarketBox's vocabulary, and the words people search for instead. - [Authentication](https://docs.gomarketbox.com/concepts/authentication.md): How API keys, project scope, and tenancy work. - [End-user authentication](https://docs.gomarketbox.com/concepts/end-user-authentication.md): How signed-in clients and suppliers call the API through your backend, and who may call each end-user route. - [Projects and scope](https://docs.gomarketbox.com/concepts/projects-and-scope.md): How the API is organized around projects, and how scope shapes what a key can do. - [The booking engine model](https://docs.gomarketbox.com/concepts/booking-engine-model.md): How orders, bookings, slates, and credits fit together in MarketBox. - [Regional pricing](https://docs.gomarketbox.com/concepts/regional-pricing.md): How MarketBox picks a price rule and currency for an order, and how to tell it where the booking happens. - [Service fees](https://docs.gomarketbox.com/concepts/service-fees.md): How fees configured on a business model become discrete order-level charges, outside subtotal and outside tax. - [Pagination](https://docs.gomarketbox.com/concepts/pagination.md): Cursor-based pagination used on the API's large lists. - [Errors](https://docs.gomarketbox.com/concepts/errors.md): Error envelope, HTTP status codes, and what to do about them. - [Emails](https://docs.gomarketbox.com/concepts/emails.md): What MarketBox sends on your behalf, when, and what you control. - [Versioning](https://docs.gomarketbox.com/concepts/versioning.md): How the API surface evolves without breaking your integration. - [Timezones](https://docs.gomarketbox.com/concepts/timezones.md): How MarketBox represents booking times in UTC and a client-facing local timezone. - [Concurrency and versioning](https://docs.gomarketbox.com/concepts/concurrency.md): Supplier time is exclusive — how MarketBox guards against double-booking, and what to do when you hit a 409. - [Tracking state without webhooks](https://docs.gomarketbox.com/concepts/tracking-state-without-webhooks.md): What changes on its own after you write it — payment, cancellation cascades, hold expiry, the end of a session, disputes — and what to poll for each, and how often. - [What the API doesn't do](https://docs.gomarketbox.com/concepts/what-the-api-doesnt-do.md): The features the public API doesn't have — webhooks, refunds, payouts, invitations, creating Locations and skills, and some supplier-plane and client-plane actions — and what to do instead of each. - [Provision your catalog and suppliers](https://docs.gomarketbox.com/guides/provision-catalog-and-suppliers.md): Create a service, its business models, offerings and packages, publish it, and add the suppliers who deliver it, from your own system with an API key. - [Build a booking flow](https://docs.gomarketbox.com/guides/booking-flow-auth.md): Wire end-user sign-in into a custom booking flow that calls the MarketBox API, using the backend-for-frontend pattern. - [Client checkout, end to end](https://docs.gomarketbox.com/guides/client-checkout-end-to-end.md): 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. - [Create a single booking](https://docs.gomarketbox.com/guides/create-a-single-booking.md): Book one client into one session — create an order, find its order item, then create the booking that draws it down. - [Show a package storefront](https://docs.gomarketbox.com/guides/show-a-package-storefront.md): Render every package of a service as a ready-to-book plan — one call returns each package, its pricing and its slate, with no fan-out. - [Create a package booking with a slate](https://docs.gomarketbox.com/guides/create-a-package-booking.md): Book every session of a package in one call — build a slate for the recurring pattern, create the PACKAGE order item, then book the whole slate by id. - [Book a client's package credit](https://docs.gomarketbox.com/guides/book-a-package-credit.md): Let a signed-in client book the sessions left on a package they already bought — list their credits, plan a slate from one, then book it as the client. - [Availability and slates](https://docs.gomarketbox.com/guides/availability-and-slates.md): A deep dive into the clusters/availability engine — slate anatomy, cadence rules, and the advanced booking paths that sit alongside book-by-slateId. - [Let clients adjust a proposed slate](https://docs.gomarketbox.com/guides/adjust-a-proposed-slate.md): Let a client move one session of a proposed package slate to a time that suits them, re-render from the updated slate, then hold or book it. - [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md): Reserve a supplier's time while a client pays — hold a single session or a whole package slate, then convert the hold into bookings. - [Cancel or reschedule a booking](https://docs.gomarketbox.com/guides/cancel-or-reschedule-a-booking.md): Cancel a booking with or without returning its package session, move it to a new time, cancel a whole order, and know when to delete instead, from your server with an API key. - [Group bookings and check-in](https://docs.gomarketbox.com/guides/group-bookings-and-check-in.md): Create a booking with more than one seat, register clients on it, check them in at the door, and handle the 409 you get at capacity or on a duplicate — and know that registering a participant charges nothing. - [Order lifecycle after checkout](https://docs.gomarketbox.com/guides/order-lifecycle-after-checkout.md): What happens to an order after it's placed — how it moves between statuses, how it settles to PAID, changing its items, cancelling it and its bookings, and when to delete instead. - [Collect reviews and show ratings](https://docs.gomarketbox.com/guides/collect-reviews-and-show-ratings.md): Let clients rate suppliers and suppliers rate clients after a booking, handle the duplicate and cancelled-booking errors, and show a supplier's star rating on a profile page, from your server with an API key. - [Search suppliers by availability](https://docs.gomarketbox.com/guides/search-suppliers-by-availability.md): Render a wall of supplier cards with bookable times. One call returns matching suppliers — each with its full profile and open slots grouped by day — so you never group flat slots or make a follow-up call per supplier. - [Build a supplier profile page](https://docs.gomarketbox.com/guides/build-a-supplier-profile-page.md): Assemble a public supplier profile on your server — name, photo, rating, services and the next opening — from GET /suppliers/{supplierId} and an availability search, without sending the supplier's contact details to the browser. - [Booking addresses](https://docs.gomarketbox.com/guides/booking-addresses.md): When the structured address object is required, its exact shape, and how it threads through slates so book-by-slateId satisfies the rule automatically. - [Manage a client's account](https://docs.gomarketbox.com/guides/manage-a-client-account.md): Let a signed-in client edit their profile and saved addresses, choose the default address that prices their orders, and see their booking and order history. - [Accept payments with Stripe](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md): Charge clients for orders in your booking flow using Stripe, from connecting a business's Stripe account to confirming a card with the Payment Element and finalizing the order. - [Record offline payments](https://docs.gomarketbox.com/guides/record-offline-payments.md): Record cash, bank transfers and comps against an order, retry safely, settle the order to PAID, and reconcile the ledger. - [Build a supplier portal](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md): Let suppliers manage their profile, bookings, hours, travel zones and insights from your own branded portal, through the supplier plane. - [Supplier portal: sign-in and access](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md): What a supplier portal needs before its first call, the two credentials on every supplier-plane request, checking access on sign-in, every refusal and its code, telling a removed supplier from one never invited, and where MarketBox emails send suppliers. - [Supplier portal: profile and photo](https://docs.gomarketbox.com/guides/supplier-portal-profile-and-photo.md): Let a signed-in supplier read and edit their own profile, pick their services and skills, and change their photo, on the supplier plane. - [Supplier portal: bookings](https://docs.gomarketbox.com/guides/supplier-portal-bookings.md): Show a signed-in supplier their bookings, let them file attendance reports and rate the client, and cancel or move a booking when the service allows it. - [Supplier portal: availability](https://docs.gomarketbox.com/guides/supplier-portal-availability.md): Let a signed-in supplier set their working hours, block time off, skip dates with exdates, and choose the travel zones and venues they work in. - [Supplier portal: insights and alerts](https://docs.gomarketbox.com/guides/supplier-portal-insights-and-alerts.md): Show a signed-in supplier their demand and search insights, and build a bell for their new, moved and cancelled bookings from the alerts inbox. - [Supplier day view and attendance reports](https://docs.gomarketbox.com/guides/supplier-day-view-and-reporting.md): Build a supplier's agenda from their bookings, show only the actions the server allows, and file the attendance report that settles each booking. - [Weekly hours, exceptions and seasons](https://docs.gomarketbox.com/guides/weekly-hours-exceptions-and-seasons.md): Model a supplier's real working year on the supplier plane — weekly hours, single days off, blocked time, seasonal schedules and a timezone move — and check the result with an availability search. - [Set up a mobile supplier's service area](https://docs.gomarketbox.com/guides/set-up-a-mobile-supplier-service-area.md): Give a supplier who travels to clients a travel zone and the hours they work in it, check a client's address is covered, and book them there. - [Report site events](https://docs.gomarketbox.com/guides/report-site-events.md): Tell MarketBox which suppliers your site showed, which cards were seen and opened, and which search a booking came from, so suppliers' insights count them. - [Services and offerings](https://docs.gomarketbox.com/resources/services.md): The catalog objects a booking is made from — services, the business models that say how they're sold, and the offerings that carry duration and price. - [Packages](https://docs.gomarketbox.com/resources/packages.md): Prepaid sessions of one offering, sold as one order line and drawn down by later bookings. - [Clients](https://docs.gomarketbox.com/resources/clients.md): The person the service is for — the client profile, the routes a signed-in client calls on their own behalf, and the API-key routes that read a client's history. - [Suppliers](https://docs.gomarketbox.com/resources/suppliers.md): The people or units that fulfill bookings in a project, and the two endpoints that describe them. - [Locations and skills](https://docs.gomarketbox.com/resources/locations.md): Read a project's venues, virtual locations, travel-zone areas and skills with the API key alone. - [Availability](https://docs.gomarketbox.com/resources/availability.md): Find when and where suppliers can fulfill a service — suggested slots, open slots, and recurring patterns. - [Suggestions](https://docs.gomarketbox.com/resources/suggestions.md): The plans the availability engine proposes for a package — suggestion requests, slates and slots, every field they carry, and the route that moves one slot before anything is booked. - [Holds](https://docs.gomarketbox.com/resources/holds.md): Temporarily reserved supplier time — the object a checkout places, extends, converts into bookings or releases. - [Orders](https://docs.gomarketbox.com/resources/orders.md): Build and manage orders — the commerce primitive for tracking what a client owes. - [Transactions](https://docs.gomarketbox.com/resources/transactions.md): The money ledger behind every order — recording cash, external payments and comps, and reading the ledger back for reconciliation. - [Bookings](https://docs.gomarketbox.com/resources/bookings.md): Create, manage, and operate on bookings — the core scheduling primitive. - [Reviews and reports](https://docs.gomarketbox.com/resources/reviews.md): Two-way ratings between clients and suppliers, and per-side attendance reports on a booking. - [API reference](https://docs.gomarketbox.com/api-reference/introduction.md): Every endpoint, schema, and example for the MarketBox public API. - [Report site events straight from the browser (publishable key, no response body)](https://docs.gomarketbox.com/api-reference/events/report-site-events-straight-from-the-browser-publishable-key-no-response-body.md): The browser path for the same events as `POST /events`, for sites without a server of their own and for MarketBox’s own widget. Built for `navigator.sendBeacon` and `fetch(…, { keepalive: true })` on a page that may be closing, so nothing about it needs a header: the credential is the publishable ke… - [Report what your site showed: rendered searches, lists, impressions, clicks, profile views](https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views.md): MarketBox runs the search; your site draws the results. Only your site knows which suppliers it actually put on the page, which cards reached the screen and which ones a client opened, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every… - [Whether the signed-in person may use the supplier plane, and why not](https://docs.gomarketbox.com/api-reference/supplier-plane/whether-the-signed-in-person-may-use-the-supplier-plane-and-why-not.md): Answers 200 for every signed-in person, with `allowed` and a `reasonCode`; it never answers 4xx for a person-level outcome. Call it on sign-in, and use the plane with the returned `supplierId` only when `allowed` is true; otherwise show `message`. `reasonCode` is one of: `SUPPLIER_ACTIVE` (allowed),… - [List the signed-in supplier’s bookings](https://docs.gomarketbox.com/api-reference/supplier-plane/list-the-signed-in-supplier’s-bookings.md): Every booking assigned to the supplier the user token resolves to, in the window — the rows the MarketBox dashboard shows them under My Bookings, built by the same code. Each row carries `viewerActions` (what the supplier may do with it now, by the service’s participant settings and the server’s clo… - [One of the signed-in supplier’s bookings, with services and participants](https://docs.gomarketbox.com/api-reference/supplier-plane/one-of-the-signed-in-supplier’s-bookings-with-services-and-participants.md): The booking as the dashboard’s own-booking detail shows it: the row with the client as the participant settings allow, its service lines, and its participants named as the supplier may see them. No notes (staff-authored) and no other party’s report. A booking that is not the supplier’s is a 404, ind… - [Move one of the signed-in supplier’s bookings to another time](https://docs.gomarketbox.com/api-reference/supplier-plane/move-one-of-the-signed-in-supplier’s-bookings-to-another-time.md): The supplier moves their own booking, exactly as from the MarketBox dashboard: time only, keeping its length, supplier, location and zone. Only a SCHEDULED booking, only when its service lets suppliers reschedule (403 `PARTICIPANT_ACTION_DISABLED`), outside the notice window (409 `NOTICE_WINDOW_PASS… - [The signed-in supplier’s own attendance report on one of their bookings](https://docs.gomarketbox.com/api-reference/supplier-plane/the-signed-in-supplier’s-own-attendance-report-on-one-of-their-bookings.md): Whether a report may be filed now (by the server’s clock), what each answer would do to the booking if filed now, and the supplier’s report if one is on file — the same view the dashboard drawer reads. The client’s report is never returned. Requires the API key and the supplier’s user token. - [File the signed-in supplier’s attendance report on one of their bookings](https://docs.gomarketbox.com/api-reference/supplier-plane/file-the-signed-in-supplier’s-attendance-report-on-one-of-their-bookings.md): A self-report: `attended` says whether the SUPPLIER showed up, and settles the booking exactly as filing from the dashboard does — attended → COMPLETED (or DISPUTED, when the client has reported that they did not attend), did not attend → SUPPLIER_NO_SHOW. 201 when filed, 200 when the identical answ… - [Cancel one of the signed-in supplier’s bookings](https://docs.gomarketbox.com/api-reference/supplier-plane/cancel-one-of-the-signed-in-supplier’s-bookings.md): The supplier cancels their own booking, exactly as from the MarketBox dashboard: only a SCHEDULED booking, only when its service lets suppliers cancel (403 `PARTICIPANT_ACTION_DISABLED`), and only outside the service’s notice window (409 `NOTICE_WINDOW_PASSED`). Recorded as supplier-initiated, by th… - [List the signed-in supplier’s schedules](https://docs.gomarketbox.com/api-reference/supplier-plane/list-the-signed-in-supplier’s-schedules.md): The supplier’s schedules as the dashboard lists them: ACTIVE ones by default, INACTIVE and soft-deleted ones on request. Requires the API key and the supplier’s user token. - [Create a schedule for the signed-in supplier](https://docs.gomarketbox.com/api-reference/supplier-plane/create-a-schedule-for-the-signed-in-supplier.md): A new recurring working pattern for the supplier the user token resolves to, exactly as the dashboard creates one: the offerings must be ACTIVE offerings of the supplier’s services, the locations must exist in the project, and an ACTIVE schedule may not overlap another ACTIVE one (409). Omit `timezo… - [Get one of the signed-in supplier’s schedules](https://docs.gomarketbox.com/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-schedules.md): One schedule by id, if it belongs to the supplier the user token resolves to. Requires the API key and the supplier’s user token. - [Delete one of the signed-in supplier’s schedules](https://docs.gomarketbox.com/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-schedules.md): Soft-deletes the schedule (and its supplier travel zone, if no other schedule of the supplier still uses it), as the dashboard does. Requires the API key and the supplier’s user token. - [Update one of the signed-in supplier’s schedules](https://docs.gomarketbox.com/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-schedules.md): Change any of the schedule’s fields; send the row’s current `version` (optimistic concurrency — a stale one is a 409). Newly added offerings must be ACTIVE; an ACTIVE schedule may not come to overlap another (409). Requires the API key and the supplier’s user token. - [Clone one of the signed-in supplier’s schedules](https://docs.gomarketbox.com/api-reference/supplier-plane/clone-one-of-the-signed-in-supplier’s-schedules.md): A copy of the schedule, created INACTIVE so it can be edited before it offers anything. Requires the API key and the supplier’s user token. - [Move the signed-in supplier’s schedules and blocked times to their profile zone](https://docs.gomarketbox.com/api-reference/supplier-plane/move-the-signed-in-supplier’s-schedules-and-blocked-times-to-their-profile-zone.md): Rewrites every schedule and blocked time of the supplier into the supplier’s profile timezone (the project default when the profile has none), keeping wall clocks; rows already in that zone are untouched. The direction is fixed: the caller never chooses a zone. Requires the API key and the supplier’… - [List the signed-in supplier’s blocked times](https://docs.gomarketbox.com/api-reference/supplier-plane/list-the-signed-in-supplier’s-blocked-times.md): The supplier’s blocked times as the dashboard lists them: ACTIVE ones by default, INACTIVE and soft-deleted ones on request. Requires the API key and the supplier’s user token. - [Create a blocked time for the signed-in supplier](https://docs.gomarketbox.com/api-reference/supplier-plane/create-a-blocked-time-for-the-signed-in-supplier.md): A period the supplier is unavailable — a holiday, a commitment of their own — as the dashboard creates one. Omit `timezone` to use the supplier’s profile zone, then the project default. Requires the API key and the supplier’s user token. - [Get one of the signed-in supplier’s blocked times](https://docs.gomarketbox.com/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-blocked-times.md): One blocked time by id, if it belongs to the supplier the user token resolves to. Requires the API key and the supplier’s user token. - [Delete one of the signed-in supplier’s blocked times](https://docs.gomarketbox.com/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-blocked-times.md): Soft-deletes the blocked time, as the dashboard does. Requires the API key and the supplier’s user token. - [Update one of the signed-in supplier’s blocked times](https://docs.gomarketbox.com/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-blocked-times.md): Change any of the blocked time’s fields; send the row’s current `version` (optimistic concurrency — a stale one is a 409). Requires the API key and the supplier’s user token. - [The signed-in supplier’s Week & demand view](https://docs.gomarketbox.com/api-reference/supplier-plane/the-signed-in-supplier’s-week-&-demand-view.md): Booked, searched and unfilled demand by hour of week over the supplier’s area, with their bookable hours, a glance and suggestions — the same view the MarketBox dashboard shows them. Hours are the supplier’s home zone, derived per instant from the rollup’s UTC buckets. Counts of 1–2 read "few"; fewe… - [Dismiss one of the signed-in supplier’s demand suggestions for 90 days](https://docs.gomarketbox.com/api-reference/supplier-plane/dismiss-one-of-the-signed-in-supplier’s-demand-suggestions-for-90-days.md): "Keep these hours": hides the suggestion with this key from the demand view (and from Search insights) for 90 days. Idempotent; the dashboard shows the same dismissal. Requires the API key and the supplier’s user token. - [Undo a dismissal: the suggestion shows again when the data still supports it](https://docs.gomarketbox.com/api-reference/supplier-plane/undo-a-dismissal:-the-suggestion-shows-again-when-the-data-still-supports-it.md): Removes the 90-day dismissal of this key. Idempotent: 200 with `dismissed: false` whether or not one was on file. Requires the API key and the supplier’s user token. - [The signed-in supplier’s Search insights](https://docs.gomarketbox.com/api-reference/supplier-plane/the-signed-in-supplier’s-search-insights.md): Shown, Seen, profile opens, open rate, bookings from search, average position, missed searches by reason and the channel / service / area / time-asked breakdowns, each with the previous equal-length period and a daily series — the dashboard’s Search insights tab. `?days=7|28|90` (default 28) or `?fr… - [The signed-in supplier’s own profile](https://docs.gomarketbox.com/api-reference/supplier-plane/the-signed-in-supplier’s-own-profile.md): The supplier record the user token resolves to in this project, as the MarketBox dashboard shows it under My Profile, built by the same code. It is the supplier’s own record, resolved from the user token: phone, email, address, `active`, time zone, service and skill ids, languages and locales. `GET… - [Update the signed-in supplier’s own profile](https://docs.gomarketbox.com/api-reference/supplier-plane/update-the-signed-in-supplier’s-own-profile.md): Changes the supplier record the user token resolves to, as the MarketBox dashboard does when a supplier edits My Profile, built by the same code. Only the fields in the body schema can be changed; any field left out is unchanged. `serviceIds` and `skillIds` replace the whole set when sent. A body na… - [Get a presigned URL to upload the signed-in supplier’s photo](https://docs.gomarketbox.com/api-reference/supplier-plane/get-a-presigned-url-to-upload-the-signed-in-supplier’s-photo.md): Step 1 of 2 of changing the photo of the supplier the user token resolves to. The image never passes through this API: you get back a short-lived URL and PUT the bytes straight to storage, then call PUT /suppliers/me/avatar with the `variantId` returned here. - [Attach the uploaded photo to the signed-in supplier](https://docs.gomarketbox.com/api-reference/supplier-plane/attach-the-uploaded-photo-to-the-signed-in-supplier.md): Step 2 of 2: attaches the uploaded image to the supplier the user token resolves to and returns their profile, in the shape `GET /suppliers/me` answers, with the new `avatarUrl`. Pass the `variantId` from the upload-url call. - [Remove the signed-in supplier’s photo](https://docs.gomarketbox.com/api-reference/supplier-plane/remove-the-signed-in-supplier’s-photo.md): Clears the photo of the supplier the user token resolves to and deletes the stored images for good. Returns 204 whether or not they had one. To swap a photo, confirm the new one instead: that replaces the old image in one step. Requires the API key and the supplier’s user token. - [List the signed-in supplier’s travel zones](https://docs.gomarketbox.com/api-reference/supplier-plane/list-the-signed-in-supplier’s-travel-zones.md): The supplier’s travel zones as the dashboard lists them: active ones by default, inactive and soft-deleted ones on request, optionally by name prefix. Requires the API key and the supplier’s user token. - [Create a travel zone for the signed-in supplier](https://docs.gomarketbox.com/api-reference/supplier-plane/create-a-travel-zone-for-the-signed-in-supplier.md): An area the supplier travels to, as the dashboard creates one: a CIRCULAR zone (a radius around a centre) or a DRAWN one (GeoJSON polygons). The zone is always the signed-in supplier’s. Requires the API key and the supplier’s user token. - [Get one of the signed-in supplier’s travel zones](https://docs.gomarketbox.com/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-travel-zones.md): One travel zone by id, if it belongs to the supplier the user token resolves to; another supplier’s zone is a 404 like a missing one. Requires the API key and the supplier’s user token. - [Delete one of the signed-in supplier’s travel zones](https://docs.gomarketbox.com/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-travel-zones.md): Soft-deletes the travel zone, as the dashboard does. Requires the API key and the supplier’s user token. - [Update one of the signed-in supplier’s travel zones](https://docs.gomarketbox.com/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-travel-zones.md): Change any of the zone’s fields; send the row’s current `version` (optimistic concurrency — a stale one is a 409). A geometry change re-computes the coverage of every schedule that uses the zone; `coverageRecompute` reports how many and how many failed. A rename or other non-geometry edit leaves the… - [List the venues the signed-in supplier may be scheduled at](https://docs.gomarketbox.com/api-reference/supplier-plane/list-the-venues-the-signed-in-supplier-may-be-scheduled-at.md): The project's active PHYSICAL and VIRTUAL locations (deleted ones never appear), sorted by name: the venues a supplier can name in a schedule, as the MarketBox dashboard lists them, built by the same code. Each is the supplier view of a location, with no travel settings and no status or audit fields… - [List the signed-in supplier’s alerts](https://docs.gomarketbox.com/api-reference/supplier-plane/list-the-signed-in-supplier’s-alerts.md): The supplier’s alerts — new, moved and cancelled bookings — newest first, as the bell in the MarketBox dashboard lists them, read by the same code from the same inbox. Each row carries a `target` naming what it is about (`{ kind: "booking", bookingId }`); map it to your own page, since alerts hold n… - [The signed-in supplier’s unread count and open conditions](https://docs.gomarketbox.com/api-reference/supplier-plane/the-signed-in-supplier’s-unread-count-and-open-conditions.md): What a bell badge needs, in one cheap call: the unread alert count (capped at 100, `unreadCapped` when there may be more) and the open conditions — states computed on every read, such as `MY_REPORTS_OVERDUE` ("N bookings need your report"). Conditions have no read state and leave when resolved; thei… - [Mark all of the signed-in supplier’s alerts read](https://docs.gomarketbox.com/api-reference/supplier-plane/mark-all-of-the-signed-in-supplier’s-alerts-read.md): Marks up to 1,000 unread alerts read in one call and reports how many (`updated`). When `more` is true, unread alerts remain past the cap: call again until it is false. Conditions are not alerts and are not cleared. Requires the API key and the supplier’s user token. - [Mark one of the signed-in supplier’s alerts read](https://docs.gomarketbox.com/api-reference/supplier-plane/mark-one-of-the-signed-in-supplier’s-alerts-read.md): Marks the alert read, typically when the supplier opens it. Answers 204 whether or not it was already read. An id that is not in this supplier’s inbox — missing, another user’s, or in another inbox of theirs — is the same 404. Requires the API key and the supplier’s user token. - [List bookings for a project](https://docs.gomarketbox.com/api-reference/bookings/list-bookings-for-a-project.md): Bookings across the whole project, filtered by the supported query fields and paginated with `limit`/`cursor` (`nextCursor: null` is the last page). For one supplier's diary or one client's history, prefer the dedicated `/suppliers/{supplierId}/bookings` and `/clients/{clientId}/bookings` lists — th… - [Create a new booking](https://docs.gomarketbox.com/api-reference/bookings/create-a-new-booking.md): Creates a single booking. Each service line must reference an existing order + order item (orderId + orderItemId) to draw down — create and pay for an order first. Location fields depend on locationType: TRAVEL_ZONE requires locationId, latitude, longitude, and a structured address; PHYSICAL require… - [Get a booking by ID](https://docs.gomarketbox.com/api-reference/bookings/get-a-booking-by-id.md): The booking record on its own — times, supplier, client, location and status. Local-time fields (`bookingLocalDate`, `bookingLocalStartTime`, …) are derived server-side from the UTC times and the booking timezone, so render those rather than converting the UTC values yourself. Use the `/aggregate` v… - [Soft-delete a booking](https://docs.gomarketbox.com/api-reference/bookings/soft-delete-a-booking.md): Marks the booking deleted and hides it from lists, retaining the record so history stays auditable. This is not how you cancel: use `POST /status` with `CANCELLED` for a booking that genuinely was called off — it keeps the booking visible, records a reason and lets you choose the credit treatment. R… - [Reschedule or update a booking](https://docs.gomarketbox.com/api-reference/bookings/reschedule-or-update-a-booking.md): Moves a booking in time, or edits its details. Send UTC times (`bookingStartUtc`, `bookingEndUtc`) with `bookingTz`; the four local-time fields are computed from those and are deliberately NOT accepted here — passing local times directly is how a booking ends up disagreeing with itself across timezo… - [Get a booking with its services, participants, notes, reports and party names](https://docs.gomarketbox.com/api-reference/bookings/get-a-booking-with-its-services-participants-notes-reports-and-party-names.md): The booking plus everything hanging off it — service lines, participants, notes and attendance reports — in one call. This is the shape for a booking detail screen; assembling it from five separate endpoints is slower and can tear if something changes mid-sequence. `reports` holds at most two rows,… - [Change a booking status](https://docs.gomarketbox.com/api-reference/bookings/change-a-booking-status.md): Moves the booking through its lifecycle. The `status` enum on the request body is the authoritative list of what a caller may ASK for — it is narrower than the `status` on the response, because `SCHEDULED` and `DISPUTED` are states a booking is put into by the platform and can only be observed, neve… - [List bookings for a supplier](https://docs.gomarketbox.com/api-reference/bookings/list-bookings-for-a-supplier.md): One supplier's diary, ordered by date and paginated. This is the indexed path for a supplier-facing schedule — use it rather than listing the project and filtering client-side. - [List bookings for a client](https://docs.gomarketbox.com/api-reference/bookings/list-bookings-for-a-client.md): One client's bookings, past and upcoming, ordered by date and paginated. This is the call behind a client-facing "my bookings" view. - [List participants on a booking](https://docs.gomarketbox.com/api-reference/bookings/list-participants-on-a-booking.md): Everyone registered on the booking, with their check-in state. This is the roster a supplier works from at the door. - [Register a participant on a booking](https://docs.gomarketbox.com/api-reference/bookings/register-a-participant-on-a-booking.md): Adds a client to a booking that seats more than one person, such as a class or a group session. Capacity is enforced, so registering past the capacity set on the booking is rejected rather than silently overbooking. Registering the same client twice is a conflict, not a duplicate row; a participant… - [Get a single booking participant](https://docs.gomarketbox.com/api-reference/bookings/get-a-single-booking-participant.md): One participant's registration on this booking, including whether they have checked in. Returns 404 when the client is not registered on it. - [Cancel a booking participant](https://docs.gomarketbox.com/api-reference/bookings/cancel-a-booking-participant.md): Removes one participant from the booking, freeing their seat for someone else. The booking itself stays scheduled for everyone else — to call off the whole booking, change its status to CANCELLED instead. Returns 204 with no body. - [Check in a participant](https://docs.gomarketbox.com/api-reference/bookings/check-in-a-participant.md): Records that the participant physically arrived. Idempotent in effect — checking in someone already checked in leaves them checked in — so it is safe to retry from a door-scanning client with unreliable connectivity, and a retry keeps the first `checkInAt`. This tracks attendance only; it does not c… - [List booking notes](https://docs.gomarketbox.com/api-reference/bookings/list-booking-notes.md): Every note on the booking, newest first. Also available inside GET /bookings/{bookingId}/aggregate, so prefer that when you need the booking and its notes together. - [Create a booking note](https://docs.gomarketbox.com/api-reference/bookings/create-a-booking-note.md): Attaches a free-text note to the booking — preparation details, access instructions, what happened on the day. Notes are operational context for staff, not a channel to the client, and nothing here is shown to the client automatically. - [Delete a booking note](https://docs.gomarketbox.com/api-reference/bookings/delete-a-booking-note.md): Permanently removes the note. Unlike bookings and orders, notes are not soft-deleted — there is no audit reason to retain one, and nothing else references it. Returns 204 with no body. - [Update a booking note](https://docs.gomarketbox.com/api-reference/bookings/update-a-booking-note.md): Edits the body of an existing note in place. The note keeps its id and position in the list, so an edit does not resurface it as new. - [List the reports filed on a booking](https://docs.gomarketbox.com/api-reference/bookings/list-the-reports-filed-on-a-booking.md): Both sides' reports on this booking — at most two, one per `reporterRole`, unpaginated. A side that has not filed is simply absent, which is not the same as a filed report saying `attended: false`; only an explicit row means "I did not attend". Also included in `GET /bookings/{bookingId}/aggregate`,… - [File one side's report on a booking](https://docs.gomarketbox.com/api-reference/bookings/file-one-sides-report-on-a-booking.md): Records one side of a booking reporting on it — today, whether they showed up. A booking carries at most two reports, one per side, identified by `(bookingId, reporterRole)`; there is no report id. - [List every review linked to a booking](https://docs.gomarketbox.com/api-reference/reviews/list-every-review-linked-to-a-booking.md): Every review linked to this booking, newest first, in both directions and unpaginated. - [Review a booking, in either direction](https://docs.gomarketbox.com/api-reference/reviews/review-a-booking-in-either-direction.md): Records one side of a booking rating the other, and folds the rating into the rated party's running average in the same atomic write. Both parties are read off the booking in the URL — the body carries **no ids at all**, so a review can only ever be attributed to the supplier and client who were act… - [List reviews for a project (newest first); filter by supplier](https://docs.gomarketbox.com/api-reference/reviews/list-reviews-for-a-project-newest-first;-filter-by-supplier.md): Reviews newest-first, either across the project or for one supplier via `supplierId`. This returns individual reviews only. The running average maintained when a review is created is not exposed by this API, and no supplier field carries it, so a star rating has to be computed here — which means wal… - [Create a supplier review (1–5 star rating with optional comment)](https://docs.gomarketbox.com/api-reference/reviews/create-a-supplier-review-1–5-star-rating-with-optional-comment.md): Records a rating against a supplier and folds it into that supplier's running average in the same atomic write, so the aggregate never disagrees with the rows behind it. - [List the reviews written about a client](https://docs.gomarketbox.com/api-reference/reviews/list-the-reviews-written-about-a-client.md): Reviews **of** this client — the ones suppliers wrote about them — newest first. It is not the reviews this client wrote; those are reviews of a supplier and are read through `GET /reviews?supplierId=…`. Only `SUPPLIER_TO_CLIENT` reviews appear here, so every row has this client as its `subjectId`. - [Get a client's average rating and review count](https://docs.gomarketbox.com/api-reference/reviews/get-a-clients-average-rating-and-review-count.md): The running average of the reviews suppliers have written about this client, maintained at write time rather than computed on read — so it never disagrees with the rows behind it and does not require walking `GET /clients/{clientId}/reviews`. - [Get a supplier's average rating and review count](https://docs.gomarketbox.com/api-reference/reviews/get-a-suppliers-average-rating-and-review-count.md): This supplier's star rating and how many reviews it is based on, read from the aggregate maintained in the same atomic write that records each review. - [List orders by status, by payment method, or every order in a date range](https://docs.gomarketbox.com/api-reference/orders/list-orders-by-status-by-payment-method-or-every-order-in-a-date-range.md): Exactly one listing mode per request, chosen by which filter you send: - [Create a new order](https://docs.gomarketbox.com/api-reference/orders/create-a-new-order.md): Creates an order (a cart/purchase record). For a package, add an item with { skuType: "PACKAGE", packageId } — the server derives service, offering, session count (creditCount), price and expiry from the package. For a single session use { skuType: "SINGLE_SESSION", serviceId, offeringId, quantity }… - [Get an order by ID](https://docs.gomarketbox.com/api-reference/orders/get-an-order-by-id.md): Returns the order header only — totals, currency, status and the `pricingRegion` it resolved at create time. It does NOT include line items; use the `/aggregate` variant when you need the items too, rather than calling this and then listing items separately. - [Soft-delete an order](https://docs.gomarketbox.com/api-reference/orders/soft-delete-an-order.md): Marks the order deleted and hides it from list endpoints. The record is retained rather than destroyed, so financial history stays auditable. This is not the same as cancelling: use `POST /status` with `CANCELLED` to record that a real order was called off, and reserve delete for orders raised in er… - [Update an order](https://docs.gomarketbox.com/api-reference/orders/update-an-order.md): Deliberately narrow, and tax is not editable: the platform computes it — line tax plus tax on taxable service fees — when the order is created and whenever its lines change. `tax` is still accepted for compatibility, but only when it equals both the computed and the stored figure, i.e. when it chang… - [Get an order with its items](https://docs.gomarketbox.com/api-reference/orders/get-an-order-with-its-items.md): The order header plus every line item in one call — the shape to use when rendering a receipt or reconciling what was charged. Each item carries `priceRuleId` and `priceScope`, so you can prove which regional price rule produced its amount: `priceScope: "DEFAULT"` where you expected a regional price… - [List orders for a client](https://docs.gomarketbox.com/api-reference/orders/list-orders-for-a-client.md): Every order belonging to one client, newest first, across all statuses — unlike the project-level list, no `status` is required. This is the call behind a client's order history. - [Change order status](https://docs.gomarketbox.com/api-reference/orders/change-order-status.md): Moves the order through its lifecycle. Only these transitions are allowed, and anything else is a 400: - [Add an item to an order](https://docs.gomarketbox.com/api-reference/orders/add-an-item-to-an-order.md): Adds a line and returns the whole order with its items, so you never need a follow-up read to get the new total. You do not send a price: the server resolves it from the offering against the order's `pricingRegion`, which is what keeps the charge honest. A line whose resolved currency differs from t… - [Remove an order item](https://docs.gomarketbox.com/api-reference/orders/remove-an-order-item.md): Drops the line and returns the order with its recalculated totals. Removing a PACKAGE line does not retract bookings already drawn from it, so check `GET /orders/{orderId}/package-bookings?orderItemId=` before removing one that has been booked against. - [Update an order item quantity](https://docs.gomarketbox.com/api-reference/orders/update-an-order-item-quantity.md): Changes quantity only — the unit price stays as resolved when the line was added, so re-pricing an existing line is not possible through this endpoint. Remove the line and add it again if the price must change. Returns the whole order with its recalculated totals. - [List the bookings created for a PACKAGE order item](https://docs.gomarketbox.com/api-reference/orders/list-the-bookings-created-for-a-package-order-item.md): Every session already booked against this order — the other half of the package ledger. Compare the count against the item's credit count to see how many sessions remain unbooked, and call this before removing or refunding a PACKAGE line so you know what has already been consumed. Optional `startDat… - [Create N package sessions atomically (or best-effort) from one PACKAGE order item](https://docs.gomarketbox.com/api-reference/orders/create-n-package-sessions-atomically-or-best-effort-from-one-package-order-item.md): Books all sessions of a package against one PACKAGE order item. Provide exactly one source: slateId (book a whole slate — recommended; the server resolves times/supplier/location and fills the travel-zone location itself), slotIds (cherry-pick), or sessions (explicit). Booking does NOT require the o… - [List suppliers for a project, enriched with services and skills; filter by service/skill/region/point](https://docs.gomarketbox.com/api-reference/suppliers/list-suppliers-for-a-project-enriched-with-services-and-skills;-filter-by-serviceskillregionpoint.md): The supplier directory, each row already carrying its resolved `services` and `skills`, so a "who can do X, near Y" page needs one call. Every filter is AND, both within a parameter and across parameters: `services=a,b` means a supplier offering BOTH, never either. The location filter is hierarchica… - [Create a supplier](https://docs.gomarketbox.com/api-reference/suppliers/create-a-supplier.md): Location fields are canonicalised to ISO codes: `country` is an ISO 3166-1 alpha-2 code (e.g. "CA"), `state` an ISO 3166-2 subdivision of that country ("CA-ON" or "ON"). Invalid codes return 400. `city` is free text. - [One supplier in full: profile, services, skills, locations, rating and working hours](https://docs.gomarketbox.com/api-reference/suppliers/one-supplier-in-full:-profile-services-skills-locations-rating-and-working-hours.md): Everything about one supplier in a single call — the same shape `GET /suppliers` returns for a row, plus two blocks the list deliberately omits because they cost a read each: `rating` and `availability`. Use it for a supplier profile page; use the list for a directory. - [Update a supplier; sync its service/skill mappings when arrays are supplied](https://docs.gomarketbox.com/api-reference/suppliers/update-a-supplier;-sync-its-serviceskill-mappings-when-arrays-are-supplied.md): Same ISO location contract as create: `country` is ISO 3166-1 alpha-2, `state` an ISO 3166-2 subdivision ("CA-ON" or "ON"). Invalid codes return 400. - [Soft-delete a supplier (cascade-removes its mappings and avatar)](https://docs.gomarketbox.com/api-reference/suppliers/soft-delete-a-supplier-cascade-removes-its-mappings-and-avatar.md): Retires a supplier. The profile is soft-deleted and stays readable to bookings that reference it, but the cascade around it is permanent: every service and skill mapping is hard-deleted and the avatar images are removed from storage. There is no undelete — recreating the supplier means re-adding all… - [Add a service to a supplier](https://docs.gomarketbox.com/api-reference/suppliers/add-a-service-to-a-supplier.md): Declares that this supplier performs this service, which is what makes them appear in availability searches and in `?services=` filters for it. Idempotent: re-adding an existing mapping succeeds and changes nothing, so you can call it without checking first. The service must already exist in the pro… - [Remove a service from a supplier](https://docs.gomarketbox.com/api-reference/suppliers/remove-a-service-from-a-supplier.md): Stops this supplier being offered for this service in availability searches. The mapping is hard-deleted, not soft-deleted, so re-adding it later creates a fresh mapping with no memory of the old one. Idempotent and forgiving: removing a mapping that was never there still returns 204, so a 204 is no… - [Add a skill to a supplier](https://docs.gomarketbox.com/api-reference/suppliers/add-a-skill-to-a-supplier.md): Grants the supplier a skill. Skills gate offerings rather than services: an offering that lists `skillIds` can only be performed by suppliers holding all of them, so a supplier mapped to the right service can still be invisible in availability if a skill is missing — check here first when a supplier… - [Remove a skill from a supplier](https://docs.gomarketbox.com/api-reference/suppliers/remove-a-skill-from-a-supplier.md): Revokes a skill, narrowing which offerings this supplier can be matched to. Expect the supplier to drop out of availability for every offering that required it, which is often more than the one you had in mind — list the supplier first if you want to see what they currently hold. The mapping is hard… - [Get a presigned URL to upload a supplier avatar](https://docs.gomarketbox.com/api-reference/suppliers/get-a-presigned-url-to-upload-a-supplier-avatar.md): Step 1 of 2. The image never passes through this API: you get back a short-lived URL and PUT the bytes straight to storage, then call PUT /suppliers/{supplierId}/avatar with the `variantId` returned here to attach the result. - [Confirm an uploaded avatar and attach it to the supplier](https://docs.gomarketbox.com/api-reference/suppliers/confirm-an-uploaded-avatar-and-attach-it-to-the-supplier.md): Step 2 of 2: attaches the uploaded image to the supplier and returns the enriched supplier with its new avatar. Pass the `variantId` from the presign response, not the `uploadId`. - [Remove a supplier's avatar](https://docs.gomarketbox.com/api-reference/suppliers/remove-a-suppliers-avatar.md): Clears the avatar reference and deletes the stored image variants. Both the reference and the images are gone for good, so restoring the same picture means uploading it again through the presign flow. Returns 204 whether or not the supplier had an avatar, so use it freely without a prior read — but… - [Find suppliers + suggested/open slots for a service, location and window](https://docs.gomarketbox.com/api-reference/availability/find-suppliers-+-suggestedopen-slots-for-a-service-location-and-window.md): The main "when can this be booked" call. Returns two parallel, slot-centric arrays: `timeSlots`, the engine's ranked suggestions with travel between jobs taken into account, and `openSlots`, every free interval at `interval` granularity with no ranking. Show `timeSlots` to clients and keep `openSlot… - [Generate clustered time slots from suppliers + engine config](https://docs.gomarketbox.com/api-reference/availability/generate-clustered-time-slots-from-suppliers-+-engine-config.md): Runs the clustering engine directly on suppliers and a config YOU supply. Nothing is read from the project — not the catalogue, not the supplier roster, not existing bookings — so this answers "what would the engine do with these inputs", not "when is this bookable". The supplier availability you pa… - [Supplier-centric availability: paginated suppliers, each with open slots grouped by day](https://docs.gomarketbox.com/api-reference/availability/supplier-centric-availability:-paginated-suppliers-each-with-open-slots-grouped-by-day.md): Returns availability grouped by supplier — a paginated list of suppliers, each with its full profile (same shape as GET /suppliers) and its open slots bucketed by local day. Use this to render a wall of supplier cards with bookable times, instead of the flat, slot-centric arrays /availability/search… - [Build a single-supplier N-session package slate (policy-driven), persisting suggestions](https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions.md): Builds one or more "slates" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A cr… - [List a service's packages, each with a ready-to-book slate](https://docs.gomarketbox.com/api-reference/availability/list-a-services-packages-each-with-a-ready-to-book-slate.md): Returns every ACTIVE package of a service, each with a complete N-session plan built from a supplier's real availability. The response entry carries a slateId that can be booked directly via POST /orders/{orderId}/package-bookings. Cadence defaults to FREQ=WEEKLY;COUNT={creditCount}, derived per pac… - [Reschedule a suggested slot to a new time (server-validated), refreshing its slate](https://docs.gomarketbox.com/api-reference/suggestions/reschedule-a-suggested-slot-to-a-new-time-server-validated-refreshing-its-slate.md): Moves ONE slot of a proposed slate to a time the client picked, before anything is booked. This is the "actually, can we do Thursday instead" step of a multi-session proposal — it does not touch bookings, which have their own reschedule route. The new time is validated against the supplier's real av… - [Hold supplier time during checkout — a single session, or a whole package slate](https://docs.gomarketbox.com/api-reference/holds/hold-supplier-time-during-checkout-—-a-single-session-or-a-whole-package-slate.md): Claims supplier time so nobody else can book it while your client pays. Provide exactly one of: intervals (explicit supplier time — this is the form that works for a SINGLE session, with no package and no slate), slateId (hold every slot of a persisted package slate), or slotIds (cherry-pick slots o… - [Read a hold — its status, its heldUntil, and the supplier time it claims](https://docs.gomarketbox.com/api-reference/holds/read-a-hold-—-its-status-its-helduntil-and-the-supplier-time-it-claims.md): Returns the reservation as it stands. status is HELD (live), CONVERTED (already booked — a repeated convert replays the same bookings), or RELEASED. A hold past its heldUntil may still read as HELD: expiry is lazy, so compare heldUntil against now rather than trusting status alone. - [Release a hold (HELD → RELEASED) — idempotent](https://docs.gomarketbox.com/api-reference/holds/release-a-hold-held-→-released-—-idempotent.md): Frees the supplier time immediately: call this when the client abandons checkout instead of waiting for lazy expiry. Idempotent — an already-released hold returns RELEASED, an already-converted hold returns CONVERTED (it is booked and cannot be released), and an unknown reservationId returns NOT_FOU… - [Convert a hold into confirmed bookings (the idempotent purchase hook)](https://docs.gomarketbox.com/api-reference/holds/convert-a-hold-into-confirmed-bookings-the-idempotent-purchase-hook.md): Turns the held supplier time into real bookings, drawing credits from the given order item. The order item's skuType decides what is booked: a PACKAGE item books every held interval as package sessions; a SINGLE_SESSION item books the ONE held interval as an ordinary single booking — no package, and… - [Onboard the authenticated client to a project](https://docs.gomarketbox.com/api-reference/clients/onboard-the-authenticated-client-to-a-project.md): Idempotently registers the signed-in end user as a CLIENT of the project: ensures a ProjectUsers membership, creates Stripe's own Customer object on the project's connected account (when Stripe is configured, stored as stripeCustomerId), and writes the ClientProfile. Requires both an API key (`x-api… - [Update the authenticated client's contact details](https://docs.gomarketbox.com/api-reference/clients/update-the-authenticated-clients-contact-details.md): Changes the signed-in client's first name, last name and/or phone number in this project. The profile is resolved from the client user JWT, never from the URL, and requires both the API key (`x-api-key`) and the JWT (`Authorization: Bearer`). The caller must already be onboarded: POST /clients/me fi… - [Get the authenticated client's package credits](https://docs.gomarketbox.com/api-reference/clients/get-the-authenticated-clients-package-credits.md): Returns the signed-in client's remaining package credits on the project. Each entry is a PACKAGE order item the client owns; `quantityRemaining` is the live, authoritative balance. Only PAID orders count, and expired or fully-drawn-down packages are omitted (pass `includeExpired=true` to keep expire… - [Book sessions from the authenticated client's own package credit](https://docs.gomarketbox.com/api-reference/clients/book-sessions-from-the-authenticated-clients-own-package-credit.md): The signed-in client books their own credit. Only credits `GET /clients/me/credits` returns can be booked. Same body, response and refusals as `POST /orders/{orderId}/package-bookings` (a cancelled order is 409 `ORDER_CANCELLED` there and here), plus 404 for another client's order and 409 `CREDIT_NO… - [Add a service address to the caller's client profile](https://docs.gomarketbox.com/api-reference/clients/add-a-service-address-to-the-callers-client-profile.md): Saves a service address for the signed-in client. Requires both the API key and the client user JWT, and the caller must already be onboarded — POST /clients/me first, or this is a 404. - [Remove one of the caller's addresses](https://docs.gomarketbox.com/api-reference/clients/remove-one-of-the-callers-addresses.md): Deletes one saved address and returns the client profile as it now stands. The removal is permanent — there is no soft delete — but bookings already placed against that address are unaffected, since they captured it at the time. - [Update one of the caller's addresses](https://docs.gomarketbox.com/api-reference/clients/update-one-of-the-callers-addresses.md): Address ids are derived from the address content, so a successful update MAY change the id — always re-read ids from the returned profile. - [Set the caller's default address](https://docs.gomarketbox.com/api-reference/clients/set-the-callers-default-address.md): Points the client's `defaultAddressId` at an address they have already saved; it does not create one, so add the address first or this is a 404. Returns the whole updated profile. - [List services for a project](https://docs.gomarketbox.com/api-reference/services/list-services-for-a-project.md): The project catalogue, sorted by name within each status. Unlike most list endpoints this one is not paginated: a project holds few enough services to return in one response, so `nextCursor` is always null and there is no `limit`. All three statuses are included unless you filter — pass `status=LIVE… - [Create a new service](https://docs.gomarketbox.com/api-reference/services/create-a-new-service.md): A service is the umbrella record; the sellable variants hang off it as offerings, and only an offering carries price and duration. So a service on its own sells nothing — create at least one offering before publishing. The new service is always DRAFT regardless of what you send; publish it with POST… - [Get a service by ID](https://docs.gomarketbox.com/api-reference/services/get-a-service-by-id.md): The service header on its own — its offerings, business models and attributes are separate resources and are not embedded here, so pricing and duration require a second call to the offerings endpoint. `counts.offerings` tells you whether that call is worth making. A soft-deleted service is a 404, no… - [Update a service](https://docs.gomarketbox.com/api-reference/services/update-a-service.md): Edits the descriptive fields only. `name` and `description` are whole-map replacements, not merges: send every language you want to keep or the ones you omit are dropped. Renaming re-runs the uniqueness check and returns 409 if the new name is taken, so read the error before retrying — the rest of t… - [Soft delete a service](https://docs.gomarketbox.com/api-reference/services/soft-delete-a-service.md): Marks the service deleted and flips it to INACTIVE. It disappears from lists and GETs while the record is retained, so bookings and orders already placed against it still resolve. The name reservation is released in the same write, meaning the name is immediately reusable by a new service — deleting… - [Change service status](https://docs.gomarketbox.com/api-reference/services/change-service-status.md): The publish switch: only LIVE services are bookable. Allowed transitions are DRAFT to LIVE, DRAFT to INACTIVE, LIVE to INACTIVE and INACTIVE to LIVE; anything else is a 400. Note there is no route back to DRAFT once published, so a service you want to keep working on privately should go to INACTIVE,… - [List business models for a service](https://docs.gomarketbox.com/api-reference/servicebusinessmodels/list-business-models-for-a-service.md): How this service may be sold, and on what payment terms. Check here first when a package create returns 400: creating packages requires an entry with `type: "PACKAGE"` and `active: true`, and this is the only way to see whether the service has one. Inactive models are returned too — read `active`, d… - [Add a business model to a service](https://docs.gomarketbox.com/api-reference/servicebusinessmodels/add-a-business-model-to-a-service.md): Declares a way the service can be sold, and gates what you can build on it — a service cannot have packages created against it until it carries an active PACKAGE model, so this call usually comes before the first package. The model is created active. Nothing here is deduplicated: posting the same `t… - [Update a business model](https://docs.gomarketbox.com/api-reference/servicebusinessmodels/update-a-business-model.md): Edits `paymentOptions`, `fees`, and `config` only. `type` is fixed at creation and there is no way to change it — to switch a service from one selling model to another, deactivate this one and add the model you want. All three fields are whole-value replacements: sending `paymentOptions` discards th… - [Toggle business model active status](https://docs.gomarketbox.com/api-reference/servicebusinessmodels/toggle-business-model-active-status.md): Turns a selling model on or off without deleting it, which is how you retire one while keeping its history. Deactivating the PACKAGE model blocks NEW packages from being created against the service, but does nothing to packages that already exist — they keep selling until you archive them individual… - [List offerings for a service](https://docs.gomarketbox.com/api-reference/serviceofferings/list-offerings-for-a-service.md): Every offering on the service, each already hydrated with the full `skills` and `locations` records behind its `skillIds`/`locationIds` — so rendering a service page needs no second round-trip per offering. Not paginated: `nextCursor` is always null and the whole set comes back at once. Soft-deleted… - [Add an offering to a service](https://docs.gomarketbox.com/api-reference/serviceofferings/add-an-offering-to-a-service.md): The offering is the sellable variant — price and duration live here, not on the service, so this is the call that makes a service purchasable. It is created ACTIVE; there is no draft step. `pricing` is a rule hierarchy, not a single amount: exactly one DEFAULT rule is required, a STATE rule is rejec… - [Get an offering](https://docs.gomarketbox.com/api-reference/serviceofferings/get-an-offering.md): One offering with its `skills` and `locations` resolved to full records, the same shape the list endpoint returns. This is where you read `pricing` and `duration` back after a write — the geo coercion means what you sent is not always what is stored. Offerings created before regional pricing existed… - [Update an offering](https://docs.gomarketbox.com/api-reference/serviceofferings/update-an-offering.md): A partial update despite the verb: only the fields you send are written and the rest are left alone. Where a field is an array — `pricing`, `skillIds`, `locationIds`, `attributeValues` — sending it replaces the whole array, so add to a set by sending the full new one, never just the delta. Supplying… - [Soft delete an offering](https://docs.gomarketbox.com/api-reference/serviceofferings/soft-delete-an-offering.md): Marks the offering deleted, forces it INACTIVE and decrements the parent service's `counts.offerings`, once: deleting an unknown or already-deleted offering is a 404 and changes nothing, so a retry is safe. The record is retained so bookings and order items that snapshot it still resolve. Packages b… - [Change offering status](https://docs.gomarketbox.com/api-reference/serviceofferings/change-offering-status.md): Takes one variant off sale without touching the rest of the service. An INACTIVE offering stops accepting new bookings while bookings already made against it stand, so this is the safe way to retire a price point or a duration. Unlike service status there is no transition table — ACTIVE and INACTIVE… - [List packages for an offering (storefront)](https://docs.gomarketbox.com/api-reference/servicepackages/list-packages-for-an-offering-storefront.md): The bundles buyable for one specific offering, ordered by status and then by credit count ascending — so the cheapest bundle leads and a price ladder renders without client-side sorting. Pass `status=ACTIVE` for the purchasable set; DRAFT and ARCHIVED bundles are included otherwise. Not paginated: `… - [Create a sellable package (bundle) for an offering](https://docs.gomarketbox.com/api-reference/servicepackages/create-a-sellable-package-bundle-for-an-offering.md): Sells `creditCount` prepaid sessions of one offering as a single bundle. The parent service must already carry an ACTIVE business model of type PACKAGE — without it this is a 400, and that guard is the usual reason a first package create fails, so add the business model before the package. The offer… - [List every package for a service (storefront discovery)](https://docs.gomarketbox.com/api-reference/servicepackages/list-every-package-for-a-service-storefront-discovery.md): Returns every package under the service, across all of its offerings — the call a storefront makes before the client has chosen an option. Pass ?status=ACTIVE for only the purchasable bundles. Each package carries its offeringId, so the client can join it against the offerings list it already holds. - [Get a package by id](https://docs.gomarketbox.com/api-reference/servicepackages/get-a-package-by-id.md): Resolves a package from its id alone, without needing the serviceId — the order and slate flows hold a `packageId` and nothing else, which is why this route exists alongside the nested ones. Read it before creating an order to confirm `creditCount`, `capacity` and the region rules you are about to b… - [Update a package](https://docs.gomarketbox.com/api-reference/servicepackages/update-a-package.md): A partial update: only the fields you send change. Editing `pricing` or `creditCount` affects future purchases ONLY — every order item already placed snapshots the package at purchase time, so repricing never disturbs credits a client has already bought and never retro-bills them. `pricing` is reval… - [Change package status (rewrites the storefront sort key)](https://docs.gomarketbox.com/api-reference/servicepackages/change-package-status-rewrites-the-storefront-sort-key.md): Moves the bundle between DRAFT, ACTIVE and ARCHIVED. Any status can follow any other — unlike services, there is no transition table, so a bundle can be pulled and reinstated freely. ARCHIVED is the correct way to retire a bundle: it drops out of the storefront and blocks new orders, while credits c… - [List locations for a project](https://docs.gomarketbox.com/api-reference/locations/list-locations-for-a-project.md): The project's locations: PHYSICAL venues where a service is delivered, VIRTUAL locations, and TRAVEL_ZONE areas a supplier travels within. Active locations only unless `includeInactive=true`; deleted locations are never returned. Filter by `locationType`, and within a type by `namePrefix`. Not pagin… - [Get a location by ID](https://docs.gomarketbox.com/api-reference/locations/get-a-location-by-id.md): One location of the project, active or inactive. A deleted location, an unknown id and another project's location all return the same 404. - [List skills for a project](https://docs.gomarketbox.com/api-reference/skills/list-skills-for-a-project.md): The project's skills — the qualifications a supplier can list on their profile. Use it to build the skill picker of a supplier profile form: the ids you send as `skillIds` to PATCH /suppliers/me come from here. Active skills only unless `includeInactive=true`; soft-deleted skills are never returned.… - [Record a manual (cash/external/comp) transaction against an order](https://docs.gomarketbox.com/api-reference/transactions/record-a-manual-cashexternalcomp-transaction-against-an-order.md): Books money that moved outside Stripe — cash at the door, a bank transfer, a comped session. Card payments do not belong here: `source` accepts only CASH, EXTERNAL and COMP, and STRIPE is rejected, because Stripe rows are created by the payment-intent flow and settled by webhook. `kind: "REFUND"` is… - [List transactions (filter by order, client, or status)](https://docs.gomarketbox.com/api-reference/transactions/list-transactions-filter-by-order-client-or-status.md): The money ledger for the project, newest first, for reconciliation and payment history. - [Create a Stripe PaymentIntent for an order (client-side confirmation)](https://docs.gomarketbox.com/api-reference/transactions/create-a-stripe-paymentintent-for-an-order-client-side-confirmation.md): Starts a card payment for whatever the order still owes. Returns a `clientSecret` to confirm with Stripe.js in the browser — the card details never reach this API. The charge is created on the project's connected account for `total - amountPaid - amountComped`, so part-paid orders are billed only fo… - [Changelog](https://docs.gomarketbox.com/changelog/overview.md): New features, updates, and fixes to the MarketBox API. ## OpenAPI Specs - [openapi](/api-reference/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.