- Service: the sellable thing. It starts
DRAFT. - Business models: how the service is sold (single sessions, packages).
- Offerings: the bookable variants, each with a duration and a price.
- Packages: prepaid bundles of sessions of one offering, if you sell them.
- Publish the service:
LIVE. - Suppliers: who delivers it, linked to the service, with a photo.
- Hours: the supplier’s schedule. An API key can’t write these.
x-api-key header. Paths in the prose are
relative to the project: POST /services is
POST /v1/projects/{projectId}/services. Ids come back on each create response:
keep them, because the next step needs them.
Each object has a reference page with every field and rule:
Services and offerings covers services, business
models and offerings, and Packages covers packages.
1
Create the service
name and description are localized: one string per language, keyed by
language code. The 201 returns the service in data, with its serviceId
and status: "DRAFT". A new service is always DRAFT, whatever you send.Names are unique in a project, per language:taxSettings is the service’s own tax, used when no price rule sets tax. See
How tax is computed.bufferBeforeStartMinutes, 0 to 120, is the time a supplier needs free
before the service starts. It defaults to 0. Suggested times respect it, but
it never blocks a booking. See
Buffer before start.A service has no externalId. Store the serviceId against your own record.2
Add the business models
A business model says how the service is sold. An order line needs one that
matches it:Post a second one with Business models can also carry booking fees. See
Service fees.
"type": "PACKAGE" and
"paymentOptions": ["PAY_FULL_PRICE_WHILE_PURCHASING"] to sell packages. You
can also send both inline, as businessModels, on the service create.A business model is active when it’s created. Turn one off or on with
POST /services/{serviceId}/business-models/{businessModelId}/status and
{ "active": false }. It’s a boolean, not a status.A service with no active SINGLE_BOOKING model creates, publishes and lists
fine. It fails only when a client orders it:3
Create the offerings
An offering is what a client actually books: a duration and a price.An offering is
- Amounts are integer minor units.
4500is $45.00. A decimal is a400. pricingneeds exactly oneDEFAULTrule. It’s the price wherever no more specific rule matches. AddCOUNTRY,STATEandPOSTALrules for regional prices. See Regional pricing.ruleIdis yours. Give each rule a stable name of your choosing.
DEFAULT rule, or two of them, is refused:ACTIVE when it’s created. Only an ACTIVE offering can be
ordered or booked: any other is 422 NOT_SELLABLE, Offering off_… is INACTIVE and is not sold; only ACTIVE offerings take new bookings and orders.
Change it with POST /services/{serviceId}/offerings/{offeringId}/status and
{ "status": "INACTIVE" }.skillIds and locationIds on an offering must name existing, active skills
and Locations. Both are read-only on the public API: see
Locations and skills.4
Create the packages
A package is a prepaid bundle of sessions of one offering. Create it under
that offering:Put the package on sale with
creditCountis the number of sessions.pricingis the price of the whole package, with the same one-DEFAULTrule as an offering.validityDaysis how long the sessions stay bookable after purchase. Leave it out and they never expire.- A package is
ACTIVEunless you sendstatus. AnACTIVEpackage is on sale at once. Send"status": "DRAFT"while you set things up.
PACKAGE business model. A SCHEDULED_PACKAGE
one isn’t enough to create a package:POST /packages/{packageId}/status and
{ "status": "ACTIVE" }. ARCHIVED retires it. List a service’s packages with
GET /services/{serviceId}/packages.Only an ACTIVE package sells. An order line for a DRAFT or ARCHIVED
package is 422 PACKAGE_NOT_ACTIVE. Sessions already bought from it stay
bookable. Show clients only status=ACTIVE packages. See
The package lifecycle.5
Publish the service
Nothing goes back to
DRAFT. Any other move, including LIVE to LIVE, is a
400:LIVE. Publish last, once the steps above are done.Only a LIVE service appears in a supplier’s services on
GET /suppliers and in search results. A DRAFT one is linked but hidden.Only a LIVE service sells. Until you publish it, POST /orders refuses
its lines with 422 NOT_SELLABLE. See
What the status controls.6
Create the suppliers
firstName,lastNameandemailare required. The email is unique in the project: a second supplier with it is409 CONFLICT,A supplier with this email already exists in the project.serviceIdslinks the supplier to the services they deliver. An id that isn’t a service is400 BAD_REQUEST,Unknown serviceId(s): srv_…. Link one more later withPOST /suppliers/{supplierId}/services/{serviceId}.skillIdslists the supplier’s skills. An offering that requires a skill is offered only by suppliers who have it.timezoneis the zone the supplier’s hours are written in. Without it, the supplier uses the project’s default zone.externalIdis your own id for the supplier. It comes back on every read, but you can’t search by it. Keep thesupplierIdin your own system too.
active when created. Update one with
PUT /suppliers/{supplierId}: send only the fields that change.
serviceIds and skillIds, when sent, replace the whole set. See
Managing suppliers.7
Add the supplier's photo
The photo upload is three calls. You never send the image to MarketBox
directly.The response is the supplier, with
-
Ask for an upload URL:
contentTypeisimage/jpeg,image/pngorimage/webp.contentLengthis the file’s size in bytes, at most 5 MB. The200returnsuploadId,variantId,url,method: "PUT"andheaders. -
PUTthe file’s bytes tourl, with exactly theheadersyou were given, within 300 seconds. Add no headers of your own. -
Attach it:
avatarUrl set.8
Get the supplier's hours set
An API key can’t write a supplier’s schedule, blocked time or travel
zones. Those routes exist only on the supplier plane, as the signed-in
supplier. So a supplier you’ve just created is in the catalog, but nobody can
book them yet.Either the supplier sets their own hours, in your
supplier portal or in the
MarketBox dashboard, or the business sets them in the dashboard. For a supplier
who travels to clients, see
Set up a mobile supplier’s service area.To use your portal, the business invites the supplier to the project from the
dashboard, and the supplier accepts. See
Before you start.Check from your server with
GET /suppliers/{supplierId}.
availability.schedules: [] means the supplier has no live schedule and
can’t be booked, even with active: true.A supplier is bookable when
- they’re
active; - they’re linked to the service, and have every skill the offering requires;
- they have an
ACTIVEschedule that covers the offering, at a venue or in a travel zone; - the offering is
ACTIVE, with itsDEFAULTprice; - the service has an active business model for the way you sell it.
Keep it in sync
- Store MarketBox’s ids. Services, offerings, business models and packages
carry no id of yours, so keep
serviceId,offeringId,businessModelIdandpackageIdagainst your own records. - Use the ids from the responses. Updating an offering or a business
model, changing its status, or deleting an offering, with an unknown id is
404 NOT_FOUND. Nothing is written. - Replace whole values on
PUT. OnPUT /services/{serviceId},name,descriptionandparticipantSettingsreplace the stored value. Send the full object, not only the changed language. - Retire instead of deleting. Set an offering
INACTIVE, a packageARCHIVEDand a serviceINACTIVE. Orders and bookings that already use them keep their snapshot of the price. AnINACTIVEoffering refuses new order lines and every new booking of it, even from items already bought. AnINACTIVEservice and anARCHIVEDpackage refuse new orders, but sessions already bought from them stay bookable. - Lists aren’t paginated.
GET /services, its offerings, business models and packages return everything in one page.
Reference
Endpoints used in this guide
All take the API key alone.
Errors and edge cases
See Errors for the envelope.