> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Sign up, create a project, mint an API key, make your first call, and create your first booking.

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](https://app.gomarketbox.com/dashboard).

**1. Sign up or sign in**

Open the [dashboard](https://app.gomarketbox.com/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](https://docs.gomarketbox.com/guides/booking-flow-auth.md) 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](https://docs.gomarketbox.com/concepts/authentication.md)
for scope, capabilities and rotation.

> [!WARNING]
>
> 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:

```
https://apiv2.gomarketbox.com
```

Every example in these docs reads it from `MARKETBOX_API_URL`:

```bash theme={null}
export MARKETBOX_API_URL="https://apiv2.gomarketbox.com"
export MARKETBOX_API_KEY="your-key-here"
```

> [!NOTE]
>
> This is the production API. A key acts on the real data of its project. See
> [Test keys and sandbox](https://docs.gomarketbox.com/concepts/authentication.md#test-keys-and-sandbox).

Export the project ID too:

```bash theme={null}
export MARKETBOX_PROJECT_ID="prj_..."
```

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`.

```bash curl theme={null}
curl "$MARKETBOX_API_URL/health"
```

```ts TypeScript theme={null}
const res = await fetch(`${process.env.MARKETBOX_API_URL}/health`);
console.log(await res.json());
```

Then try a real call. List the services in your project:

```bash curl theme={null}
curl "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/services" \
  -H "x-api-key: $MARKETBOX_API_KEY"
```

```ts TypeScript theme={null}
const res = await fetch(
  `${process.env.MARKETBOX_API_URL}/v1/projects/${process.env.MARKETBOX_PROJECT_ID}/services`,
  { headers: { 'x-api-key': process.env.MARKETBOX_API_KEY! } },
);
const { data, nextCursor } = await res.json();
```

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:

```bash curl theme={null}
curl "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/services/$SERVICE_ID/offerings" \
  -H "x-api-key: $MARKETBOX_API_KEY"
```

```ts TypeScript theme={null}
const res = await fetch(
  `${process.env.MARKETBOX_API_URL}/v1/projects/${process.env.MARKETBOX_PROJECT_ID}/services/${process.env.SERVICE_ID}/offerings`,
  { headers: { 'x-api-key': process.env.MARKETBOX_API_KEY! } },
);
const { data, nextCursor } = await res.json();
```

The response is:

```json theme={null}
{
  "data": [
    {
      "offeringId": "off_01h2xcejqtfzcjxkvc4ay3pnh3",
      "serviceId": "srv_01h2xcejqtfzcjxkvc4ay3pnh3",
      "name": { "en": "60-minute private lesson" },
      "pricing": [
        {
          "ruleId": "r_9f2c1b04",
          "scope": "DEFAULT",
          "price": { "amount": 12000, "currency": "USD" }
        }
      ],
      "duration": { "type": "FIXED", "minutes": 60 },
      "attributeValues": [],
      "status": "ACTIVE"
    }
  ],
  "nextCursor": null
}
```

## 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:

| You need | What it must be | How to get it |
| - | - | - |
| `serviceId` and `offeringId` | A `LIVE` service with an active `SINGLE_BOOKING` business model, and an `ACTIVE` offering with a `DEFAULT` price. | Create them in the dashboard, or with your API key: [Provision your catalog and suppliers](https://docs.gomarketbox.com/guides/provision-catalog-and-suppliers.md). The two calls in step 2 list their IDs. |
| `supplierId` | A supplier in the project. | Add one in the dashboard, or with the same guide. `GET /v1/projects/{projectId}/suppliers` lists their IDs. |
| `clientId` | A client in the project. | **An API key alone can't create a client.** See below. |
| A start and an end | A future time when the supplier isn't already booked. | Pick one, or find an open slot with [Search suppliers by availability](https://docs.gomarketbox.com/guides/search-suppliers-by-availability.md). |

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](https://docs.gomarketbox.com/guides/booking-flow-auth.md).
* **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_…`.

> [!WARNING]
>
> **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](https://docs.gomarketbox.com/concepts/emails.md) and
> [Test keys and sandbox](https://docs.gomarketbox.com/concepts/authentication.md#test-keys-and-sandbox).

Export what you collected. The curl examples below read these:

```bash theme={null}
export SERVICE_ID="srv_..."
export OFFERING_ID="off_..."
export SUPPLIER_ID="sup_..."
export CLIENT_ID="cli_..."

# A future start and end, in UTC, when the supplier is free.
# Replace YYYY-MM-DD with a date that hasn't passed.
export BOOKING_START_UTC="YYYY-MM-DDT17:00:00.000Z"
export BOOKING_END_UTC="YYYY-MM-DDT18:00:00.000Z"
```

### 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.

```bash curl theme={null}
curl -X POST "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/orders" \
  -H "x-api-key: $MARKETBOX_API_KEY" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "clientId": "$CLIENT_ID",
  "currency": "USD",
  "items": [
    {
      "skuType": "SINGLE_SESSION",
      "serviceId": "$SERVICE_ID",
      "offeringId": "$OFFERING_ID",
      "quantity": 1
    }
  ]
}
EOF
```

```ts TypeScript theme={null}
const orderRes = await fetch(
  `${process.env.MARKETBOX_API_URL}/v1/projects/${process.env.MARKETBOX_PROJECT_ID}/orders`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.MARKETBOX_API_KEY!,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      clientId: process.env.CLIENT_ID,
      currency: 'USD', // the currency of the offering's price
      items: [
        {
          skuType: 'SINGLE_SESSION',
          serviceId: process.env.SERVICE_ID,
          offeringId: process.env.OFFERING_ID,
          quantity: 1,
        },
      ],
    }),
  },
);
const order = (await orderRes.json()).data;
const orderId = order.order.orderId;
const orderItemId = order.items[0].orderItemId;
```

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](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md) to charge
for it later.

```json theme={null}
{
  "data": {
    "order": {
      "orderId": "ord_01h2xcejqtfzcjxkvc4ay3pnh3",
      "status": "DRAFT",
      "total": { "amount": 12000, "currency": "USD" }
    },
    "items": [
      {
        "orderItemId": "oi_01h2xcejqtfzcjxkvc4ay3pnh3",
        "skuType": "SINGLE_SESSION",
        "quantity": 1,
        "quantityRemaining": 1,
        "unitPrice": { "amount": 12000, "currency": "USD" }
      }
    ]
  }
}
```

Keep the two IDs. The booking needs both:

```bash theme={null}
export ORDER_ID="ord_..."        # data.order.orderId
export ORDER_ITEM_ID="oi_..."    # data.items[0].orderItemId
```

### 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](https://docs.gomarketbox.com/concepts/timezones.md)). This example uses
`locationType: "VIRTUAL"`, which needs no other location fields. `PHYSICAL`
and `TRAVEL_ZONE` bookings need more: see
[Create a single booking](https://docs.gomarketbox.com/guides/create-a-single-booking.md) for the required
fields per `locationType`.

```bash curl theme={null}
curl -X POST "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/bookings" \
  -H "x-api-key: $MARKETBOX_API_KEY" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "supplierId": "$SUPPLIER_ID",
  "clientId": "$CLIENT_ID",
  "bookingStartUtc": "$BOOKING_START_UTC",
  "bookingEndUtc": "$BOOKING_END_UTC",
  "bookingTz": "America/New_York",
  "locationType": "VIRTUAL",
  "capacity": 1,
  "services": [
    {
      "serviceId": "$SERVICE_ID",
      "offeringId": "$OFFERING_ID",
      "businessModelType": "SINGLE_BOOKING",
      "quantity": 1,
      "orderId": "$ORDER_ID",
      "orderItemId": "$ORDER_ITEM_ID"
    }
  ]
}
EOF
```

```ts TypeScript theme={null}
// One week from now at 17:00 UTC, for 60 minutes. Pick a time the supplier
// is free, and make the length match the offering's duration.
const start = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
start.setUTCHours(17, 0, 0, 0);
const end = new Date(start.getTime() + 60 * 60 * 1000);

const bookingRes = await fetch(
  `${process.env.MARKETBOX_API_URL}/v1/projects/${process.env.MARKETBOX_PROJECT_ID}/bookings`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.MARKETBOX_API_KEY!,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      supplierId: process.env.SUPPLIER_ID,
      clientId: process.env.CLIENT_ID,
      bookingStartUtc: start.toISOString(),
      bookingEndUtc: end.toISOString(),
      bookingTz: 'America/New_York',
      locationType: 'VIRTUAL',
      capacity: 1,
      services: [
        {
          serviceId: process.env.SERVICE_ID,
          offeringId: process.env.OFFERING_ID,
          businessModelType: 'SINGLE_BOOKING',
          quantity: 1,
          orderId, // from the order you just created
          orderItemId,
        },
      ],
    }),
  },
);
const booking = (await bookingRes.json()).data;
console.log(booking.bookingId, booking.status);
```

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](https://docs.gomarketbox.com/guides/cancel-or-reschedule-a-booking.md).

### If it fails

| Status and `code` | What it means | Fix |
| - | - | - |
| `403 FORBIDDEN`, "API key missing or not recognised" | The `x-api-key` header is absent or wrong. | Check `MARKETBOX_API_KEY`. |
| `403 CAPABILITY_NOT_GRANTED` | The application lacks **Standard API access**. | A project admin ticks it on the **API Access** page. |
| `404 NOT_FOUND`, "Client not found" | The `clientId` isn't a client of this project. | Use a `cli_` ID from this project. |
| `422 NOT_SELLABLE` | The service isn't `LIVE`, or the offering isn't `ACTIVE`. | Publish the service, or use another offering. |
| `422 SERVICE_NOT_SOLD_AS` | The service has no active `SINGLE_BOOKING` business model. | Add one to the service. |
| `422 OFFERING_NOT_PRICED` | The offering has no `DEFAULT` price. | Add a `DEFAULT` price to the offering. |
| `409 SLOT_BOOKED` | The supplier is already booked at that time. | Pick another time. |

[Create a single booking](https://docs.gomarketbox.com/guides/create-a-single-booking.md#errors-and-edge-cases)
has the full list.

## 4. Handle errors

Every error response has the same envelope:

```json theme={null}
{
  "code": "NOT_FOUND",
  "message": "Booking not found",
  "statusCode": 404,
  "requestId": "3f7c1a9e-5b2d-4e8a-9f01-2c6d8b4a7e13"
}
```

The `requestId` is also returned in the `X-Request-Id` response header —
include it when contacting support. See [Errors](https://docs.gomarketbox.com/concepts/errors.md) for the
full code list.

## Next steps

> [card] [Authentication](https://docs.gomarketbox.com/concepts/authentication.md)
>
> How API keys, project scope, and tenancy work.

> [card] [Pagination](https://docs.gomarketbox.com/concepts/pagination.md)
>
> Cursor-based pagination on the large list endpoints.

> [card] [Resources](https://docs.gomarketbox.com/resources/bookings.md)
>
> Per-resource overviews of bookings, orders, offerings, and suppliers.

> [card] [API reference](https://docs.gomarketbox.com/api-reference/introduction.md)
>
> Every endpoint with an interactive playground.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.