Skip to main content
This guide gets you from no account to a first booking through the MarketBox API. The examples need curl, or Node 18 or newer for the TypeScript ones.

1. Get a project and an API key

Everything in the API belongs to a project, and an API key is minted inside one. You do this once, in the MarketBox dashboard.
1

Sign up or sign in

Open the dashboard. It sends you to the MarketBox sign-in page. If you have no account yet, sign up there with your email address.
2

Create a project

A new account lands on a home page with a Set up your business card: select it. If you already belong to a project, select New project instead.Enter a Project name, Time zone, Language and Slug, then select Create project. You become the project’s admin.
3

Create an application

In the project, open Settings in the sidebar, then API Access under Operations. Only a project admin can open this page.Select New application and fill in:
  • Application name: a label for this integration.
  • Callback URLs and Logout URLs: both are required. They belong to end-user sign-in, which this quickstart doesn’t use. Enter http://localhost:3000/auth/callback and http://localhost:3000/ for now, and see Build a booking flow when you add sign-in.
  • What the API key may call: leave Standard API access ticked. A key without it is refused with 403 CAPABILITY_NOT_GRANTED.
Select Create application.
4

Copy the API key

The page shows Copy the API key now — it’s shown only once. Select Copy key and store the key somewhere safe. It can’t be shown again: if you lose it, mint a new one.
5

Copy the project ID

On the application, Config for this booking flow lists projectId and apiBaseUrl, with the sign-in settings. Copy config copies them all.The project ID starts with prj_. It is also in the address bar on every page of the project: /dashboard/project/prj_…/.
The key works on this one project. Treat it like a password: anyone who has it can act on the project. See Authentication for scope, capabilities and rotation.
Never commit API keys to source control. Use environment variables or a secrets manager.

2. Make your first call

The MarketBox API is served from:
Every example in these docs reads it from MARKETBOX_API_URL:
This is the production API. A key acts on the real data of its project. See Test keys and sandbox.
Export the project ID too:
Every request needs the key in the x-api-key header. Health is the simplest endpoint to verify connectivity — it’s unauthenticated and lives outside /v1.
Then try a real call. List the services in your project:
A new project has no services yet, so data is an empty array. That is still a working call: your key and project ID are right. Step 3 says how to add a service. Once you have a service, list its offerings. An offering is a bookable variant of a service, with its own duration and price:
The response is:

3. Create a booking

What a booking needs

A booking names a service and offering, a supplier, a client and a time. A new project has none of these, so create them first: A client is created in one of two ways:
  • A person signs in through your booking flow. POST /clients/me with their token creates the client and returns the clientId. That is the production path: see Build a booking flow.
  • Staff add the client in the dashboard. This is the quick way for a first test. In the project menu, open Customers, which is the dashboard’s name for clients. Choose New customer, fill in the form, then choose Open full profile. The cli_ ID is the last part of the page address: /dashboard/project/prj_…/client/cli_….
This creates a real booking. MarketBox emails the client a confirmation and the supplier a new-booking notice as part of the create call. Use a client and a supplier whose email addresses you control. See Emails and Test keys and sandbox.
Export what you collected. The curl examples below read these:

Create the order

A booking always draws down an order item: you can’t create one without an order first. Create an order with one SINGLE_SESSION item for your service and offering. Send the currency of the offering’s price from step 2.
The order is nested under data.order, and its items under data.items[]. The created order is DRAFT and unpaid. That is enough to book against: see Accept payments with Stripe to charge for it later.
Keep the two IDs. The booking needs both:

Create the booking

Each service line references the orderId and orderItemId from the order you just created. This is what ties the booking back to what paid for it. The body also carries explicit UTC timestamps plus an IANA timezone, and MarketBox derives the local date and times for you (see Timezones). This example uses locationType: "VIRTUAL", which needs no other location fields. PHYSICAL and TRAVEL_ZONE bookings need more: see Create a single booking for the required fields per locationType.
You get back the created booking under data, with status: "SCHEDULED" and the bookingId you use for follow-on actions. To undo a test booking, cancel it: see Cancel or reschedule a booking.

If it fails

Create a single booking has the full list.

4. Handle errors

Every error response has the same envelope:
The requestId is also returned in the X-Request-Id response header — include it when contacting support. See Errors for the full code list.

Next steps

Authentication

How API keys, project scope, and tenancy work.

Pagination

Cursor-based pagination on the large list endpoints.

Resources

Per-resource overviews of bookings, orders, offerings, and suppliers.

API reference

Every endpoint with an interactive playground.