Skip to main content
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, which starts from a packageId and slateId you already have in hand. It builds on The booking engine model — read that first if you haven’t, especially the Single vs package and Slates sections. This guide also assumes the BFF pattern and an API key already set up.
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.
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, step 1.
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.
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):
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 for the full breakdown.
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.
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.”
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 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).
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.
Continue with Step 3 (Create the order) and Step 4 (Book the slate) of Create a package booking using these two values.

Reference

Endpoints used in this guide

Configuration

Errors and edge cases

See Errors for the full envelope and code list.