Skip to main content
A package sells a number of prepaid sessions of one offering for one price, such as “10 swim lessons for $405”. A client buys it as one order line. Each later booking draws one session from it. A package belongs to one offering, and through it to one service. See Services and offerings for the objects above it, and The booking engine model for how its sessions are drawn down.

Before you create one

The service needs an active PACKAGE business model. A SCHEDULED_PACKAGE model isn’t enough to create a package. Without one, the create is a 400, and nothing is written:
Add the business model first. See Adding a business model.

The package lifecycle

POST /v1/projects/{projectId}/packages/{packageId}/status moves a package to any of the three statuses, from any other. There is no transition table, so you can take a package off sale and put it back. Only an ACTIVE package sells. POST /availability/package-options plans only ACTIVE packages, and POST /orders refuses a line for a DRAFT or ARCHIVED one. The refusal is a 422, and nothing is written:
A PACKAGE line is also refused with 422 NOT_SELLABLE when the package’s service isn’t LIVE, or its offering isn’t ACTIVE. List only status=ACTIVE packages of LIVE services to clients. Sessions a client already bought stay bookable whatever the package’s status, or the service’s, because the order item captured the package when it was bought. Three other things do stop them being booked:
  • The offering is deleted. Each session booking is a 404 NOT_FOUND, Offering off_… not found.
  • The offering is INACTIVE. Each session booking is a 422 NOT_SELLABLE, Offering off_… is INACTIVE and is not sold; only ACTIVE offerings take new bookings and orders.
  • The service has no active PACKAGE business model. Each session booking is a 400 NOT_A_PACKAGE_SERVICE. See Changing a business model.
There is no delete route. Archive a package to retire it.

Anatomy of a package

Pricing

A package’s pricing uses the same rules as an offering’s: exactly one DEFAULT rule, a child rule needs its parent, and country and state are stored as ISO codes. See Pricing rules. Each rule’s amount is the price of the whole package, not of one session. A 10-session package at 40500 charges 40500 once. When the package is bought, the order line takes:
  • quantity: the package’s creditCount.
  • lineTotal: the matched rule’s amount, for the order’s region.
  • unitPrice: lineTotal divided by creditCount, for display. It may not divide exactly. lineTotal is the figure that’s charged.
  • expiresAt: the purchase time plus validityDays, or null.
discountPercent records the discount used when the package’s prices were first worked out from the offering’s. It isn’t used to charge anything, and it may not match pricing after an edit. Never compute an amount from it. A package created before regional pricing existed reads back with one DEFAULT rule whose ruleId is r_legacy_default.

Creating a package

POST /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages:
  • creditCount and pricing are required.
  • status defaults to ACTIVE, so the package is on sale as soon as it’s created. Send DRAFT until it’s ready.
  • capacity defaults to 1, and validityDays to null.
The offering must belong to the service in the path and not be deleted. Otherwise the create is a 404 NOT_FOUND, Offering not found for this service. The create takes no idempotency key. A retried POST makes a second package, so list before you retry.

Updating a package

PUT /v1/projects/{projectId}/packages/{packageId} is a partial update. Only the fields you send change.
  • Send pricing whole, including its DEFAULT rule. It’s checked against the same rules as on create.
  • A new pricing or creditCount applies to future purchases only. A package already bought keeps the sessions and price it was bought with.
  • The offering and service can’t be changed. Create a new package instead.
  • status isn’t settable here. Use the status route.
An unknown packageId is 404 NOT_FOUND, Package not found.

Listing packages

Both lists take status. Send status=ACTIVE for a storefront: otherwise DRAFT and ARCHIVED packages are included. Neither list is paginated, and nextCursor is always null. A service that sells no packages returns 200 with data: []. For a storefront built on these reads, see Show a package storefront.

Selling a package

A package is sold as an order line that names it:
The server works out the service, offering, session count, price and expiry from the package. Add PACKAGE lines when you create the order: POST .../orders/{orderId}/items takes no packageId. See Creating an order. These refuse the order, and nothing is written: Once the order exists, its PACKAGE order item is the client’s balance of sessions: quantityRemaining is the live count. Book from it with Create a package booking.
On the client plane, a client books their own package sessions only from a PAID order. The API-key routes don’t check payment. See Book a client’s package credit.

Endpoint index

  • POST /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages
  • GET /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages
  • GET /v1/projects/{projectId}/services/{serviceId}/packages
  • GET /v1/projects/{projectId}/packages/{packageId}
  • PUT /v1/projects/{projectId}/packages/{packageId}
  • POST /v1/projects/{projectId}/packages/{packageId}/status
  • POST /v1/projects/{projectId}/availability/package-options — see Show a package storefront
  • POST /v1/projects/{projectId}/orders/{orderId}/package-bookings — see Create a package booking