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:- Get bookable plans.
POST /availability/package-optionstakes aserviceIdplus a location and plans every ACTIVE package in one call — no client-side loop over packages. Each entry carries thepackageitself (the name,creditCount, andpricingyou need to render a plan card) with astatusand, when it’s bookable, a ready-to-useslateId. - Book the one the client picks. Hand that entry’s
slateId(and itspackage.packageId) to the order + booking flow in Create a package booking.
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
Join each entry’s
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.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.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).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: Continue with Step 3 (Create the order) and Step 4 (Book the slate)
of Create a package booking using these
two values.
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.Reference
Endpoints used in this guide
Configuration
Errors and edge cases
See Errors for the full envelope and code list.