Before you create one
The service needs an activePACKAGE business model. A
SCHEDULED_PACKAGE model isn’t enough to create a package. Without one, the
create is a 400, and nothing is written:
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:
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 a422 NOT_SELLABLE,Offering off_… is INACTIVE and is not sold; only ACTIVE offerings take new bookings and orders. -
The service has no active
PACKAGEbusiness model. Each session booking is a400 NOT_A_PACKAGE_SERVICE. See Changing a business model.
Anatomy of a package
Pricing
A package’spricing 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’screditCount.lineTotal: the matched rule’s amount, for the order’s region.unitPrice:lineTotaldivided bycreditCount, for display. It may not divide exactly.lineTotalis the figure that’s charged.expiresAt: the purchase time plusvalidityDays, ornull.
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:
creditCountandpricingare required.statusdefaults toACTIVE, so the package is on sale as soon as it’s created. SendDRAFTuntil it’s ready.capacitydefaults to1, andvalidityDaystonull.
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
pricingwhole, including itsDEFAULTrule. It’s checked against the same rules as on create. - A new
pricingorcreditCountapplies 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.
statusisn’t settable here. Use the status route.
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: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}/packagesGET /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packagesGET /v1/projects/{projectId}/services/{serviceId}/packagesGET /v1/projects/{projectId}/packages/{packageId}PUT /v1/projects/{projectId}/packages/{packageId}POST /v1/projects/{projectId}/packages/{packageId}/statusPOST /v1/projects/{projectId}/availability/package-options— see Show a package storefrontPOST /v1/projects/{projectId}/orders/{orderId}/package-bookings— see Create a package booking