Skip to main content
Docs

These docs now describe the production API

The docs, the API reference and its “try it” console now name the production API instead of a development host. Nothing in the API’s behaviour changed.Changed
  • Base URL. Every page reads MARKETBOX_API_URL, and its value is now the production host. See Make your first call. Dashboard links go to the production dashboard.
  • Keys belong to one environment. A key minted against the development host isn’t recognised by the production API. Mint a key in the production dashboard: see Get a project and an API key.
  • The “try it” console sends real requests to production. A booking you create there is a real booking.
Added
  • Quickstart — signing up, creating a project, where the API key and the project ID are, what a first booking needs, and TypeScript for the order and the booking. The booking example no longer uses a fixed date.
  • Test keys and sandbox — there is one kind of key, and no sandbox.
Fixed
  • Key prefixes. Examples showed keys starting mb_live_ and mb_test_. Keys have no prefix.
  • Testing payments. Accept payments with Stripe said to use Stripe test mode. Production charges in live mode, and test cards are declined.
API

API reference corrections for the November 17 release

The API reference now lists every error and field from the November 17 release. Nothing in the API’s behaviour changed, so you don’t need to change any requests.Fixed
  • POST …/orders/{orderId}/payment-intent lists 409 PAYMENT_IN_FLIGHT. The reference also said a reused intent keeps its original amount. It doesn’t: an open intent is reused only while it is for the amount owed now. When the amount owed changes, the old intent is canceled and a new one is created. Always use the clientSecret from the latest call. See Accept payments with Stripe.
  • POST …/orders/{orderId}/transactions lists 422 ORDER_NOT_PAYABLE: a SUCCEEDED PAYMENT, or a COMP adjustment, on a CANCELLED order.
  • disputeId and disputeStatus on transactions are described, including what each disputeStatus value means.
  • NOT_SELLABLE on bookings, hold conversion and package bookings — the reference said a service that isn’t LIVE is refused. On these routes only an offering that isn’t ACTIVE is refused, because they book an order item already bought. Both package-bookings routes now list the code.
  • START_END_LOCATIONS_DISABLED and SETTING_NOT_DELEGATED are in the list of error codes.
API

Stricter booking and order rules, traffic-aware offered times, a buffer before each service, and schedule start and end locations

This release makes the open API enforce the booking, order and payment rules the dashboard already applied. Offered times now account for split shifts, traffic and the drive to neighbouring bookings. Services gain an optional buffer before they start. Supplier schedules can name where the day starts and ends, once a project turns that on.Several requests that used to succeed are now refused with a 4xx code. No field was removed or renamed, and every new field is optional or nullable. Regenerate decoders for services, transactions, supplier alerts and supplier-plane schedules. Branch on the new codes rather than retrying them.Breaking
  • A service that isn’t LIVE, or an offering that isn’t ACTIVE, is no longer sold. POST …/orders and POST …/orders/{orderId}/items answer 422 NOT_SELLABLE, for example “Service srv_… is DRAFT and is not sold; only LIVE services take new bookings and orders”. A service that wasn’t LIVE used to be accepted. An inactive offering on an order item used to be 400. Bookings, hold conversion and package sessions against an order item already bought stay bookable after the service stops being LIVE, but answer 422 NOT_SELLABLE once the offering isn’t ACTIVE.
  • A PACKAGE line for a DRAFT or ARCHIVED package on POST …/orders is 422 PACKAGE_NOT_ACTIVE.
  • Your key can’t cancel a booking that has taken place. POST …/bookings/{bookingId}/status with CANCELLED on an AWAITING_CONFIRMATION booking is 400. Settle it instead, with COMPLETED or a no-show.
  • DELETE …/bookings/{bookingId} is a cancel first. A booking your key can’t cancel (AWAITING_CONFIRMATION, COMPLETED, a no-show) is 422 BOOKING_NOT_DELETABLE, and nothing changes. Deleting a booking that is already cancelled sends no second cancellation email.
  • Moving a settled booking is refused. A PATCH …/bookings/{bookingId} that changes the time or supplier of a booking that isn’t SCHEDULED or STARTED is 422 BOOKING_NOT_AMENDABLE. Its other fields can still be edited.
  • An attendance report filed with your key now settles the booking. A SUPPLIER report on POST …/bookings/{bookingId}/reports moves the booking as the supplier’s own report does: attended → COMPLETED (or DISPUTED when the client reported not attending), did not attend → SUPPLIER_NO_SHOW. A CLIENT “did not attend” on a completed booking inside the dispute window opens a dispute. A report before the session ends, on a cancelled booking, or a SUPPLIER report on a settled booking is 422 BOOKING_NOT_REPORTABLE. It was 422 UNPROCESSABLE_ENTITY, and a report never changed the status.
  • Participants only join an open booking. Registering a participant on a booking that isn’t SCHEDULED or STARTED, or checking one in on a booking that is settled, disputed or cancelled, is 422 BOOKING_NOT_OPEN_FOR_PARTICIPANTS. An AWAITING_CONFIRMATION booking still takes a check-in.
  • A cancelled order takes no new money. A PAYMENT or COMP recorded on a CANCELLED order is 422 ORDER_NOT_PAYABLE, “Order ord_… is CANCELLED and cannot take a payment”. A REFUND is still recorded.
  • One card payment at a time. POST …/orders/{orderId}/payment-intent while a card payment on the order is in progress is 409 PAYMENT_IN_FLIGHT.
  • The status routes check the id. POST …/offerings/{offeringId}/status with an unknown or deleted offering is 404 NOT_FOUND, “Offering not found”. It used to write a stub. POST …/business-models/{businessModelId}/status with an unknown id is 404, “Business model not found”.
New
  • bufferBeforeStartMinutes on services — 0 to 120, default 0, on service responses and on POST …/services and PUT …/services/{serviceId}. Suggested times leave that gap before a job of the service, online jobs included. It is never busy time, never part of travelTimeMins, and never refuses a booking made at a specific time.
  • Start and end locations on supplier-plane schedules — startLocation, endLocation, driveTiming, maxTravelOnStartDrive and maxTravelOnEndDrive on …/suppliers/me/schedules. All are nullable, and null uses the project’s default. A write is 422 START_END_LOCATIONS_DISABLED while the project has the feature off, and 422 SETTING_NOT_DELEGATED for a setting the project keeps. Sending null or the stored value is never refused. The feature is off for every project until it is turned on.
  • disputeId and disputeStatus on transactions — set when a card payment is disputed. Read-only.
  • PAYMENT_NEEDS_REVIEW in the alert kind enum — with payload.paymentReason. It is a staff alert, so GET …/suppliers/me/alerts doesn’t return it to a supplier. Typed clients should still accept the value. See Supplier portal: insights and alerts.
Changed
  • Offered times. Each block of a split shift offers its own first and last time. Open slots leave time to drive to and from neighbouring bookings. Drive times account for traffic at the time of day, so rush-hour times can move later or disappear, and travelTimeMins reports the drive with traffic. A supplier whose bookings can’t be routed shows up in errors[] instead of failing the whole search.
  • POST …/availability/time-slots — metrics.totalTravelTimeRequestsMade counts distinct drives across the whole request. A recurring window in a time zone ahead of UTC lands on the right weekdays.
  • POST …/orders/{orderId}/payment-intent bills total − amountPaid − amountComped. An order paid or comped in full is 400.
  • A delivered package session cancelled without a creditTreatment is FORFEIT. A session still to come is still RETURN.
  • POST …/holds/{reservationId}/release can answer 409 OCCUPANCY_CONTENTION. The hold is still HELD. Retry the release.
  • Supplier photo and active writes can answer 409 CONFLICT when another request changed the same record meanwhile. Read the supplier again and retry.
  • POST …/clients/me makes an existing member a client. An admin or supplier who signs in on your booking site gains the CLIENT role.
  • Deleting a supplier-plane schedule keeps a travel zone another schedule uses.
  • GET …/orders with paymentMethod keeps settled orders that were later cancelled, with their status.
What this means for you
  • Handle the new codes without retrying. NOT_SELLABLE, PACKAGE_NOT_ACTIVE, BOOKING_NOT_DELETABLE, BOOKING_NOT_AMENDABLE, BOOKING_NOT_REPORTABLE, BOOKING_NOT_OPEN_FOR_PARTICIPANTS and ORDER_NOT_PAYABLE won’t succeed on retry.
  • Settle sessions that took place instead of cancelling them.
  • Expect offered times to change at rush hour and around split shifts. Don’t cache drive times across times of day.
  • Accept the new optional fields on services, transactions, alerts and schedules.
Full detail: Errors → Common error codes, Bookings, Cancel or reschedule a booking, Orders, Services, Availability, Supplier portal: availability.
API

Supplier access checks and refusal codes, expired slates can’t be held, client disputes, and 4xx instead of 500s

This release lets a supplier portal check, on sign-in, whether the person may use the supplier plane. Supplier-plane refusals now name their cause. Holds refuse slates that have expired. A client’s “didn’t attend” can open a dispute. Deleting an order that holds bookings or money is refused. Many caller mistakes that came back as 500 INTERNAL_ERROR now return a 4xx that says what to fix.Two breaking changes: SUGGESTION_EXPIRED on holds, and the supplier-plane refusal codes. Separately, VERSION_CONFLICT replaces CONFLICT for a stale availability version, so that is a code change too if you match on code. No field was removed or renamed. Regenerate decoders for GET /suppliers/{supplierId}, which gains a required access object.Breaking
  • SUGGESTION_EXPIRED: a hold from an expired slate is refused. POST …/holds with slateId or slotIds past its resolvableUntil (24 hours after it was planned) answers 409 SUGGESTION_EXPIRED, “Slot … is past its resolvable window”. Extending a hold the same way is refused too. It used to succeed, holding times planned from availability that may have changed. Plan a fresh slate and hold that. A heartbeat that re-posts the held intervals is unaffected. Convert doesn’t re-check the window, so a client who takes a while to pay still books. See Holds.
  • Supplier-plane refusal codes (statuses unchanged). /suppliers/me routes now name why they refuse, where they used to answer 403 FORBIDDEN or 404 NOT_FOUND:
    • 403 NOT_A_MEMBER, “You are not a member of this project.”: no membership of the project. It was FORBIDDEN, “No active membership on this project”.
    • 403 MEMBERSHIP_INACTIVE, “Your access to this project has ended.”: every role was removed. It was FORBIDDEN, “No active membership on this project”.
    • 403 NO_SUPPLIER_ROLE, “You don’t have supplier access on this project.”: the roles the person acts under lack the route’s permission. It was FORBIDDEN, “Insufficient permissions for this action”.
    • 404 NO_SUPPLIER_ROLE: the permission passed, but the person acts under no SUPPLIER role. It was NOT_FOUND, “No supplier record for current user”.
    • 404 SUPPLIER_NOT_LINKED, “Your sign-in isn’t linked to a supplier record on this project.”: the person holds SUPPLIER, but no single supplier record is linked. It was NOT_FOUND, “No supplier record for current user”.
    A booking, schedule or other id that isn’t the supplier’s is still 404 NOT_FOUND. “User account not found. Complete registration first.” is still 403 FORBIDDEN. The client plane (/clients/me) is unchanged. See Supplier portal → Refusals.
Added
  • GET /v1/projects/{projectId}/suppliers/me/access — takes the API key and the person’s access token, and always answers 200 with { allowed, reasonCode, message, supplierId, roles, membershipStatus }. reasonCode is one of seven codes:
    • SUPPLIER_ACTIVE, the only one with allowed: true;
    • SUPPLIER_RECORD_INACTIVE, NO_ACCOUNT, NOT_A_MEMBER, MEMBERSHIP_INACTIVE, NO_SUPPLIER_ROLE and SUPPLIER_NOT_LINKED.
    It ignores X-MB-Acting-Role. Wrong credentials still fail with 401 or 403. See Check access first.
  • access on GET /v1/projects/{projectId}/suppliers/{supplierId} — userId, invitationStatus, roles (empty unless the membership is ACTIVE), membershipStatus (ACTIVE, INACTIVE or null) and accessEndedAt. accessEndedAt is set when the person is unlinked, and is null for removals made before this release. GET /suppliers and POST /availability/suppliers don’t carry it. See Removed, or never a supplier.
  • conflicts[].supplierId on 409 SLOT_HELD / SLOT_BOOKED: the supplier whose calendar is blocked, null when unknown. It was in the schema but never sent.
Changed
  • A stale availability version is 409 VERSION_CONFLICT, not 409 CONFLICT. This covers PATCH on …/suppliers/me/schedules/{scheduleId}, …/blocked-times/{blockedTimeId} and …/travel-zones/{travelZoneId}. It also covers another write landing during a DELETE of any of them. The status is still 409. An overlapping ACTIVE schedule stays 409 CONFLICT, so branch on code. See Supplier portal → Set working hours.
  • Acting as CLIENT never serves a supplier’s bookings. A request to the supplier plane’s bookings routes with X-MB-Acting-Role: CLIENT is 404 NO_SUPPLIER_ROLE, even when the person has a linked supplier record. It used to answer 200. The alerts routes always read the supplier’s own inbox, whatever the header names.
  • DELETE …/orders/{orderId} refuses a real order. An order holding a booking (booked or delivered), or a PENDING or SUCCEEDED payment or refund, answers 409 ORDER_NOT_DELETABLE, and nothing changes. Cancel it with POST …/orders/{orderId}/status instead. An order that books nothing and took no money still deletes. See Orders.
  • A client’s “didn’t attend” can open a dispute. A supplier report of attended: true makes the booking DISPUTED, not COMPLETED, when a client report already says attended: false. A client’s attended: false within 24 hours of a booking becoming COMPLETED also makes it DISPUTED, whoever completed it. Client reports filed with your key count toward the first case only. Nothing settles a booking on a timer. See Attendance and disputes.
Fixed
  • Booking writes return 4xx instead of 500. POST …/bookings, PATCH …/bookings/{bookingId}, POST …/holds/{reservationId}/convert and both package-bookings routes now answer:
    • 409 SLOT_HELD / SLOT_BOOKED when a reschedule’s new time is taken, with conflicts[] and hint;
    • 409 OCCUPANCY_CONTENTION when the supplier’s calendar is under heavy writes;
    • 409 VERSION_CONFLICT when the booking changed since you read it;
    • 404 NOT_FOUND for an unknown location, and 400 BAD_REQUEST for one of the wrong type or another supplier’s travel zone;
    • 422 UNPROCESSABLE_ENTITY for a PHYSICAL Location without coordinates.
  • Converting a PHYSICAL hold works. It used to fail with a 500.
  • Converting a package hold answers package refusals with their own codes, as POST …/package-bookings does, instead of 500: 409 ORDER_ITEM_QUANTITY_UNAVAILABLE, 409 PACKAGE_EXPIRED, 422 PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC and 422 BEST_EFFORT_NOT_ENABLED. Nothing is booked in any of them.
  • An offering’s holdDurationMinsOverride is saved. It was accepted but dropped, so holds ignored it. A hold placed from a slate or slot of that offering now lasts that long when the request sends no holdDurationMins. null clears it.
  • NOT_A_PACKAGE_SERVICE is listed with the other error codes. The API already returned it (400) for a PACKAGE booking or convert whose service has no active PACKAGE business model.
  • POST …/orders/{orderId}/items with skuType: "PACKAGE" is 400 VALIDATION_ERROR: “skuType: a PACKAGE line can only be added when the order is created: send it in POST /orders items[] with a packageId”. Nothing is written. The request schema no longer lists PACKAGE for this route.
  • POST …/availability/search and POST …/availability/suppliers with an unknown id are 404 NOT_FOUND, naming it. For an offering, the message is “Service offering off_… not found on service srv_…”. For a locationId sent without lat/lng, it is “Location loc_… not found”. A search location with no coordinates is 400 BAD_REQUEST, “Could not resolve coordinates for the requested location”.
  • Updating an offering or a business model with an unknown id is 404 NOT_FOUND. PUT …/offerings/{offeringId} (“Offering not found”) and PUT …/business-models/{businessModelId} (“Business model not found”) used to write a new, partial record. Nothing is written now. The status routes are unchanged.
  • A supplier’s move under calendar contention (PATCH …/suppliers/me/bookings/{bookingId}) is 409 OCCUPANCY_CONTENTION, not 500.
  • An offering with no DEFAULT price rule is 422 OFFERING_NOT_PRICED on every write that prices it, not 500.
  • PATCH …/suppliers/me refuses unknown serviceIds and skillIds with 400 BAD_REQUEST naming them, before anything is written. It used to save them.
  • Deleting an order cancels its bookings. A delete sets the order CANCELLED, but its bookings used to stay SCHEDULED. Now any booking that reaches the order during the delete is cancelled, without emails.
  • Package-booking examples use the real off_ offering prefix. The reference showed offr_.
What this means for you
  • Hold only fresh slates. On 409 SUGGESTION_EXPIRED from POST …/holds, plan a new slate rather than retrying.
  • Match the new supplier-plane codes. If your portal branches on FORBIDDEN or NOT_FOUND from /suppliers/me to detect lost access, also branch on NOT_A_MEMBER, MEMBERSHIP_INACTIVE, NO_SUPPLIER_ROLE and SUPPLIER_NOT_LINKED.
  • Check supplier access on sign-in. Call GET /suppliers/me/access when the person signs in and when your portal renews its session. Use the plane only when allowed is true; otherwise show message. Don’t send X-MB-Acting-Role from a portal.
  • Tell removed from never invited with accessEndedAt. If your app reads supplier data with the API key, end a supplier’s session when the record has no link and accessEndedAt is set.
  • Branch on VERSION_CONFLICT in your supplier portal. On it, re-read the row and retry. Show an overlap message only on CONFLICT.
  • Cancel orders instead of deleting them. Keep delete for an order raised in error that books nothing and took no money.
  • Don’t treat COMPLETED as final for 24 hours. Anything you do once a session is delivered, such as payouts or follow-ups, should wait out the dispute window.
  • Handle DISPUTED wherever you show a booking’s status. An operator resolves it in the MarketBox console; your key can’t.
  • Stop retrying writes that failed with a 500. The same failures now arrive as a 4xx that says what to fix. Don’t retry those either: fix the id or the request.
Full detail: Supplier portal: sign-in and access, Holds, Orders → The order lifecycle, Bookings → Attendance and disputes, Bookings → Creating a booking, Supplier portal → Set working hours, Suppliers → Who can sign in as this supplier, Order lifecycle after checkout, Search suppliers by availability, Errors.
API

Package credits: plan from a credit, clients book their own, and cancelled orders book nothing; supplier alerts

You can now plan a slate from a credit the client already owns, and the signed-in client can book their own credit through a new client-plane route. A package credit books only its own offering, and a cancelled order’s credits can no longer be planned or booked. Your supplier portal can now show the dashboard’s alerts, and supplier emails can link to your portal.Two breaking changes, two behaviour changes, the rest additive. No field was removed or renamed. Strict response decoders need a regeneration for quantityReturned on GET …/clients/me/credits, and for the 409 bodies of POST …/bookings and POST …/holds/{reservationId}/convert, which the spec now describes as a union with the plain error envelope.Breaking
  • A package credit books only its own service and offering. POST …/orders/{orderId}/package-bookings used to accept sessions of any offering. Every service line of every session must now match the order item’s serviceId and offeringId, or the call is 400 ORDER_ITEM_SERVICE_MISMATCH and nothing is booked. This applies to slateId, slotIds and sessions.
  • A CANCELLED order plans and books nothing. POST …/availability/package-slate (from a credit), POST …/orders/{orderId}/package-bookings, POST …/bookings and POST …/holds/{reservationId}/convert answer 409 ORDER_CANCELLED for an order that is CANCELLED. Convert refuses even a hold that already converted. DRAFT, PENDING and PAID orders book as before: payment is still not a gate.
Changed
  • A same-key retry replays after the credits ran out. Retrying POST …/package-bookings with the same idempotencyKey and body now returns the stored 201, even when the first call used the last credits. It used to be 400 ORDER_ITEM_QUANTITY_UNAVAILABLE. A replay sends no second confirmation email. A slateId or slotIds retry must still arrive within the slate’s window.
  • A reused key with a different body is always 409 IDEMPOTENCY_KEY_CONFLICT, even when that body is invalid on its own. It used to get that body’s 400 or 404.
  • Stale-slate freshSuggestions are planned from the order item you are booking — its remaining sessions, offering and expiry — so they can be booked on it. null when the item has nothing left to plan.
  • DELETE …/suppliers/{supplierId} can answer 409 CONFLICT when the supplier’s sign-in changes during the delete. Try again.
New
  • Plan a slate from a credit. POST …/availability/package-slate takes orderId + orderItemId instead of packageId. It plans the credit’s remaining sessions in its own offering, ends at its expiresAt, and works after the package was deleted. Send exactly one source. Add an optional clientId to have the order checked against that client: another client’s order is refused like a missing one (400 INVALID_ORDER_REFERENCE). A credit that can’t be planned is 409 ORDER_ITEM_QUANTITY_UNAVAILABLE, 409 PACKAGE_EXPIRED, 409 ORDER_CANCELLED, 400 NOT_A_PACKAGE_ITEM, 400 INVALID_ORDER_REFERENCE or 404 NOT_FOUND.
  • POST …/clients/me/orders/{orderId}/package-bookings — the signed-in client books their own credit, with the API key and their access token. Same body, response and refusals as the API-key route. Another client’s order is a 404 identical to a missing one. A credit GET …/clients/me/credits would not list is 409 CREDIT_NOT_BOOKABLE. Booking by slateId or slotIds needs a slate planned from that credit.
  • quantityReturned on GET …/clients/me/credits — the sessions cancellations have returned to the credit, ever. Already counted in quantityRemaining; a returned session may have been booked again since.
  • Supplier alerts on the supplier plane. GET …/suppliers/me/alerts, GET …/suppliers/me/alerts/summary, POST …/suppliers/me/alerts/read-all and POST …/suppliers/me/alerts/{alertId}/read — the dashboard’s bell, from the same inbox. A cursor from another filter is 400 INVALID_CURSOR.
  • Supplier emails can link to your portal. When a project admin sets a supplier portal URL in the dashboard, the supplier booking emails link there, with bookingId when the email is about one booking.
What this means for you
  • Plan package slates for the offering the credit was sold with. Plan from the credit itself to be sure. Handle 400 ORDER_ITEM_SERVICE_MISMATCH.
  • Handle 409 ORDER_CANCELLED as final. Don’t retry; offer a new order.
  • Keep the same idempotencyKey when you retry a booking, and a fresh one for each new attempt.
  • Don’t add quantityReturned to quantityRemaining. It is already included.
Full detail: Create a package booking → What a booking call checks, Create a package booking → Book the sessions left on a credit, Book a client’s package credit → What the booking call checks, Supplier portal → Alerts, Supplier portal → Links in MarketBox emails, Errors → Package credit codes.
API

The supplier plane, site events, and API-key capabilities

Suppliers can now manage their own work from your branded portal. The new supplier plane, /v1/projects/{projectId}/suppliers/me, carries their profile and photo, bookings and attendance reports, cancel and reschedule, working hours, blocked time, travel zones, venues, and demand and search insights. Your site can also report which suppliers it showed, so suppliers’ search insights count them. API keys now carry capabilities, and a key without standard access is refused.One breaking change, two behaviour changes, the rest additive. No field was removed or renamed. The breaking change cuts off no live key today. Strict response decoders need a regeneration for searchId, position, engineEnabled, attribution and participantSettings.Breaking
  • A key without Standard API access is refused. Every route except POST …/events now needs the * capability. A key with no capabilities ticked, or only Site events, gets 403 CAPABILITY_NOT_GRANTED before anything else is read. Keys minted before capabilities existed are treated as * and keep working.
Changed
  • End-user routes require an ACTIVE membership. Every /clients/me route except onboarding, and every /suppliers/me route, checks the person’s membership of the project on each request. No membership is 403 FORBIDDEN, “No active membership on this project”. When the business removes a person’s role, their next call is refused.
  • Onboarding refuses a removed client. POST …/clients/me answers 403 MEMBERSHIP_INACTIVE for a person whose access the business removed, and reads or links nothing.
  • Coming: end-user tokens must come from your Application’s own client. A token issued to another client — the MarketBox dashboard’s or another Application’s — is logged today and still accepted. Once enforcement is switched on, it is 401 UNAUTHORIZED.
New
  • The supplier plane — 33 operations under /v1/projects/{projectId}/suppliers/me, each the twin of a dashboard screen. They take the API key and the supplier’s access token. Cancel and reschedule follow the service’s participant settings, with new codes PARTICIPANT_ACTION_DISABLED, BOOKING_NOT_SCHEDULED, NOTICE_WINDOW_PASSED, NEW_START_INSIDE_NOTICE_WINDOW, SLOT_UNAVAILABLE and SLOT_UNVERIFIABLE. Attendance reports add BOOKING_ALREADY_SETTLED and BOOKING_NOT_REPORTABLE. The profile adds FIELD_NOT_SELF_EDITABLE; insights add INSIGHTS_DISABLED.
  • GET …/locations and GET …/locations/{locationId} — the project’s venues, virtual locations and travel-zone areas, with the API key alone. Not paginated. The single read returns inactive locations too.
  • GET …/skills — the project’s skills, for a supplier profile’s skill picker and the skills availability filter.
  • Site events. POST …/events (from your server, needs the events:write capability) and POST …/events/beacon (from the browser, with a publishable key and an origin allowlist). New codes PAYLOAD_TOO_LARGE (413), RATE_LIMITED (429) and SERVICE_UNAVAILABLE (503).
  • searchId and position on every search. POST …/availability/search, /suppliers, /package-slate, /package-options, /time-slots and GET …/suppliers return a searchId (also the X-MB-Search-Id header), and rank each supplier or slate with a 0-based position. POST …/availability/search also returns suppliers. Two optional request headers, X-MB-Session-Key and X-MB-Client-Kind, tag a search for insights.
  • engineEnabled on POST …/availability/search. false means the project’s scheduling engine is off, so timeSlots is empty because it wasn’t computed.
  • attribution on POST …/orders — the searchId, sessionKey and surface the purchase came from. Copied onto every booking the order funds.
  • participantSettings on services — what suppliers and clients may do with, and see on, bookings of the service. Replaced whole on PUT.
  • X-MB-Acting-Role is checked. An end-user request naming a role the person doesn’t hold is 403 ACTING_ROLE_NOT_HELD.
What this means for you
  • Check every Application has Standard API access. Open API Access in the dashboard. A key with nothing ticked, or only Site events, now gets 403 CAPABILITY_NOT_GRANTED.
  • Forward the access token from your own Application’s client on every /clients/me and /suppliers/me call. Don’t forward the ID token, or a dashboard token.
  • Handle 403 on end-user routes as “access removed”. Show the person how to contact the business, not a retry.
  • Report what you draw. Send search.rendered with each search’s searchId. A search you don’t report counts for nothing in suppliers’ insights.
  • Check engineEnabled before telling a client nobody is free.
Full detail: Build a supplier portal, Report site events, Locations and skills, Authentication → Capabilities, End-user authentication → Who may call an end-user route, Availability → Search, Orders → Attribution, The booking engine model → Participant settings, Errors.
API

Package purchases are taxed, and order tax is computed, not set

The platform now computes every order’s tax, and package lines are taxed like any other line. A line with no tax says why. PATCH …/orders/{orderId} no longer lets you overwrite tax.One breaking change, the rest a behaviour change and additive fields. No field was removed or renamed. Strict response decoders need a regeneration for taxExemptReason on order items.Breaking
  • tax on PATCH …/orders/{orderId} can no longer change the order. It is accepted only when it equals both the tax the lines compute and the tax the order stores. Any other figure is 400 TAX_MISMATCH, and nothing is written. The same code is returned when the order has lines in a different currency. Omit tax.
Changed
  • Package lines are taxed. A PACKAGE line now takes the tax its price rule resolves, like a single-session line. Package lines written between June and September 2026 keep their zero tax.
  • The service’s tax settings are the last fallback. When neither the matched price rule nor its parent rules set tax, a line uses the service’s taxSettings. Lines that used to carry no tax can now be taxed.
  • A taxable fee borrows the rate of the first line taxed at a positive rate. Untaxed and 0% lines no longer shadow a taxed line listed after them, so line order no longer changes a fee’s tax.
New
  • taxExemptReason on order items — why a line carries no tax: NO_RATE, NOT_TAXABLE, ZERO_RATE, MIGRATED_V1 or PACKAGE_EXEMPT_LEGACY. Absent when the line is taxed at a positive rate, and on lines written before the field existed.
What this means for you
  • Stop sending tax on PATCH …/orders/{orderId}. Handle 400 TAX_MISMATCH if you can’t remove it yet.
  • Show the tax the API returns on package checkouts. Package totals now include tax where the price rule or service sets a rate.
  • Branch on taxExemptReason, not on skuType, to explain a zero tax.
Full detail: Orders → How tax is computed, Orders → Updating an order, Service fees → A taxable fee borrows the rate of a taxed line, Errors.
API

Orders settle from the ledger, cancels settle the credit, and clients carry their real names

This release makes money and credit follow one rule. An order becomes PAID only when its ledger covers its total. Cancelling a package session returns or forfeits its credit in the same write. Onboarding also accepts the name your checkout collected, so a client who signed up with an email address is no longer shown under the part before the @.Three breaking changes, the rest additive. No field was removed or renamed. See Breaking below. Strict response decoders need a regeneration for the new booking, order, order-item, transaction and client-address fields.Breaking
  • PAID can no longer be requested. POST …/orders/{orderId}/status answers a PAID target with 409 ORDER_NOT_SETTLED. An order becomes PAID when its ledger covers its total: record cash, external or comp money with POST …/orders/{orderId}/transactions, and let the Stripe webhook settle cards. A PAID request is refused with that 409 from every status, including PENDING.
  • NO_SHOW can no longer be set. Sending it to POST …/bookings/{bookingId}/status is a 400. Send CLIENT_NO_SHOW or SUPPLIER_NO_SHOW. Bookings recorded before the split still carry NO_SHOW on every read, and will indefinitely.
  • An order line the service is not sold as is refused. POST …/orders and POST …/orders/{orderId}/items return 422 SERVICE_NOT_SOLD_AS when the service has no active rate of the line’s kind, such as a SINGLE_SESSION line with no active SINGLE_BOOKING rate. Such lines used to be written with no rate attached, and so without its fees.
New
  • firstName and lastName on POST …/clients/me, beside phone. Each field you send overwrites the stored value and is copied to the client’s record in Stripe. Blank or null means not sent. At most 80 characters after trimming.
  • PATCH …/clients/me — change the signed-in client’s firstName, lastName or phone. Names can be changed but not cleared; phone: null clears the phone. Call it before POST /orders so emails use the new name.
  • creditTreatment on POST …/bookings/{bookingId}/status, with CANCELLED only. RETURN (the default for a package session) puts the session back on the order item and records a CREDIT_REVERSAL. FORFEIT keeps it spent. Sending it for a booking with no package credit is 422 NO_SESSION_CREDIT, and nothing is cancelled.
  • Three listing modes on GET …/orders. status is no longer required. Send status, or paymentMethod (with startSettledAt/endSettledAt), or neither to list every order (with startCreatedAt/endCreatedAt). Mixing modes is a 400. The no-filter mode is missing orders created before this release until a backfill runs.
  • reason and idempotencyKey on POST …/orders/{orderId}/transactions. reason is required with source: "COMP". The same idempotencyKey on the same order returns the first row as 200 with replayed: true instead of recording the money twice. A first recording is 201 with replayed: false.
  • skills on POST …/availability/search — supplier skill ids a supplier must all hold to be considered.
  • bio: null on PUT …/suppliers/{supplierId} clears the bio. Omitting it still keeps it.
  • New response fields.
    • Order: paymentMethod, settledAt, amountComped.
    • Order item: priceSource (RULE or MANUAL).
    • Booking: creditTreatment, cancellationInitiatedBy, cancellationReasonCode, durationOverrideMinutes, durationOverrideReason.
    • Transaction: channel, reason, and the CREDIT_REVERSAL kind.
    • Client address: latitude, longitude.
Changed
  • Cancelling settles the order item. A cancelled package session returns its credit by default. A cancelled single session closes its allocation and returns no quantity. DELETE …/bookings/{bookingId} settles the same way as a default cancel.
  • The card is saved on public-API checkout. When the order’s client has an email, the PaymentIntent sets setup_future_usage: off_session. Tell the client their card will be saved.
  • Body ids are fenced to your project. A clientId or supplierId from another project is a 404 with nothing written, on booking create and update, participants, order create, package bookings, holds and manual transactions.
  • A booking line must match its order item’s kind. A businessModelType the order item is not sold as is 400 ORDER_ITEM_BUSINESS_MODEL_MISMATCH.
  • Cancellation emails report what happened to the client’s session credit, and do not include the cancellationReason text.
What this means for you
  • Stop setting orders to PAID. Record the payment instead, and read status back.
  • Send an idempotencyKey on every manual transaction you might retry, and branch on replayed.
  • Send reason with every comp.
  • Replace NO_SHOW in requests with CLIENT_NO_SHOW or SUPPLIER_NO_SHOW. Keep handling it in responses.
  • Decide your late-cancel policy. Send creditTreatment: "FORFEIT" when a package session should stay spent. Otherwise it goes back to the client.
  • Send firstName and lastName on onboarding, especially for email-and-password sign-ups.
  • Handle 422 SERVICE_NOT_SOLD_AS on order create, and check the rates on services you sell.
  • Don’t treat the no-filter orders list as complete for historical data. List by status when you need every order.
  • Tell clients at checkout that their card will be saved.
Full detail: Orders → Settling an order, Orders → Listing orders, Bookings → Cancelling and the package credit, Booking flow auth → Onboard the client, Errors.
API

Every slot time is one instant, every zone is IANA, and bookings say who moved them

Availability slots used to take their clock digits from the supplier’s own zone and their offset from the timezone you passed, so when the two differed the string described a different moment than the one the supplier was free at — a Toronto supplier viewed with timezone: "America/Los_Angeles" was three hours off. Recurring schedules also used one fixed offset for their whole span and drifted an hour after a daylight-saving change. Both are fixed, and the booking lifecycle now carries the statuses the platform has been using internally.Additive on the wire, with one breaking validation change. No field was removed or renamed. A request that previously sent an abbreviated timezone will now be rejected — see Breaking below. Strict response decoders need a regeneration for the new booking statuses and the new slot and envelope fields.New
  • timeSlotStartUtc on every slot in timeSlots[] and openSlots[] from POST /v1/projects/{projectId}/availability/search and …/time-slots. The slot start in UTC, always Z-suffixed, always the same instant as timeSlotDateAndTime. Prefer it as the booking anchor. Package slates derive each session’s bookingStartUtc from it. This is a response shape:
  • supplierZones on POST /v1/projects/{projectId}/availability/search — each returned supplier’s own profile zone, keyed by supplierId. The recommended bookingTz for a virtual booking with no service location: location zone, else supplier zone, else project default. A supplier missing from the map has no profile zone.
  • Four booking statuses: AWAITING_CONFIRMATION, DISPUTED, CLIENT_NO_SHOW, SUPPLIER_NO_SHOW — on every booking response and on the status filter of the three list endpoints. AWAITING_CONFIRMATION and DISPUTED are entered by the platform after a session ends and can only be observed. CLIENT_NO_SHOW / SUPPLIER_NO_SHOW replace NO_SHOW, which no longer said which side was absent. See Bookings → The booking lifecycle.
  • statusUpdatedBy and statusUpdatedByCapacity on every booking — who last changed the status and in what capacity (ADMIN, SUPPLIER, CLIENT, SYSTEM, API). A change made through the public API is attributed to the API key that made it, in the API capacity.
  • lookAheadStartDate accepts a Z instant on recurring …/availability/search. A Z suffix and a numeric offset are equally valid there; the “must carry a numeric offset” 400 is gone from that endpoint. …/package-slate and …/package-options still require a numeric offset.
Changed
  • Corrected slot times. timeSlotDateAndTime keeps its name and now renders the slot instant in the response timezone with that zone’s offset at that instant, so digits and offset always agree and the string always parses to timeSlotStartUtc. If your code parses the whole string you will simply see correct times. If it reads only the clock digits, pass timezone explicitly to keep receiving that zone’s clock. On …/availability/suppliers, startUtc is now the engine instant verbatim and startLocal is rendered in the response timezone.
  • Daylight saving. A supplier’s weekly schedule now keeps its local wall clock across a transition (a 9:00 lesson stays 9:00 in the supplier’s zone) and the UTC instant shifts. That is correct; do not “fix” it on your side.
  • Package sessions are stamped with the home zone. Slots from …/package-slate and …/package-options, and the bookings created from them, carry bookingTz equal to the session’s home zone — the service location’s zone, else the supplier’s, else the project default — instead of the timezone you sent. bookingStartUtc is unchanged.
  • Recurring search windows resolve on the local date. On recurring …/availability/search, the window and the recurrence anchor are read on the local date in the request timezone, so a midnight-UTC lookAheadStartDate against a zone west of Greenwich anchors one day earlier than before. A value that does not parse is a 400 in the standard error envelope rather than a raw validation payload.
  • POST …/bookings/{bookingId}/status request enum is narrower than the response. SCHEDULED and DISPUTED are no longer advertised as settable — they were always rejected. NO_SHOW is deprecated, still accepted, and will be removed in a later version (it was: since the September 23, 2026 release, sending NO_SHOW is a 400). An API key can request every transition an operator can except resolving a dispute or reversing a settled booking back to AWAITING_CONFIRMATION. A transition the booking cannot make is a 400 naming the booking’s current status.
  • Supplier timezone drives the daily agenda email. It is used verbatim as the schedule zone for the supplier’s 07:00 agenda; unset inherits the project default.
Breaking: timezone values must be IANA identifiersEvery zone field is validated on write. Accepted: any IANA identifier containing a / (America/Toronto, Australia/Sydney, Asia/Kolkata) and the literal UTC; deprecated aliases with a / (US/Pacific) still pass. Rejected with 400 VALIDATION_ERROR: abbreviations (EST, PST, IST, CET), legacy names without a / (Hongkong, Japan), numeric offsets (-05:00), and values with surrounding whitespace. The message names the field:
Stored values are not re-validated on read.What this means for you
  • Search your code for hard-coded zone strings sent to the API and replace abbreviations with IANA ids: EST → America/Toronto or America/New_York, PST → America/Los_Angeles, IST → Asia/Kolkata.
  • Prefer timeSlotStartUtc for anything that computes with a slot time; treat timeSlotDateAndTime as a display convenience.
  • If you rely on the clock digits in timeSlotDateAndTime, pass timezone explicitly on every availability request.
  • If you display package sessions using bookingTz, expect the home zone rather than your request zone.
  • Regenerate response types for the four new statuses, statusUpdatedBy, statusUpdatedByCapacity, timeSlotStartUtc and supplierZones. Handle AWAITING_CONFIRMATION and DISPUTED as in-flight, not failed.
  • Stop sending NO_SHOW. Send CLIENT_NO_SHOW or SUPPLIER_NO_SHOW instead.
  • A “no Z” guard on lookAheadStartDate is now only needed for the package endpoints, not for recurring search.
Full detail: Timezones, Availability → Slot times and zones, Bookings → The booking lifecycle.
API

Supplier directory: servedRegions, point search, one liveness rule — plus booking locale and E.164 phones

You can now see exactly why a supplier does or does not match the region filter, search the directory by coordinate, and record the language a purchase was made in.Purely additive on the wire, with one behaviour change. No field was removed or renamed and every request valid before this release is still valid. servedRegions is a new required field on every supplier response, so strict response decoders need a regeneration. The liveness change below can make locations[] shorter than it was.New
  • servedRegions on every supplier response — the rows of GET /v1/projects/{projectId}/suppliers, the detail endpoint, the create, update, services, skills and avatar responses, and data[].supplier on POST /v1/projects/{projectId}/availability/suppliers. Sorted slug region paths at every hierarchy level — the same set the country/state/city filter matches against, so membership is explainable from the record. [] when there is no live schedule with a geocodable zone. This is a response shape:
  • lat + lng on GET /v1/projects/{projectId}/suppliers — both or neither. Returns suppliers whose live travel zone contains the point, tested against the real polygon or radius, AND-combined with services/skills. Exclusive with country/state/city (400). Fixed-location-only suppliers have no zone and are not matched by a point. The first way to ask “who covers this address?” without a service and an offering.
  • Borough matching. Coverage now resolves to the locality, its borough and the wider municipality, so a Scarborough zone is returned by city=Scarborough and city=Toronto. Previously only the municipality matched.
  • locale on POST /v1/projects/{projectId}/orders — optional, the language the buyer completed the purchase in. Normalized to canonical BCP-47 (en-us → en-US); malformed is a 400 VALIDATION_ERROR. Immutable on the order, snapshotted as locale onto every booking the order funds (never accepted on POST /bookings), and saved as the client’s defaultLocale (latest booking wins). Suppliers gain a staff-set defaultLocale on create and update (null clears on update) and in every response — distinct from the existing languages and derived locales.
  • Three review-URL tokens beside {bookingId}: {bookingLocale}, {clientLocale}, {supplierLocale}. Each falls back only to the project default, never to another token. See Emails.
Changed
  • One schedule-liveness rule. A schedule is live when it is ACTIVE, not deleted, and its endDate has not passed in the schedule’s own timezone. locations[], the region filter, servedRegions and the detail endpoint’s availability.schedules all use it. Before this release locations[] and availability.schedules ignored endDate, so a supplier whose only schedule had ended still advertised a travel zone the filter no longer matched — in one real project, 80 records carried country: "CA" on their profile while ?country=CA returned 49 rows. locations[] and availability.schedules can now be shorter, including [], for suppliers you saw as bookable yesterday.
  • Supplier phone is validated and normalized. Create and update accept E.164 or a national NANP number and store E.164 (+14165550134); anything unparseable is a 400 VALIDATION_ERROR. Update accepts null to clear. Rows written before this release keep whatever was typed until next edited.
What this means for you
  • Regenerate response types. servedRegions: string[] is required everywhere a supplier is returned.
  • Stop deriving “does this supplier serve Toronto?” from profile city/state. Read servedRegions, or use the filter — they agree by construction. locations[] is per-request; servedRegions is swept daily and can lag a schedule’s endDate by up to a day.
  • If you filter by city, expect more rows where boroughs exist. Nothing you matched before stopped matching.
  • If you cached locations[] to decide bookability, refresh: a schedule past its endDate no longer contributes. schedules: [] on the detail endpoint now really means “cannot be booked”.
  • Send locale on order create if your storefront is localized and you use a review redirect URL — it is the only way MarketBox can learn the language, and the tokens fall back to the project default without it.
  • Don’t pre-format phones, and don’t assume the stored value matches what you sent — read it back.
Full detail: Suppliers → Regions served, Listing suppliers, Orders → Creating an order.
API

Every slate now says why it isn’t a perfect match: matchNotes and advice

matchScore told you how well a slate matched, and matchComponents told you which criterion missed. Neither told you why — so a booking UI could show “3 of 4 weeks” and had nothing to put underneath it. Slates now carry matchNotes: one coded reason per departure, each with the evidence behind it.Purely additive. No existing field changed shape, meaning, or gating. Every request valid before this release is still valid, and every response field you already read is unchanged. This one is safe to adopt at your own pace — unlike the cadenceSummary release below it, which removed a field.New
  • matchNotes on every slate (PackageSlateDto) — an array of { code, component, weekStart?, evidence } objects. Always present: nothing departed from your request means [], not a missing key, so .length is safe to read without a null check. It is not gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning.
  • Nine codes, each with its own evidence shape, discriminated on code so your generated types tell you exactly which fields are present: SUPPLIER_UNAVAILABLE_WEEK, WEEK_EXCLUDED_BY_FILTERS, WEEK_SUPPLY_INSUFFICIENT, WEEK_CAPPED, SESSIONS_EXHAUSTED, CADENCE_RELAXED, SESSIONS_OUTSIDE_PREFERRED_TIMES, FIRST_SESSION_LATE, PACKAGE_UNDERFILLED.
  • advice on every slate, optional — a forward-looking hint naming earliestSustainedWeek, the earliest Monday from which supply alone could sustain the frequency you asked for.
  • Both fields appear at all 17 slate positions across the same four operations cadenceSummary reaches: POST /v1/projects/{projectId}/availability/package-slate (200), POST /v1/projects/{projectId}/availability/package-options (200), POST /v1/projects/{projectId}/orders/{orderId}/package-bookings (409, inside freshSuggestions), and POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule (200 and 409).
Why there is no message stringA note carries no English at all. You keep your own copy and can localise it; evidence exists so you can name the week, the weekday or the count in your own wording. Weekday numbers everywhere are 0 = Sunday through 6 = Saturday, matching request-level daysOfWeek.What this means for you
  • “Wait a week” and “loosen your days” are opposite calls to action, and telling them apart is the point of the whole field. The supplier-break case reaches you as WEEK_SUPPLY_INSUFFICIENT with openingsInPool: 0 — nothing was open that week, relaxing your own filter cannot help, so “wait a week” is the honest thing to say and advice names which week. WEEK_EXCLUDED_BY_FILTERS is the reverse: the supplier’s working pattern covers days in that week and your daysOfWeek or excludeDates cut them below your target, so “loosen your days” is the move. The candidate pool alone can’t separate them, because your filters were already applied to it; evidence.supplierWorkdays is the pre-filter fact that can. Note it is a fact about the supplier’s working pattern, not a check of that calendar week, so treat “loosen your filter” as the most likely fix rather than a guaranteed one.
  • SUPPLIER_UNAVAILABLE_WEEK is published but not currently emitted by the live engine. It fires only for a supplier who works no weekday at all, and such a supplier yields no availability and therefore no slate for a note to attach to. Keep it in your switch — it is part of the contract — but key your “waiting helps” copy on WEEK_SUPPLY_INSUFFICIENT with openingsInPool: 0 instead.
  • SESSIONS_EXHAUSTED means nothing went wrong — don’t apologise for it. Nine sessions at four a week leaves the last week holding one. That week is short because the package ran out of credits, not because anyone failed. It outranks every supply code, so when it’s emitted for a week no supply code is emitted for that same week. Render it as a plain fact or drop it; surfacing it as a problem makes correct behaviour look broken.
  • advice is advisory and nothing more. It reports that open supply exists from earliestSustainedWeek onward — not that a slate was built for that week, and not that one would be bookable. Holds, capacity, travel time and the cadence rules all still apply. Re-request with a later lookAheadStartDate before promising a client anything.
  • matchNotes explains matchComponents, it doesn’t replace it. Read matchComponents for which criterion missed and matchNotes for why; component on each note points at the criterion it explains. PACKAGE_UNDERFILLED is the one code with no component, because plan size isn’t a scored criterion. That pointer is a guide, not a join key: the week-level codes bucket Monday-anchored calendar weeks while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start, so a note can name a short week for a criterion the component scores as met, and the reverse. Join notes to cadenceSummary.byWeek on weekStart, which shares their bucketing.
  • Slates persisted before this release read back with matchNotes: [] and no advice. Both are provenance — recorded when the slate was built, not re-derived on a rebuild.
Full walkthrough, with both sides of the supplier-versus-filter pair side by side: Suggestions → Why a slate departs from your request.
API

Slate cadence: sessionsPerWeek is gone, cadenceSummary replaces it

Every slate now reports how often it actually runs, week by week, instead of a single averaged rate.BreakingsessionsPerWeek has been removed from the slate object (PackageSlateDto) and replaced by cadenceSummary. This is only the slate response field: the request field of the same name (integer 1–14, the frequency target) and matchComponents.sessionsPerWeek (the 0–1 match ratio) are unchanged and still present.Before:
After:
WhyThe removed field was an average, and an average is the one number that describes none of the weeks. When a supplier takes a week off mid-plan, a nine-session plan lands 1 / 0 / 4 / 4 across four weeks — so the field reported 1.67, and booking UIs rendered “1.67×/week” for a plan that runs at four a week wherever it runs at all. There was no way to recover the real cadence from that number, and no way to see which week was short.cadenceSummary publishes the week-by-week truth instead. peak is the most sessions in any one week and is the number to render. average is byWeek’s sessions divided by byWeek’s length to two decimal places, verifiable straight from the array, counted across the plan’s own span (first session’s week through last session’s) rather than your whole look-ahead window, so a wide window doesn’t dilute it. byWeek is Monday-anchored, ascending and contiguous, and includes weeks holding 0 sessions — the zero week is how you show a client why a plan looks uneven instead of apologising for it. requested echoes the frequency you asked for: your sessionsPerWeek target when you sent one, otherwise the number of weekdays your own FREQ=WEEKLY rule named in BYDAY, and null when the rule wasn’t yours to count (a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays, or a cadence this API synthesised for you).Changed
  • Gating is wider than the field it replaces. sessionsPerWeek was stamped only when cadence relaxation had been requested, so a strict caller could not get a cadence number at all. cadenceSummary is present on every request path, including the default cadenceFlexibility: "NONE". It is absent only for a slate holding no sessions, which has no cadence to describe.
  • The swap spans 17 response positions across four operations, not just the obvious one — every place a slate is published:
    • POST /v1/projects/{projectId}/availability/package-slate — 200: primarySlate, alternates[], partial, cadenceAlternatives[].
    • POST /v1/projects/{projectId}/availability/package-options — 200: the same four inside each entry of data[].
    • POST /v1/projects/{projectId}/orders/{orderId}/package-bookings — 409: the same four inside freshSuggestions.
    • POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule — 200: slate. 409: the same four inside freshSuggestions.
What this means for you
  • Read cadenceSummary.peak wherever you read sessionsPerWeek, and render peak. Don’t substitute average — that reproduces the bug this release fixes.
  • Update the 409 paths too, not just the availability calls. Those bodies fire mid-checkout, when a slot went stale while a client was paying, and their freshSuggestions carries full slates. A client that reads the removed field only on the happy path fails at the worst possible moment.
  • cadenceSummary and matchComponents.sessionsPerWeek count weeks differently, deliberately. cadenceSummary buckets Monday-anchored calendar weeks, so weekStart is always a real Monday and the buckets agree with the maxSessionsPerWeek cap. The matchComponents ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on POST /availability/suppliers. peak: 4 against a target of 4 while that ratio reads below 1 is exactly the supplier-break case above, and both numbers are correct for what they measure — not a bug.
  • Unlike its neighbours, cadenceSummary is not provenance. matchScore and matchComponents are recorded once and never re-derived, but peak, average and byWeek recompute from the slate’s current sessions on every rebuild; only requested is snapshotted. A slate can come back from a reschedule with an unchanged matchScore and a changed cadenceSummary.
  • Slates persisted before this release read back with requested: null; peak, average and byWeek are computed from their stored sessions, so they are correct.
Full explanation, with the two week-bucketings side by side: Suggestions → How often a plan runs.
API

Package discovery, bookable package options, and a wider look-ahead window

Packages are now discoverable and plannable in one call each — and the weekly multi-session package that the engine used to refuse is bookable.New
  • GET /v1/projects/{projectId}/services/{serviceId}/packages — every package on a service, across all of its offerings. This is the call a storefront makes before the client picks an option, when it holds a serviceId and no offeringId — previously there was no endpoint that could answer it. Pass ?status=ACTIVE for just the purchasable bundles. Each package carries its offeringId, so you can join it against the offerings list you already hold. A real service that sells no packages is a 200 with data: []; an unknown serviceId is a 404, so a typo can never masquerade as “no packages”.
  • POST /v1/projects/{projectId}/availability/package-options — every ACTIVE package of a service, each planned against a supplier’s real availability and carrying a ready-to-book slateId. Send a serviceId and a location (locationId, or lat + lng + address); supplierId, timezone, and rrule are optional. Cadence defaults to FREQ=WEEKLY;COUNT={creditCount}, derived per package from its own credit count. It replaces the client-side fan-out of one package-slate call per package, and it’s cheaper than that loop — supplier bundles are read once per offering, not once per package.
Changed
  • The package look-ahead ceiling moved from 31 days to 120 days. The window is still derived from your cadence and the package’s creditCount — only the cap on that derivation changed. A weekly 10-session package spans about 70 days, so it was unbookable under the old 31-day cap and always came back NO_COMPLETE_SLATE; it now plans and books normally, as do weekly 12-packs (~84 days) and biweekly 5-packs (~70 days). A cadence that still needs more than 120 days keeps the existing fail-loud behaviour — NO_COMPLETE_SLATE with a reason naming the exact window required, never a silently truncated slate.
What this means for you
  • If you were listing business models and rendering each row as a package, stop. PACKAGE is a business model — a flag meaning “this service can be sold as packages” — not a sellable bundle, and it carries no creditCount and no pricing. The bundles are what the new package list returns.
  • If you hardcoded a dense weekday rrule (e.g. FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR) purely to squeeze a multi-session package under the 31-day cap, you can drop the workaround and send the cadence you actually sell.
  • Purely additive: no existing route, schema, or DTO changed shape. Every request valid before this release is still valid.
Walkthroughs: Create a package booking with a slate (now starts at finding the package) and Availability and slates for the cadence rules and the new ceiling.
API

Holds, the double-booking guard — and a breaking change to POST /holds

Supplier time is now exclusive at the write layer, and you can hold it while a client pays. A hold works on any supplier time — a single session (no package, no slate), a cherry-picked subset of a package slate, or a whole slate — and POST /holds/{reservationId}/convert turns it into confirmed bookings. Alongside it, every write that claims supplier time now passes through an occupancy guard, so two bookings can never overlap on the same supplier.BreakingEach entry in intervals[] on POST /v1/projects/{projectId}/holds now mirrors the POST /bookings location contract exactly. bookingTz and locationType are required, and locationType decides which of locationId / latitude / longitude / address must come with them.Before:
After:
An interval without bookingTz or locationType is now a 400 VALIDATION_ERROR. This applies to the heartbeat too — extending a hold re-sends the same intervals, so they must carry the same fields.WhyConvert rebuilds the booking from the reservation alone — never by re-reading a slate that may have expired while the client was paying. A hold that carried only a locationId could not say whether that id was a Location (loc_…) or a supplier travel zone (stz_…), so converting a mobile / in-home hold failed with 404 Location stz_… not found, and a TRAVEL_ZONE booking’s mandatory coordinates and address were never held at all. Travel-zone checkouts now work end to end.New
  • POST /holds — hold supplier time with intervals (single session or any explicit time), slateId (a whole package slate), or slotIds (a subset). All-or-nothing, in one transaction. Pass reservationId to extend an existing hold: the checkout heartbeat pushes heldUntil out and returns the same reservationId instead of minting a second hold.
  • POST /holds/{reservationId}/convert — one idempotent endpoint for both shapes; it branches on the order item’s skuType (SINGLE_SESSION books the one held interval; PACKAGE books every held interval and draws down credits). Safe to call straight from a Stripe webhook. (The public API sends no webhooks of its own; see Hold slots during checkout for when to convert.)
  • GET /holds/{reservationId} and the 201 from POST /holds now echo the full interval shape — bookingTz, locationType, locationId, latitude, longitude, address — so you can verify exactly what convert will build.
  • POST /holds/{reservationId}/release — free the time immediately when a checkout is abandoned. Idempotent, never an error.
  • Occupancy guard — 409 SLOT_HELD / SLOT_BOOKED on any write that collides with a live claim. The body names the blocking reservationId or bookingId and tells you what to do with it.
  • Conflict responses now carry the full error envelope. Every 409 conflict and hold-lifecycle body (SLOT_HELD, SLOT_BOOKED, HOLD_EXPIRED, RESERVATION_*, and the slate codes) now includes statusCode and requestId alongside code and message, matching every other error. Purely additive — nothing was removed or renamed. If you were branching on the HTTP status because body.statusCode was missing on these, you no longer have to. See Errors.
What this means for you
  • If you build intervals by hand, add bookingTz and locationType before your next deploy — including in your heartbeat call.
  • If you hold by slateId or slotIds, nothing changes: the slate’s slots already carry every location field, and the hold now copies them onto the reservation for you.
  • If you hold time, you must convert it — POST /bookings and POST /orders/{orderId}/package-bookings will not consume a hold, not even your own, and return 409 SLOT_HELD naming your own reservationId.
Full walkthrough, a travel-zone worked example, and a status/code troubleshooting table: Hold slots during checkout. The guard itself: Concurrency.
API

Catalog management endpoints

You can now manage your service catalog directly through the API. This release adds full create, read, update, and delete (CRUD) support for services, their offerings, and the business models attached to them — so you can build, sync, and automate catalogs without using the dashboard.New
  • Services — Create, list, retrieve, update, soft-delete, and toggle status for services on a project. See Services.
  • Offerings — Add offerings to a service, list them, fetch a single offering, update or soft-delete it, and change its status.
  • Business models — Attach pricing/business models to a service, list them, update them, and toggle active status.
What this means for you
  • Sync your catalog from an external system of record on a schedule.
  • Build admin tooling that lives outside the MarketBox dashboard.
  • Programmatically enable or disable offerings as inventory and availability shift.
All new endpoints are project-scoped and follow the existing authentication, pagination, and error conventions. Browse the full list under API reference → Endpoints.