Overview

Create a new package catalog template for the business. A package defines a bundle of services and/or products that can be sold to clients, including pricing, credit allocations per service group, and a default validity period that determines how long client subscriptions last.

Feature Requirement

Requires the booking_packages feature on the business. It belongs to the Payments module but is not part of every subscription, and is disabled by default on newly provisioned businesses — treat it as unavailable unless you have confirmed it is on for the specific business.

When the feature is off, the request is rejected with 403 Forbidden and this body:

{"message": "403 Forbidden", "status": "module_permission_missing"}

This is an entitlement check, not an authentication or permission failure. It is evaluated before the request body is validated and it fails identically for Staff, Directory and App tokens, so retrying, refreshing the token, or setting X-On-Behalf-Of will not change the outcome. The feature must be enabled for the business first. Related endpoints under /platform/v1/payment/packages and /platform/v1/payment/client_packages share the same gate.

Authentication

Available for Staff tokens. Directory and App tokens are supported with the X-On-Behalf-Of header set to the target business UID.

Required Parameters

• name — Display name of the package (e.g., "10 Music Lessons").
• price — Base price of the package (e.g., 100 for $100).
• currency — Three-letter ISO 4217 currency code (e.g., "USD", "ILS").
• expiration — Integer that, combined with expiration_unit, defines the default validity period for client subscriptions (e.g., 3).
• expiration_unit — Unit for the expiration period: "D" (days), "W" (weeks), "M" (months), or "Y" (years). Combined with expiration, determines how long a client package remains active (e.g., expiration=3, expiration_unit="M" means 3 months).
• items — Array of service/product groups included in the package. Each item must contain services (array of service UIDs) and total_bookings (number of credits for this group).

Optional Parameters

• description — Free-text description of the package shown to clients.
• discount_amount — Numeric discount value applied to the package price.
• discount_unit — Discount type: "F" (fixed amount off) or "P" (percentage off).
• image_path — URL path to the package's display image.
• online_payment_enabled — Whether clients can self-purchase this package from the client portal (boolean).
• products — Array of product objects included in the package (redeemed immediately at purchase, unlike service credits which are consumed per-appointment).

Notes

• After creating a catalog package, assign it to a client using POST /platform/v1/payment/client_packages with the returned package id as package_id.
• Items define the credit structure: when a client package is created from this template, each item becomes a credit pool with its own total_bookings count.