The Subscription Object

A subscription represents a purchased offering related to a business. It includes details such as the buyer, pricing, trial period, and the subscription's lifecycle state.

Entity Properties

Name	Description	Type	Required
uid	The entity UID	string	Yes
created_at	The creation date and time of the object	string (date-time)	Yes
updated_at	The last updated date and time of the object	string (date-time)	Yes
display_name	The subscription display name	string	Yes
is_active	Indicates whether the subscription is active (not canceled and not expired)	boolean	No
offering_uid	The underlying directory offering UID	string	Yes
offering_type	Category of the offering. Possible values: `package`, `app`, `sms`, `staff_slot`.	string	No
purchase_state	Current subscription state. Possible values: `pending`, `purchased`, `canceled`, `expired`. Default: `pending`.	string	No
cancellation_date	The date when the subscription was canceled	string (date-time)	No
expiration_date	The date when the subscription will expire (or expired)	string (date-time)	No
buyer_uid	The actor of the action, typically the staff UID	string	Yes
business_uid	The business associated with the subscription	string	Yes
purchase_price	The purchase price at the time the subscription was created	number	Yes
purchase_currency	The currency used at the time of purchase. Possible values: `USD`, `EUR`, `GBP`.	string	Yes
payment_type	Defines the payment type. Possible values: `monthly`, `annual`, `free`, `single_charge`, `bundle`, `partner`.	string	Yes
bundled_from_subscription_uid	The subscription UID that this subscription is bundled from	string	No
charged_by	Defines who charges for this subscription. Possible values: `partner`, `platform`.	string	Yes
trial_type	Indicates trial type. Possible values: `no_trial`, `expire`. Default: `no_trial`.	string	No
trial_period	Number of trial days available in the subscription	int	no
next_charge_date	The start date of the next billing cycle, or `null` if the subscription is set to expire.	string (date-time)	No
quantity	The number of units (e.g., staff seats, SMS messages, AI tokens) allocated to the subscription during the subscription period. For add-ons, if quanity equals `-1`than it means `unlimited` (currently only supported for `staff_seats`)	number	No
can_purchase_additional_seats	Indicates if a business can purchase additional seats beyond the bundled subscription (default: True); if False, only the bundled seats are available	boolean	No

Example

{
  "uid": "c33f32c-95ae-4e8f-9f65-18bba589cb43",
  "created_at": "2024-01-01T09:00:00Z",
  "updated_at": "2024-03-20T12:34:56Z",      
  "display_name": "Premium 10",
  "is_active": true,
  "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
  "offering_type": "package",
  "purchase_state": "purchased",
  "cancellation_date":"",
  "expiration_date": "",
  "buyer_uid": "user_12345",
  "business_uid": "biz_67890",
  "purchase_price": 99.99,
  "purchase_currency": "USD",
  "payment_type": "monthly",
  "bundled_from_subscription_uid":"",
  "charged_by":"platform",
  "trial_type":"no_trial",
  "next_charge_date":"2025-03-20T12:34:56Z",
  "quantity":1,
  "can_purchase_additional_seats":true
}