Skip to main content
An agency or a platform that runs many businesses usually keeps its catalog in its own system and pushes it into MarketBox. This guide is that setup, in the order the API needs it:
  1. Service: the sellable thing. It starts DRAFT.
  2. Business models: how the service is sold (single sessions, packages).
  3. Offerings: the bookable variants, each with a duration and a price.
  4. Packages: prepaid bundles of sessions of one offering, if you sell them.
  5. Publish the service: LIVE.
  6. Suppliers: who delivers it, linked to the service, with a photo.
  7. Hours: the supplier’s schedule. An API key can’t write these.
Every call is server-side, with the 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.
A retried create can make a duplicate. The catalog routes take no idempotency key. A second POST of the same offering, business model or package creates a second one. A service or supplier is protected by its unique name or email, which answers 409 CONFLICT. After a timeout, list what exists before you retry.
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 "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:
Business models can also carry booking fees. See Service fees.
3

Create the offerings

An offering is what a client actually books: a duration and a price.
  • Amounts are integer minor units. 4500 is $45.00. A decimal is a 400.
  • pricing needs exactly one DEFAULT rule. It’s the price wherever no more specific rule matches. Add COUNTRY, STATE and POSTAL rules for regional prices. See Regional pricing.
  • ruleId is yours. Give each rule a stable name of your choosing.
No DEFAULT rule, or two of them, is refused:
An offering is 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:
  • creditCount is the number of sessions.
  • pricing is the price of the whole package, with the same one-DEFAULT rule as an offering.
  • validityDays is how long the sessions stay bookable after purchase. Leave it out and they never expire.
  • A package is ACTIVE unless you send status. An ACTIVE package is on sale at once. Send "status": "DRAFT" while you set things up.
The service needs an active PACKAGE business model. A SCHEDULED_PACKAGE one isn’t enough to create a package:
Put the package on sale with 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

The allowed moves:Nothing goes back to DRAFT. Any other move, including LIVE to LIVE, is a 400:
Publishing checks nothing else. A service with no offerings, no business models and no prices goes 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, lastName and email are required. The email is unique in the project: a second supplier with it is 409 CONFLICT, A supplier with this email already exists in the project.
  • serviceIds links the supplier to the services they deliver. An id that isn’t a service is 400 BAD_REQUEST, Unknown serviceId(s): srv_…. Link one more later with POST /suppliers/{supplierId}/services/{serviceId}.
  • skillIds lists the supplier’s skills. An offering that requires a skill is offered only by suppliers who have it.
  • timezone is the zone the supplier’s hours are written in. Without it, the supplier uses the project’s default zone.
  • externalId is your own id for the supplier. It comes back on every read, but you can’t search by it. Keep the supplierId in your own system too.
A supplier is 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.
  1. Ask for an upload URL:
    contentType is image/jpeg, image/png or image/webp. contentLength is the file’s size in bytes, at most 5 MB. The 200 returns uploadId, variantId, url, method: "PUT" and headers.
  2. PUT the file’s bytes to url, with exactly the headers you were given, within 300 seconds. Add no headers of your own.
  3. Attach it:
MarketBox resizes the image after the upload. If you attach it before that’s done, retry after a second:
The response is the supplier, with 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 ACTIVE schedule that covers the offering, at a venue or in a travel zone;
  • the offering is ACTIVE, with its DEFAULT price;
  • the service has an active business model for the way you sell it.
Then search finds them. See Search suppliers by availability, and Client checkout, end to end for the booking itself.

Keep it in sync

  • Store MarketBox’s ids. Services, offerings, business models and packages carry no id of yours, so keep serviceId, offeringId, businessModelId and packageId against 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. On PUT /services/{serviceId}, name, description and participantSettings replace the stored value. Send the full object, not only the changed language.
  • Retire instead of deleting. Set an offering INACTIVE, a package ARCHIVED and a service INACTIVE. Orders and bookings that already use them keep their snapshot of the price. An INACTIVE offering refuses new order lines and every new booking of it, even from items already bought. An INACTIVE service and an ARCHIVED package 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.