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.
- 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.
- Key prefixes. Examples showed keys starting
mb_live_andmb_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 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.FixedPOST …/orders/{orderId}/payment-intentlists409 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 theclientSecretfrom the latest call. See Accept payments with Stripe.POST …/orders/{orderId}/transactionslists422 ORDER_NOT_PAYABLE: aSUCCEEDEDPAYMENT, or aCOMPadjustment, on aCANCELLEDorder.disputeIdanddisputeStatuson transactions are described, including what eachdisputeStatusvalue means.NOT_SELLABLEon bookings, hold conversion and package bookings — the reference said a service that isn’tLIVEis refused. On these routes only an offering that isn’tACTIVEis refused, because they book an order item already bought. Both package-bookings routes now list the code.START_END_LOCATIONS_DISABLEDandSETTING_NOT_DELEGATEDare in the list of error codes.
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’tACTIVE, is no longer sold.POST …/ordersandPOST …/orders/{orderId}/itemsanswer422 NOT_SELLABLE, for example “Service srv_… is DRAFT and is not sold; only LIVE services take new bookings and orders”. A service that wasn’tLIVEused to be accepted. An inactive offering on an order item used to be400. Bookings, hold conversion and package sessions against an order item already bought stay bookable after the service stops beingLIVE, but answer422 NOT_SELLABLEonce the offering isn’tACTIVE. - A
PACKAGEline for aDRAFTorARCHIVEDpackage onPOST …/ordersis422 PACKAGE_NOT_ACTIVE. - Your key can’t cancel a booking that has taken place.
POST …/bookings/{bookingId}/statuswithCANCELLEDon anAWAITING_CONFIRMATIONbooking is400. Settle it instead, withCOMPLETEDor a no-show. DELETE …/bookings/{bookingId}is a cancel first. A booking your key can’t cancel (AWAITING_CONFIRMATION,COMPLETED, a no-show) is422 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’tSCHEDULEDorSTARTEDis422 BOOKING_NOT_AMENDABLE. Its other fields can still be edited. - An attendance report filed with your key now settles the booking. A
SUPPLIERreport onPOST …/bookings/{bookingId}/reportsmoves the booking as the supplier’s own report does: attended →COMPLETED(orDISPUTEDwhen the client reported not attending), did not attend →SUPPLIER_NO_SHOW. ACLIENT“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 aSUPPLIERreport on a settled booking is422 BOOKING_NOT_REPORTABLE. It was422 UNPROCESSABLE_ENTITY, and a report never changed the status. - Participants only join an open booking. Registering a participant on a booking that isn’t
SCHEDULEDorSTARTED, or checking one in on a booking that is settled, disputed or cancelled, is422 BOOKING_NOT_OPEN_FOR_PARTICIPANTS. AnAWAITING_CONFIRMATIONbooking still takes a check-in. - A cancelled order takes no new money. A
PAYMENTorCOMPrecorded on aCANCELLEDorder is422 ORDER_NOT_PAYABLE, “Order ord_… is CANCELLED and cannot take a payment”. AREFUNDis still recorded. - One card payment at a time.
POST …/orders/{orderId}/payment-intentwhile a card payment on the order is in progress is409 PAYMENT_IN_FLIGHT. - The status routes check the id.
POST …/offerings/{offeringId}/statuswith an unknown or deleted offering is404 NOT_FOUND, “Offering not found”. It used to write a stub.POST …/business-models/{businessModelId}/statuswith an unknown id is404, “Business model not found”.
bufferBeforeStartMinuteson services — 0 to 120, default 0, on service responses and onPOST …/servicesandPUT …/services/{serviceId}. Suggested times leave that gap before a job of the service, online jobs included. It is never busy time, never part oftravelTimeMins, and never refuses a booking made at a specific time.- Start and end locations on supplier-plane schedules —
startLocation,endLocation,driveTiming,maxTravelOnStartDriveandmaxTravelOnEndDriveon…/suppliers/me/schedules. All are nullable, andnulluses the project’s default. A write is422 START_END_LOCATIONS_DISABLEDwhile the project has the feature off, and422 SETTING_NOT_DELEGATEDfor a setting the project keeps. Sendingnullor the stored value is never refused. The feature is off for every project until it is turned on. disputeIdanddisputeStatuson transactions — set when a card payment is disputed. Read-only.PAYMENT_NEEDS_REVIEWin the alertkindenum — withpayload.paymentReason. It is a staff alert, soGET …/suppliers/me/alertsdoesn’t return it to a supplier. Typed clients should still accept the value. See Supplier portal: insights and alerts.
- 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
travelTimeMinsreports the drive with traffic. A supplier whose bookings can’t be routed shows up inerrors[]instead of failing the whole search. POST …/availability/time-slots—metrics.totalTravelTimeRequestsMadecounts 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-intentbillstotal − amountPaid − amountComped. An order paid or comped in full is400.- A delivered package session cancelled without a
creditTreatmentisFORFEIT. A session still to come is stillRETURN. POST …/holds/{reservationId}/releasecan answer409 OCCUPANCY_CONTENTION. The hold is stillHELD. Retry the release.- Supplier photo and
activewrites can answer409 CONFLICTwhen another request changed the same record meanwhile. Read the supplier again and retry. POST …/clients/memakes an existing member a client. An admin or supplier who signs in on your booking site gains theCLIENTrole.- Deleting a supplier-plane schedule keeps a travel zone another schedule uses.
GET …/orderswithpaymentMethodkeeps settled orders that were later cancelled, with theirstatus.
- Handle the new codes without retrying.
NOT_SELLABLE,PACKAGE_NOT_ACTIVE,BOOKING_NOT_DELETABLE,BOOKING_NOT_AMENDABLE,BOOKING_NOT_REPORTABLE,BOOKING_NOT_OPEN_FOR_PARTICIPANTSandORDER_NOT_PAYABLEwon’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.
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 as500 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 …/holdswithslateIdorslotIdspast itsresolvableUntil(24 hours after it was planned) answers409 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 heldintervalsis 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/meroutes now name why they refuse, where they used to answer403 FORBIDDENor404 NOT_FOUND:403 NOT_A_MEMBER, “You are not a member of this project.”: no membership of the project. It wasFORBIDDEN, “No active membership on this project”.403 MEMBERSHIP_INACTIVE, “Your access to this project has ended.”: every role was removed. It wasFORBIDDEN, “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 wasFORBIDDEN, “Insufficient permissions for this action”.404 NO_SUPPLIER_ROLE: the permission passed, but the person acts under noSUPPLIERrole. It wasNOT_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 holdsSUPPLIER, but no single supplier record is linked. It wasNOT_FOUND, “No supplier record for current user”.
404 NOT_FOUND. “User account not found. Complete registration first.” is still403 FORBIDDEN. The client plane (/clients/me) is unchanged. See Supplier portal → Refusals.
-
GET /v1/projects/{projectId}/suppliers/me/access— takes the API key and the person’s access token, and always answers200with{ allowed, reasonCode, message, supplierId, roles, membershipStatus }.reasonCodeis one of seven codes:SUPPLIER_ACTIVE, the only one withallowed: true;SUPPLIER_RECORD_INACTIVE,NO_ACCOUNT,NOT_A_MEMBER,MEMBERSHIP_INACTIVE,NO_SUPPLIER_ROLEandSUPPLIER_NOT_LINKED.
X-MB-Acting-Role. Wrong credentials still fail with401or403. See Check access first. -
accessonGET /v1/projects/{projectId}/suppliers/{supplierId}—userId,invitationStatus,roles(empty unless the membership isACTIVE),membershipStatus(ACTIVE,INACTIVEornull) andaccessEndedAt.accessEndedAtis set when the person is unlinked, and isnullfor removals made before this release.GET /suppliersandPOST /availability/suppliersdon’t carry it. See Removed, or never a supplier. -
conflicts[].supplierIdon409 SLOT_HELD/SLOT_BOOKED: the supplier whose calendar is blocked,nullwhen unknown. It was in the schema but never sent.
- A stale availability
versionis409 VERSION_CONFLICT, not409 CONFLICT. This coversPATCHon…/suppliers/me/schedules/{scheduleId},…/blocked-times/{blockedTimeId}and…/travel-zones/{travelZoneId}. It also covers another write landing during aDELETEof any of them. The status is still409. An overlappingACTIVEschedule stays409 CONFLICT, so branch oncode. See Supplier portal → Set working hours. - Acting as
CLIENTnever serves a supplier’s bookings. A request to the supplier plane’s bookings routes withX-MB-Acting-Role: CLIENTis404 NO_SUPPLIER_ROLE, even when the person has a linked supplier record. It used to answer200. 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 aPENDINGorSUCCEEDEDpayment or refund, answers409 ORDER_NOT_DELETABLE, and nothing changes. Cancel it withPOST …/orders/{orderId}/statusinstead. 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: truemakes the bookingDISPUTED, notCOMPLETED, when a client report already saysattended: false. A client’sattended: falsewithin 24 hours of a booking becomingCOMPLETEDalso makes itDISPUTED, 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.
- Booking writes return 4xx instead of 500.
POST …/bookings,PATCH …/bookings/{bookingId},POST …/holds/{reservationId}/convertand both package-bookings routes now answer:409 SLOT_HELD/SLOT_BOOKEDwhen a reschedule’s new time is taken, withconflicts[]andhint;409 OCCUPANCY_CONTENTIONwhen the supplier’s calendar is under heavy writes;409 VERSION_CONFLICTwhen the booking changed since you read it;404 NOT_FOUNDfor an unknown location, and400 BAD_REQUESTfor one of the wrong type or another supplier’s travel zone;422 UNPROCESSABLE_ENTITYfor aPHYSICALLocation without coordinates.
- Converting a
PHYSICALhold works. It used to fail with a500. - Converting a package hold answers package refusals with their own codes, as
POST …/package-bookingsdoes, instead of500:409 ORDER_ITEM_QUANTITY_UNAVAILABLE,409 PACKAGE_EXPIRED,422 PACKAGE_SLATE_TOO_LARGE_FOR_ATOMICand422 BEST_EFFORT_NOT_ENABLED. Nothing is booked in any of them. - An offering’s
holdDurationMinsOverrideis 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 noholdDurationMins.nullclears it. NOT_A_PACKAGE_SERVICEis listed with the other error codes. The API already returned it (400) for aPACKAGEbooking or convert whose service has no activePACKAGEbusiness model.POST …/orders/{orderId}/itemswithskuType: "PACKAGE"is400 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 listsPACKAGEfor this route.POST …/availability/searchandPOST …/availability/supplierswith an unknown id are404 NOT_FOUND, naming it. For an offering, the message is “Service offering off_… not found on service srv_…”. For alocationIdsent withoutlat/lng, it is “Location loc_… not found”. A search location with no coordinates is400 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”) andPUT …/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}) is409 OCCUPANCY_CONTENTION, not500. - An offering with no
DEFAULTprice rule is422 OFFERING_NOT_PRICEDon every write that prices it, not500. PATCH …/suppliers/merefuses unknownserviceIdsandskillIdswith400 BAD_REQUESTnaming 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 staySCHEDULED. 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 showedoffr_.
- Hold only fresh slates. On
409 SUGGESTION_EXPIREDfromPOST …/holds, plan a new slate rather than retrying. - Match the new supplier-plane codes. If your portal branches on
FORBIDDENorNOT_FOUNDfrom/suppliers/meto detect lost access, also branch onNOT_A_MEMBER,MEMBERSHIP_INACTIVE,NO_SUPPLIER_ROLEandSUPPLIER_NOT_LINKED. - Check supplier access on sign-in. Call
GET /suppliers/me/accesswhen the person signs in and when your portal renews its session. Use the plane only whenallowedistrue; otherwise showmessage. Don’t sendX-MB-Acting-Rolefrom 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 andaccessEndedAtis set. - Branch on
VERSION_CONFLICTin your supplier portal. On it, re-read the row and retry. Show an overlap message only onCONFLICT. - Cancel orders instead of deleting them. Keep delete for an order raised in error that books nothing and took no money.
- Don’t treat
COMPLETEDas 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
DISPUTEDwherever 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.
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 forquantityReturned 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-bookingsused to accept sessions of any offering. Every service line of every session must now match the order item’sserviceIdandofferingId, or the call is400 ORDER_ITEM_SERVICE_MISMATCHand nothing is booked. This applies toslateId,slotIdsandsessions. - A
CANCELLEDorder plans and books nothing.POST …/availability/package-slate(from a credit),POST …/orders/{orderId}/package-bookings,POST …/bookingsandPOST …/holds/{reservationId}/convertanswer409 ORDER_CANCELLEDfor an order that isCANCELLED. Convert refuses even a hold that already converted.DRAFT,PENDINGandPAIDorders book as before: payment is still not a gate.
- A same-key retry replays after the credits ran out. Retrying
POST …/package-bookingswith the sameidempotencyKeyand body now returns the stored201, even when the first call used the last credits. It used to be400 ORDER_ITEM_QUANTITY_UNAVAILABLE. A replay sends no second confirmation email. AslateIdorslotIdsretry 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’s400or404. - Stale-slate
freshSuggestionsare planned from the order item you are booking — its remaining sessions, offering and expiry — so they can be booked on it.nullwhen the item has nothing left to plan. DELETE …/suppliers/{supplierId}can answer409 CONFLICTwhen the supplier’s sign-in changes during the delete. Try again.
- Plan a slate from a credit.
POST …/availability/package-slatetakesorderId+orderItemIdinstead ofpackageId. It plans the credit’s remaining sessions in its own offering, ends at itsexpiresAt, and works after the package was deleted. Send exactly one source. Add an optionalclientIdto 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 is409 ORDER_ITEM_QUANTITY_UNAVAILABLE,409 PACKAGE_EXPIRED,409 ORDER_CANCELLED,400 NOT_A_PACKAGE_ITEM,400 INVALID_ORDER_REFERENCEor404 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 a404identical to a missing one. A creditGET …/clients/me/creditswould not list is409 CREDIT_NOT_BOOKABLE. Booking byslateIdorslotIdsneeds a slate planned from that credit.quantityReturnedonGET …/clients/me/credits— the sessions cancellations have returned to the credit, ever. Already counted inquantityRemaining; 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-allandPOST …/suppliers/me/alerts/{alertId}/read— the dashboard’s bell, from the same inbox. A cursor from anotherfilteris400 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
bookingIdwhen the email is about one booking.
- 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_CANCELLEDas final. Don’t retry; offer a new order. - Keep the same
idempotencyKeywhen you retry a booking, and a fresh one for each new attempt. - Don’t add
quantityReturnedtoquantityRemaining. It is already included.
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 …/eventsnow needs the*capability. A key with no capabilities ticked, or only Site events, gets403 CAPABILITY_NOT_GRANTEDbefore anything else is read. Keys minted before capabilities existed are treated as*and keep working.
- End-user routes require an
ACTIVEmembership. Every/clients/meroute except onboarding, and every/suppliers/meroute, checks the person’s membership of the project on each request. No membership is403 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/meanswers403 MEMBERSHIP_INACTIVEfor 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.
- 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 codesPARTICIPANT_ACTION_DISABLED,BOOKING_NOT_SCHEDULED,NOTICE_WINDOW_PASSED,NEW_START_INSIDE_NOTICE_WINDOW,SLOT_UNAVAILABLEandSLOT_UNVERIFIABLE. Attendance reports addBOOKING_ALREADY_SETTLEDandBOOKING_NOT_REPORTABLE. The profile addsFIELD_NOT_SELF_EDITABLE; insights addINSIGHTS_DISABLED. GET …/locationsandGET …/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 theskillsavailability filter.- Site events.
POST …/events(from your server, needs theevents:writecapability) andPOST …/events/beacon(from the browser, with a publishable key and an origin allowlist). New codesPAYLOAD_TOO_LARGE(413),RATE_LIMITED(429) andSERVICE_UNAVAILABLE(503). searchIdandpositionon every search.POST …/availability/search,/suppliers,/package-slate,/package-options,/time-slotsandGET …/suppliersreturn asearchId(also theX-MB-Search-Idheader), and rank each supplier or slate with a 0-basedposition.POST …/availability/searchalso returnssuppliers. Two optional request headers,X-MB-Session-KeyandX-MB-Client-Kind, tag a search for insights.engineEnabledonPOST …/availability/search.falsemeans the project’s scheduling engine is off, sotimeSlotsis empty because it wasn’t computed.attributiononPOST …/orders— thesearchId,sessionKeyandsurfacethe purchase came from. Copied onto every booking the order funds.participantSettingson services — what suppliers and clients may do with, and see on, bookings of the service. Replaced whole onPUT.X-MB-Acting-Roleis checked. An end-user request naming a role the person doesn’t hold is403 ACTING_ROLE_NOT_HELD.
- 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/meand/suppliers/mecall. Don’t forward the ID token, or a dashboard token. - Handle
403on end-user routes as “access removed”. Show the person how to contact the business, not a retry. - Report what you draw. Send
search.renderedwith each search’ssearchId. A search you don’t report counts for nothing in suppliers’ insights. - Check
engineEnabledbefore telling a client nobody is free.
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.BreakingtaxonPATCH …/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 is400 TAX_MISMATCH, and nothing is written. The same code is returned when the order has lines in a different currency. Omittax.
- Package lines are taxed. A
PACKAGEline 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.
taxExemptReasonon order items — why a line carries no tax:NO_RATE,NOT_TAXABLE,ZERO_RATE,MIGRATED_V1orPACKAGE_EXEMPT_LEGACY. Absent when the line is taxed at a positive rate, and on lines written before the field existed.
- Stop sending
taxonPATCH …/orders/{orderId}. Handle400 TAX_MISMATCHif 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 onskuType, to explain a zero tax.
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 becomesPAID 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.BreakingPAIDcan no longer be requested.POST …/orders/{orderId}/statusanswers aPAIDtarget with409 ORDER_NOT_SETTLED. An order becomesPAIDwhen its ledger covers its total: record cash, external or comp money withPOST …/orders/{orderId}/transactions, and let the Stripe webhook settle cards. APAIDrequest is refused with that409from every status, includingPENDING.NO_SHOWcan no longer be set. Sending it toPOST …/bookings/{bookingId}/statusis a400. SendCLIENT_NO_SHOWorSUPPLIER_NO_SHOW. Bookings recorded before the split still carryNO_SHOWon every read, and will indefinitely.- An order line the service is not sold as is refused.
POST …/ordersandPOST …/orders/{orderId}/itemsreturn422 SERVICE_NOT_SOLD_ASwhen the service has no active rate of the line’s kind, such as aSINGLE_SESSIONline with no activeSINGLE_BOOKINGrate. Such lines used to be written with no rate attached, and so without its fees.
firstNameandlastNameonPOST …/clients/me, besidephone. Each field you send overwrites the stored value and is copied to the client’s record in Stripe. Blank ornullmeans not sent. At most 80 characters after trimming.PATCH …/clients/me— change the signed-in client’sfirstName,lastNameorphone. Names can be changed but not cleared;phone: nullclears the phone. Call it beforePOST /ordersso emails use the new name.creditTreatmentonPOST …/bookings/{bookingId}/status, withCANCELLEDonly.RETURN(the default for a package session) puts the session back on the order item and records aCREDIT_REVERSAL.FORFEITkeeps it spent. Sending it for a booking with no package credit is422 NO_SESSION_CREDIT, and nothing is cancelled.- Three listing modes on
GET …/orders.statusis no longer required. Sendstatus, orpaymentMethod(withstartSettledAt/endSettledAt), or neither to list every order (withstartCreatedAt/endCreatedAt). Mixing modes is a400. The no-filter mode is missing orders created before this release until a backfill runs. reasonandidempotencyKeyonPOST …/orders/{orderId}/transactions.reasonis required withsource: "COMP". The sameidempotencyKeyon the same order returns the first row as200withreplayed: trueinstead of recording the money twice. A first recording is201withreplayed: false.skillsonPOST …/availability/search— supplier skill ids a supplier must all hold to be considered.bio: nullonPUT …/suppliers/{supplierId}clears the bio. Omitting it still keeps it.- New response fields.
- Order:
paymentMethod,settledAt,amountComped. - Order item:
priceSource(RULEorMANUAL). - Booking:
creditTreatment,cancellationInitiatedBy,cancellationReasonCode,durationOverrideMinutes,durationOverrideReason. - Transaction:
channel,reason, and theCREDIT_REVERSALkind. - Client address:
latitude,longitude.
- Order:
- 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
clientIdorsupplierIdfrom another project is a404with 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
businessModelTypethe order item is not sold as is400 ORDER_ITEM_BUSINESS_MODEL_MISMATCH. - Cancellation emails report what happened to the client’s session credit, and do not include the
cancellationReasontext.
- Stop setting orders to
PAID. Record the payment instead, and readstatusback. - Send an
idempotencyKeyon every manual transaction you might retry, and branch onreplayed. - Send
reasonwith every comp. - Replace
NO_SHOWin requests withCLIENT_NO_SHOWorSUPPLIER_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
firstNameandlastNameon onboarding, especially for email-and-password sign-ups. - Handle
422 SERVICE_NOT_SOLD_ASon 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
statuswhen you need every order. - Tell clients at checkout that their card will be saved.
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 thetimezone 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.NewtimeSlotStartUtcon every slot intimeSlots[]andopenSlots[]fromPOST /v1/projects/{projectId}/availability/searchand…/time-slots. The slot start in UTC, alwaysZ-suffixed, always the same instant astimeSlotDateAndTime. Prefer it as the booking anchor. Package slates derive each session’sbookingStartUtcfrom it. This is a response shape:
supplierZonesonPOST /v1/projects/{projectId}/availability/search— each returned supplier’s own profile zone, keyed bysupplierId. The recommendedbookingTzfor 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 thestatusfilter of the three list endpoints.AWAITING_CONFIRMATIONandDISPUTEDare entered by the platform after a session ends and can only be observed.CLIENT_NO_SHOW/SUPPLIER_NO_SHOWreplaceNO_SHOW, which no longer said which side was absent. See Bookings → The booking lifecycle. statusUpdatedByandstatusUpdatedByCapacityon 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 theAPIcapacity.lookAheadStartDateaccepts aZinstant on recurring…/availability/search. AZsuffix and a numeric offset are equally valid there; the “must carry a numeric offset”400is gone from that endpoint.…/package-slateand…/package-optionsstill require a numeric offset.
- Corrected slot times.
timeSlotDateAndTimekeeps its name and now renders the slot instant in the responsetimezonewith that zone’s offset at that instant, so digits and offset always agree and the string always parses totimeSlotStartUtc. If your code parses the whole string you will simply see correct times. If it reads only the clock digits, passtimezoneexplicitly to keep receiving that zone’s clock. On…/availability/suppliers,startUtcis now the engine instant verbatim andstartLocalis rendered in the responsetimezone. - 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-slateand…/package-options, and the bookings created from them, carrybookingTzequal to the session’s home zone — the service location’s zone, else the supplier’s, else the project default — instead of thetimezoneyou sent.bookingStartUtcis 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 requesttimezone, so a midnight-UTClookAheadStartDateagainst a zone west of Greenwich anchors one day earlier than before. A value that does not parse is a400in the standard error envelope rather than a raw validation payload. POST …/bookings/{bookingId}/statusrequest enum is narrower than the response.SCHEDULEDandDISPUTEDare no longer advertised as settable — they were always rejected.NO_SHOWis deprecated, still accepted, and will be removed in a later version (it was: since the September 23, 2026 release, sendingNO_SHOWis a400). An API key can request every transition an operator can except resolving a dispute or reversing a settled booking back toAWAITING_CONFIRMATION. A transition the booking cannot make is a400naming the booking’s current status.- Supplier
timezonedrives the daily agenda email. It is used verbatim as the schedule zone for the supplier’s 07:00 agenda; unset inherits the project default.
/ (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/TorontoorAmerica/New_York,PST→America/Los_Angeles,IST→Asia/Kolkata. - Prefer
timeSlotStartUtcfor anything that computes with a slot time; treattimeSlotDateAndTimeas a display convenience. - If you rely on the clock digits in
timeSlotDateAndTime, passtimezoneexplicitly 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,timeSlotStartUtcandsupplierZones. HandleAWAITING_CONFIRMATIONandDISPUTEDas in-flight, not failed. - Stop sending
NO_SHOW. SendCLIENT_NO_SHOWorSUPPLIER_NO_SHOWinstead. - A “no
Z” guard onlookAheadStartDateis now only needed for the package endpoints, not for recurring search.
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.NewservedRegionson every supplier response — the rows ofGET /v1/projects/{projectId}/suppliers, the detail endpoint, the create, update, services, skills and avatar responses, anddata[].supplieronPOST /v1/projects/{projectId}/availability/suppliers. Sorted slug region paths at every hierarchy level — the same set thecountry/state/cityfilter 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+lngonGET /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 withservices/skills. Exclusive withcountry/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=Scarboroughandcity=Toronto. Previously only the municipality matched. localeonPOST /v1/projects/{projectId}/orders— optional, the language the buyer completed the purchase in. Normalized to canonical BCP-47 (en-us→en-US); malformed is a400 VALIDATION_ERROR. Immutable on the order, snapshotted aslocaleonto every booking the order funds (never accepted onPOST /bookings), and saved as the client’sdefaultLocale(latest booking wins). Suppliers gain a staff-setdefaultLocaleon create and update (nullclears on update) and in every response — distinct from the existinglanguagesand derivedlocales.- Three review-URL tokens beside
{bookingId}:{bookingLocale},{clientLocale},{supplierLocale}. Each falls back only to the project default, never to another token. See Emails.
- One schedule-liveness rule. A schedule is live when it is
ACTIVE, not deleted, and itsendDatehas not passed in the schedule’s own timezone.locations[], the region filter,servedRegionsand the detail endpoint’savailability.schedulesall use it. Before this releaselocations[]andavailability.schedulesignoredendDate, so a supplier whose only schedule had ended still advertised a travel zone the filter no longer matched — in one real project, 80 records carriedcountry: "CA"on their profile while?country=CAreturned 49 rows.locations[]andavailability.schedulescan now be shorter, including[], for suppliers you saw as bookable yesterday. - Supplier
phoneis validated and normalized. Create and update accept E.164 or a national NANP number and store E.164 (+14165550134); anything unparseable is a400 VALIDATION_ERROR. Update acceptsnullto clear. Rows written before this release keep whatever was typed until next edited.
- Regenerate response types.
servedRegions: string[]is required everywhere a supplier is returned. - Stop deriving “does this supplier serve Toronto?” from profile
city/state. ReadservedRegions, or use the filter — they agree by construction.locations[]is per-request;servedRegionsis swept daily and can lag a schedule’sendDateby 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 itsendDateno longer contributes.schedules: []on the detail endpoint now really means “cannot be booked”. - Send
localeon 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.
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.NewmatchNoteson every slate (PackageSlateDto) — an array of{ code, component, weekStart?, evidence }objects. Always present: nothing departed from your request means[], not a missing key, so.lengthis safe to read without a null check. It is not gated onmatchScore— aDIRECT_FILLslate and aPARTIALslate can both score1and still carry notes, and those are exactly the slates worth captioning.
- Nine codes, each with its own evidence shape, discriminated on
codeso 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. adviceon every slate, optional — a forward-looking hint namingearliestSustainedWeek, 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
cadenceSummaryreaches: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, insidefreshSuggestions), andPOST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule(200and409).
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_INSUFFICIENTwithopeningsInPool: 0— nothing was open that week, relaxing your own filter cannot help, so “wait a week” is the honest thing to say andadvicenames which week.WEEK_EXCLUDED_BY_FILTERSis the reverse: the supplier’s working pattern covers days in that week and yourdaysOfWeekorexcludeDatescut 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.supplierWorkdaysis 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_WEEKis 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 yourswitch— it is part of the contract — but key your “waiting helps” copy onWEEK_SUPPLY_INSUFFICIENTwithopeningsInPool: 0instead.SESSIONS_EXHAUSTEDmeans 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.adviceis advisory and nothing more. It reports that open supply exists fromearliestSustainedWeekonward — 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 laterlookAheadStartDatebefore promising a client anything.matchNotesexplainsmatchComponents, it doesn’t replace it. ReadmatchComponentsfor which criterion missed andmatchNotesfor why;componenton each note points at the criterion it explains.PACKAGE_UNDERFILLEDis the one code with nocomponent, 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 whilematchComponents.sessionsPerWeekbuckets 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 tocadenceSummary.byWeekonweekStart, which shares their bucketing.- Slates persisted before this release read back with
matchNotes: []and noadvice. Both are provenance — recorded when the slate was built, not re-derived on a rebuild.
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: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.
sessionsPerWeekwas stamped only when cadence relaxation had been requested, so a strict caller could not get a cadence number at all.cadenceSummaryis present on every request path, including the defaultcadenceFlexibility: "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 ofdata[].POST /v1/projects/{projectId}/orders/{orderId}/package-bookings—409: the same four insidefreshSuggestions.POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule—200:slate.409: the same four insidefreshSuggestions.
- Read
cadenceSummary.peakwherever you readsessionsPerWeek, and renderpeak. Don’t substituteaverage— that reproduces the bug this release fixes. - Update the
409paths too, not just the availability calls. Those bodies fire mid-checkout, when a slot went stale while a client was paying, and theirfreshSuggestionscarries full slates. A client that reads the removed field only on the happy path fails at the worst possible moment. cadenceSummaryandmatchComponents.sessionsPerWeekcount weeks differently, deliberately.cadenceSummarybuckets Monday-anchored calendar weeks, soweekStartis always a real Monday and the buckets agree with themaxSessionsPerWeekcap. ThematchComponentsratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable withavailabilityMatchonPOST /availability/suppliers.peak: 4against a target of4while that ratio reads below1is exactly the supplier-break case above, and both numbers are correct for what they measure — not a bug.- Unlike its neighbours,
cadenceSummaryis not provenance.matchScoreandmatchComponentsare recorded once and never re-derived, butpeak,averageandbyWeekrecompute from the slate’s current sessions on every rebuild; onlyrequestedis snapshotted. A slate can come back from a reschedule with an unchangedmatchScoreand a changedcadenceSummary. - Slates persisted before this release read back with
requested: null;peak,averageandbyWeekare computed from their stored sessions, so they are correct.
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.NewGET /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 aserviceIdand noofferingId— previously there was no endpoint that could answer it. Pass?status=ACTIVEfor just the purchasable bundles. Each package carries itsofferingId, so you can join it against the offerings list you already hold. A real service that sells no packages is a200withdata: []; an unknownserviceIdis a404, 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-bookslateId. Send aserviceIdand a location (locationId, orlat+lng+address);supplierId,timezone, andrruleare optional. Cadence defaults toFREQ=WEEKLY;COUNT={creditCount}, derived per package from its own credit count. It replaces the client-side fan-out of onepackage-slatecall per package, and it’s cheaper than that loop — supplier bundles are read once per offering, not once per package.
- 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 backNO_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_SLATEwith areasonnaming the exact window required, never a silently truncated slate.
- If you were listing business models and rendering each row as a package, stop.
PACKAGEis a business model — a flag meaning “this service can be sold as packages” — not a sellable bundle, and it carries nocreditCountand nopricing. 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.
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: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.NewPOST /holds— hold supplier time withintervals(single session or any explicit time),slateId(a whole package slate), orslotIds(a subset). All-or-nothing, in one transaction. PassreservationIdto extend an existing hold: the checkout heartbeat pushesheldUntilout and returns the samereservationIdinstead of minting a second hold.POST /holds/{reservationId}/convert— one idempotent endpoint for both shapes; it branches on the order item’sskuType(SINGLE_SESSIONbooks the one held interval;PACKAGEbooks 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 the201fromPOST /holdsnow 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_BOOKEDon any write that collides with a live claim. The body names the blockingreservationIdorbookingIdand tells you what to do with it. - Conflict responses now carry the full error envelope. Every
409conflict and hold-lifecycle body (SLOT_HELD,SLOT_BOOKED,HOLD_EXPIRED,RESERVATION_*, and the slate codes) now includesstatusCodeandrequestIdalongsidecodeandmessage, matching every other error. Purely additive — nothing was removed or renamed. If you were branching on the HTTP status becausebody.statusCodewas missing on these, you no longer have to. See Errors.
- If you build
intervalsby hand, addbookingTzandlocationTypebefore your next deploy — including in your heartbeat call. - If you hold by
slateIdorslotIds, 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 /bookingsandPOST /orders/{orderId}/package-bookingswill not consume a hold, not even your own, and return409 SLOT_HELDnaming your ownreservationId.
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.
- 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.