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

# Show a package storefront

> Render every package of a service as a ready-to-book plan — one call returns each package, its pricing and its slate, with no fan-out.

This guide covers **package discovery** — the screen a client sees before
they've picked anything: every package a service sells, each already priced
and matched against real supplier availability. It's the step that comes
*before* [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md), which
starts from a `packageId` and `slateId` you already have in hand.

It builds on [The booking engine model](https://docs.gomarketbox.com/concepts/booking-engine-model.md) —
read that first if you haven't, especially the [Single vs package](https://docs.gomarketbox.com/concepts/booking-engine-model.md#single-vs-package)
and [Slates](https://docs.gomarketbox.com/concepts/booking-engine-model.md#slates) sections. This guide also
assumes the [BFF pattern](https://docs.gomarketbox.com/guides/booking-flow-auth.md#the-bff-pattern) and an
API key already set up.

> [!NOTE]
>
> Every request in this guide is authenticated with the `x-api-key` header,
> attached server-side by your BFF — never in the browser.

## How it works

A package storefront is two calls, always in this order:

1. **Get bookable plans.** `POST /availability/package-options` takes a
   `serviceId` plus a location and plans **every** ACTIVE package in one
   call — no client-side loop over packages. Each entry carries the
   `package` itself (the name, `creditCount`, and `pricing` you need to
   render a plan card) with a `status` and, when it's bookable, a
   ready-to-use `slateId`.
2. **Book the one the client picks.** Hand that entry's `slateId` (and its
   `package.packageId`) to the order + booking flow in
   [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md).

You don't need to list the packages first: `package-options` returns each
package with its pricing. To list a service's packages without planning
them, see
[Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md#how-it-works),
step 1.

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant BFF as Your BFF
    participant MB as MarketBox API
    B->>BFF: Show packages for a service
    BFF->>MB: POST .../availability/package-options { serviceId, location }
    MB-->>BFF: { data: [{ package, status, slateId, primarySlate }] }
    BFF-->>B: Render plan cards; mark OK entries bookable, surface reason on the rest
    B->>BFF: Client picks a plan
    Note over BFF,MB: Continue with Create a package booking (order → package-bookings)
```

**1. Get bookable plans**

Plan every ACTIVE package in one call with
`POST /availability/package-options` — send the `serviceId` and a location
(a stored `locationId`, or `lat` + `lng` + `address` for the travel-zone
branch). Optionally pin a `supplierId`, or override the cadence with `rrule`.

```ts theme={null}
// app/api/bff/package-options/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { serviceId } = await request.json();

  const res = await fetch(
    `${process.env.MARKETBOX_API_URL}/v1/projects/${process.env.MARKETBOX_PROJECT_ID}/availability/package-options`,
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.MARKETBOX_API_KEY!, // server-only
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        serviceId,
        lat: 43.6532,
        lng: -79.3832,
        address: {
          addressOneLine: '100 Queen St W, Toronto, ON M5H 2N2, Canada',
          streetNumber: '100',
          streetName: 'Queen St W',
          city: 'Toronto',
          state: 'ON',
          country: 'CA',
          zipCode: 'M5H 2N2',
        },
        timezone: 'America/Toronto',
        lookAheadStartDate: '2026-08-01T00:00:00-04:00',
      }),
    },
  );

  const body = await res.json().catch(() => ({}));
  return NextResponse.json(body, { status: res.status });
}
```

> [!WARNING]
>
> `lookAheadStartDate` must carry a **numeric `±HH:MM` offset** (e.g.
> `-04:00`) — a `Z` suffix is rejected with a `400`. `timezone` must be an
> **IANA identifier** (`America/Toronto`, never `EST`) — anything else is also
> a `400`.

`rrule` is optional. Omit it and the cadence **defaults to
`FREQ=WEEKLY;COUNT={creditCount}`, derived per package from its own credit
count** — a 10-session package gets a 10-week weekly cadence automatically,
with no need to compute one per plan card.

One entry per ACTIVE package (abridged to two — a bookable plan and an
unplannable one):

```json theme={null}
{
  "data": [
    {
      "package": {
        "packageId": "pkg_01kvr4cgb3esg8hxx32kwhre7g",
        "offeringId": "off_01kv60qge5eh59ap0gw0pqrrys",
        "name": { "en": "10-Session Pack" },
        "creditCount": 10,
        "pricing": [{ "ruleId": "r_9f2c1b04", "scope": "DEFAULT", "price": { "amount": 45000, "currency": "USD" } }, { "ruleId": "r_210b02de", "scope": "COUNTRY", "country": "CA", "price": { "amount": 45000, "currency": "CAD" } }],
        "status": "ACTIVE"
      },
      "status": "OK",
      "reason": null,
      "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
      "primarySlate": {
        "slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
        "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
        "completeness": "COMPLETE",
        "sessionsRequested": 10,
        "sessionsFilled": 10,
        "matchScore": 1,
        "matchComponents": { "startDate": 1 },
        "slots": [ { "sessionIndex": 1, "bookingStartUtc": "2026-08-01T13:30:00.000Z" } ]
      },
      "alternates": []
    },
    {
      "package": {
        "packageId": "pkg_01kvc5m1t8h2y4nq7wzb3jde6k",
        "offeringId": "off_01kv60qge5eh59ap0gw0pqrrys",
        "name": { "en": "20-Session Pack" },
        "creditCount": 20,
        "pricing": [{ "ruleId": "r_5e8a71c2", "scope": "DEFAULT", "price": { "amount": 80000, "currency": "USD" } }, { "ruleId": "r_318c04ef", "scope": "COUNTRY", "country": "CA", "price": { "amount": 80000, "currency": "CAD" } }],
        "status": "ACTIVE"
      },
      "status": "NO_COMPLETE_SLATE",
      "reason": "package cadence requires 134-day availability window for 20 sessions, which exceeds the 120-day maximum",
      "slateId": null,
      "primarySlate": null,
      "alternates": []
    }
  ]
}
```

`matchComponents` carries only `startDate` here, with no `cadence` entry —
this endpoint's whole appeal is not sending an `rrule` per package, and
without one there's no requested cadence for the plan to be scored against.
`matchScore` is `1`, the mean of the one component present. See
[How well a slate matches](https://docs.gomarketbox.com/resources/suggestions.md#how-well-a-slate-matches-matchscore-and-matchcomponents)
for the full breakdown.

> [!NOTE]
>
> **This is a `200` even when some — or every — package is unplannable.**
> `package-options` never fails the request because one package couldn't be
> planned. Read each entry's `status`: render `OK` entries as bookable plan
> cards using `slateId`, and surface the others' `reason` (e.g. "no slots for
> this cadence" or, as above, a cadence that needs more than the 120-day
> look-ahead ceiling) instead of hiding them silently. A weekly 10-session
> package (\~70 days) comfortably fits the ceiling and comes back `OK`; a
> weekly 20-session package (\~134 days) does not.

> [!NOTE]
>
> **A service with no ACTIVE packages is a `200` with `data: []`, not an
> error** — hide the packages tab, don't branch on a status code. An
> **unknown** `serviceId` is a `404`, so a typo can never masquerade as "this
> service sells no packages."

> [!NOTE]
>
> **`pricing[]` is the full rule set, not one number.** Every package (and
> offering) carries a `DEFAULT` rule plus zero or more regional overrides
> (`COUNTRY` / `STATE` / `POSTAL`) — a rule set with no `DEFAULT` is invalid,
> so it's always there. The storefront's job is to pick **one** entry to
> *display*, based on where you already know (or guess) the client is
> booking from; the order-create call later must pass a matching region
> source (`reservationId`, `locationId`, or `address`) so the **server**
> resolves that same rule. Show the `COUNTRY/CA` price and then create the
> order with no region fields, and the order will price off the client's
> default saved address instead — or off `DEFAULT` when the client has no
> saved address. Either may be a different currency than what you
> displayed. See
> [Regional pricing](https://docs.gomarketbox.com/concepts/regional-pricing.md) for the full resolution
> rule and how to keep display and order-create in agreement.

Join each entry's `package.offeringId` against the offerings you already hold to
build the card label — e.g. `pkg.offeringId` → `offering.name` gives you
"10-Session Pack · Beginner 30 minutes · \$450 CAD" from `name`, the joined
offering name, and the entry of `pricing[]` matching the client's known or
selected region (falling back to the `DEFAULT` entry when you don't know it
yet).

> [!WARNING]
>
> **Don't list business models and render them as packages.** The
> `PACKAGE` **business model** returned by
> `GET /services/{serviceId}/business-models` is only a flag on the service
> meaning "this service *can* be sold as packages." It is **not** a sellable
> bundle, and it carries **no `creditCount` and no `pricing`** — those fields
> live only on packages, such as the `package` in each entry here. Reading the business-models
> list and rendering each row as a package gives you one package-shaped object
> with a null session count and a null price, and a storefront that renders
> nothing. The packages are here; the business model just permits them.

This also replaces a client-side fan-out of one `package-slate` call per
package: the engine reads each **offering's** supplier availability once,
however many packages sit on that offering, not once per package.

**2. Book one**

Once the client picks a card, you already have everything the booking flow
needs: `package.packageId` and `slateId` from the chosen entry. Skip
straight to order creation — no need to rebuild a slate, since
`package-options` already built one.

```ts theme={null}
// pass straight into the order + booking flow
const { packageId } = chosen.package;
const { slateId } = chosen;
```

Continue with **Step 3 (Create the order)** and **Step 4 (Book the slate)**
of [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md) using these
two values.

## Reference

### Endpoints used in this guide

| Endpoint | Method | Auth | Description |
| - | - | - | - |
| `/v1/projects/{projectId}/availability/package-options` | `POST` | `x-api-key` | Plan every ACTIVE package of a service in one call. Each entry carries the `package`, its `status`, `reason`, and — when bookable — a ready-to-use `slateId`. `200` even when packages are unplannable; per-package failures never fail the request. `404` for an unknown `serviceId`. For the package object, see [Packages](https://docs.gomarketbox.com/resources/packages.md). |

### Configuration

| Value | Env var | Browser? |
| - | - | - |
| API key | `MARKETBOX_API_KEY` | **No** (server-only) |
| API base URL | `MARKETBOX_API_URL` | **No** (BFF-only) |
| Project id | `MARKETBOX_PROJECT_ID` | **No** (BFF-only) |

### Errors and edge cases

| Scenario | `code` | Status | Resolution |
| - | - | - | - |
| The service exists but has no ACTIVE packages | — | `200` | Not an error: `data` is `[]`. Hide the packages tab rather than branching on a status code. |
| Unknown `serviceId` | `NOT_FOUND` | `404` | A typo never reads as "no packages" — check the id came from this project's service catalogue. |
| A package's derived (or explicit) cadence needs more than the 120-day look-ahead ceiling | `NO_COMPLETE_SLATE` | `200`, per entry | Not a request-level error — that entry's `status` is `NO_COMPLETE_SLATE` and `reason` names the window required. Render the other `OK` entries normally; see [Availability and slates](https://docs.gomarketbox.com/guides/availability-and-slates.md#the-120-day-look-ahead-ceiling). |
| No supplier availability at all for a package's location/window | `NO_AVAILABILITY` | `200`, per entry | Also per-entry, not a request failure. Try a different location or a later `lookAheadStartDate`. |
| `lookAheadStartDate` has a `Z` suffix instead of a numeric offset | `VALIDATION_ERROR` | `400` | Use a numeric `±HH:MM` offset, e.g. `-04:00`. |
| `timezone` is an abbreviation or offset (`EST`, `GMT+5`) rather than an IANA identifier | `VALIDATION_ERROR` | `400` | Send an IANA zone, e.g. `America/Toronto`. See [Timezones](https://docs.gomarketbox.com/concepts/timezones.md#valid-timezones). |
| Neither `locationId` nor `lat`+`lng`+`address` provided | `VALIDATION_ERROR` | `400` | Send one location form — a stored `locationId`, or the full travel-zone trio. |
| Listing business models instead of packages | — | — | Not an API error — a modeling mistake. `GET .../business-models` rows have no `creditCount`/`pricing`; use `GET .../packages` instead. |

See [Errors](https://docs.gomarketbox.com/concepts/errors.md) for the full envelope and code list.


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