--- title: "Get subscription" method: GET path: "/subscriptions/{id}" tags: ["Subscriptions"] --- # Get subscription `GET /subscriptions/{id}` Retrieves detailed information for a specific subscription. The response includes: * Current tier * Active add-ons * Subscription status ## Path parameters - `id` string, required ## Response `200` When request is successful. Returns a 'Subscription' object. - Subscription - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `id` string, nullable — Unique identifier of the subscription. - `type` 0 | 1 - `productSuite` string, nullable — The product suite of the subscription. - `tier` Tier - `id` string, uuid — Unique identifier of the tier. - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `smokeballId` string, nullable — Unique Smokeball identifier of the tier. This identifier convenience purposes only and should not be used to interact with the subscriptions API. - `productSuite` string, nullable — The product suite that this tier belongs to. - `name` string, nullable — The display name of the tier. - `description` string, nullable — The description of the tier. Can be used to describe the tier to a customer. - `trialPeriodDays` integer, nullable — The number of days the tier can be trialed for. Cannot be trialed if zero or missing. - `prices` Price[], nullable — The price options for the tier. - `id` string, nullable — The internal price id. - `externalPriceId` string, nullable — The external price id. - `default` boolean — Returns `true` if the price is the default price. - `active` boolean — Returns `true` if the Price is active. - `type` string — The type of price. - `name` string, nullable — The price display name. - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents). - `interval` string — Recurring payment interval type. - `createdDate` string, date-time — The created date of the tier. - `updatedDate` string, date-time — The updated date of the tier. - `trialingTier` TrialingTier - `id` string, uuid — Unique identifier of the tier. - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `smokeballId` string, nullable — Unique Smokeball identifier of the tier. This identifier convenience purposes only and should not be used to interact with the subscriptions API. - `productSuite` string, nullable — The product suite that this tier belongs to. - `name` string, nullable — The display name of the tier. - `description` string, nullable — The description of the tier. Can be used to describe the tier to a customer. - `trialPeriodDays` integer, nullable — The number of days the tier can be trialed for. Cannot be trialed if zero or missing. - `prices` Price[], nullable — The price options for the tier. - `id` string, nullable — The internal price id. - `externalPriceId` string, nullable — The external price id. - `default` boolean — Returns `true` if the price is the default price. - `active` boolean — Returns `true` if the Price is active. - `type` string — The type of price. - `name` string, nullable — The price display name. - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents). - `interval` string — Recurring payment interval type. - `createdDate` string, date-time — The created date of the tier. - `updatedDate` string, date-time — The updated date of the tier. - `cancellationStatus` string, nullable — The cancellation status of the trial. * None - The trial has not been canceled. If a payment method is added to the subscription, the trial product(s) will be applied to the subscription at expiration. * Pending - The trial has been canceled. The trial product(s) will not be applied to the subscription at expiration. Possible values: None, Pending. - `activationDate` string, date-time, nullable — The date the trial was activated. - `expirationDate` string, date-time, nullable — The date the trial will expire. - `addOns` AddOn[], nullable — List of 'AddOn' products that the subscription is subscribed to. - `id` string, uuid — Unique identifier of the add-on. - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `smokeballId` string, nullable — Unique Smokeball identifier of the add-on. This identifier convenience purposes only and should not be used to interact with the subscriptions API. - `productSuite` string, nullable — The product suite that this add-on belongs to. - `name` string, nullable — The display name of the add-on. - `description` string, nullable — The description of the add-on. Can be used to describe the add-on to a customer. - `trialPeriodDays` integer, nullable — The number of days the add-on can be trialed for. Cannot be trialed if zero or missing. - `prices` Price[], nullable — The price options for the add-on. - `id` string, nullable — The internal price id. - `externalPriceId` string, nullable — The external price id. - `default` boolean — Returns `true` if the price is the default price. - `active` boolean — Returns `true` if the Price is active. - `type` string — The type of price. - `name` string, nullable — The price display name. - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents). - `interval` string — Recurring payment interval type. - `createdDate` string, date-time — The created date of the add-on. - `updatedDate` string, date-time — The updated date of the add-on. - `usages` Usage[], nullable — List of 'Usage' products that the subscription is subscribed to. - `id` string, uuid — Unique identifier of the usage product. - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `smokeballId` string, nullable — Unique Smokeball identifier of the usage product. - `productSuite` string, nullable — The product suite that this usage product belongs to. - `iconIdentifier` string, nullable — Icon identifier for the product. - `name` string, nullable — The display name of the usage product. - `description` string, nullable — The description of the usage product. - `trialPeriodDays` integer, nullable — The number of days the usage product can be trialed for. - `prices` Price[], nullable — The chargeable metered price options for the usage product. - `id` string, nullable — The internal price id. - `externalPriceId` string, nullable — The external price id. - `default` boolean — Returns `true` if the price is the default price. - `active` boolean — Returns `true` if the Price is active. - `type` string — The type of price. - `name` string, nullable — The price display name. - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents). - `interval` string — Recurring payment interval type. - `createdDate` string, date-time — The created date of the usage product. - `updatedDate` string, date-time — The updated date of the usage product. - `discounts` SubscriptionDiscount[], nullable — List of Discounts (promotions) applied to the subscription. - `promotion` SubscriptionPromotion - `id` string, uuid — Unique identifier of the promotion. - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `productSuite` string, nullable — The product suite that this promotion belongs to. - `tiers` Tier[], nullable — List of tiers this promotion can be applied to. If tiers and add-ons are both empty, the promotion can be applied to any tier or add-on. - `id` string, uuid — Unique identifier of the tier. - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `smokeballId` string, nullable — Unique Smokeball identifier of the tier. This identifier convenience purposes only and should not be used to interact with the subscriptions API. - `productSuite` string, nullable — The product suite that this tier belongs to. - `name` string, nullable — The display name of the tier. - `description` string, nullable — The description of the tier. Can be used to describe the tier to a customer. - `trialPeriodDays` integer, nullable — The number of days the tier can be trialed for. Cannot be trialed if zero or missing. - `prices` Price[], nullable — The price options for the tier. - `id` string, nullable — The internal price id. - `externalPriceId` string, nullable — The external price id. - `default` boolean — Returns `true` if the price is the default price. - `active` boolean — Returns `true` if the Price is active. - `type` string — The type of price. - `name` string, nullable — The price display name. - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents). - `interval` string — Recurring payment interval type. - `createdDate` string, date-time — The created date of the tier. - `updatedDate` string, date-time — The updated date of the tier. - `addOns` AddOn[], nullable — List of add-ons this promotion can be applied to. If tiers and add-ons are both empty, the promotion can be applied to any tier or add-on. - `id` string, uuid — Unique identifier of the add-on. - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `self` Link - `id` string, nullable - `href` string, nullable - `relation` string, nullable - `method` string, nullable - `smokeballId` string, nullable — Unique Smokeball identifier of the add-on. This identifier convenience purposes only and should not be used to interact with the subscriptions API. - `productSuite` string, nullable — The product suite that this add-on belongs to. - `name` string, nullable — The display name of the add-on. - `description` string, nullable — The description of the add-on. Can be used to describe the add-on to a customer. - `trialPeriodDays` integer, nullable — The number of days the add-on can be trialed for. Cannot be trialed if zero or missing. - `prices` Price[], nullable — The price options for the add-on. - `id` string, nullable — The internal price id. - `externalPriceId` string, nullable — The external price id. - `default` boolean — Returns `true` if the price is the default price. - `active` boolean — Returns `true` if the Price is active. - `type` string — The type of price. - `name` string, nullable — The price display name. - `amount` number, double, nullable — The per unit amount for this pricing option for the specified interval (in cents). - `interval` string — Recurring payment interval type. - `createdDate` string, date-time — The created date of the add-on. - `updatedDate` string, date-time — The updated date of the add-on. - `usage` string[], nullable — Intended usage type for this promotion. * Manual - Promotion can be applied manually at any time (with a code). * Trial - The promotion can be used for trialing tiers or add-ons. * CancelRetention - The promotion can be used when the user is trying to cancel their subscription. * DowngradeRetention - The promotion can be used when the user is trying to downgrade their subscription. * Signup - The promotion can be used on sign up. - `name` string, nullable — Display name of the promotion. - `description` string, nullable — Description of the promotion. - `durationDays` integer, nullable — Number of days the promotion applies for. For example, if the promotion is a trial promotion, how many days the associated tier or add-on will be trialed for. - `amountOff` integer, nullable — Fixed amount off (in cents). Only one of AmountOff or PercentOff will be set. - `percentOff` number, double, nullable — Percentage discount. Only one of AmountOff or PercentOff will be set. - `active` boolean — Whether the promotion is currently valid and can be applied. - `numUsed` integer — Number of times this promotion has been used. - `createdDate` string, date-time — When the promotion was created. - `expirationDate` string, date-time, nullable — When the promotion expires. Null if the promotion does not expire. - `codes` PromotionCode[], nullable — List of promotion codes associated with this promotion. - `id` string, nullable — Unique identifier of the promotion code. - `name` string, nullable — Display name of the promotion code. - `description` string, nullable — The description of the promotion code. - `code` string, nullable — The actual code that customers can use. - `active` boolean — Whether this promotion code is currently active. - `minimumAmount` integer, nullable — Minimum amount in cents required to apply this promotion code. - `firstTimeCustomersOnly` boolean — Whether this code can only be used by first-time customers. - `limit` integer, nullable — Maximum number of times this code can be used. Null means unlimited uses. - `createdDate` string, date-time — When the promotion code was created. - `expiratonDate` string, date-time, nullable — When the promotion code expires. Null if the code does not expire. - `metadata` object, nullable — Additional metadata associated with the promotion code. - `metadata` object, nullable — Additional metadata associated with the promotion code. - `isPersistent` boolean — Whether the promotion persists across tier switches. For example, if a BILL only promotion is applied to the subscription and the firm upgrades to BOOST, the Promotion should be deactivated. * If the promotion is non-persistent, it should be removed completely. * If the promotion is persistent and the firm reverts back to BILL at a later date, the promotion should automatically be reactivated. - `isFree` boolean — Whether this promotion makes the targeted tier or add-on free. - `deleted` boolean, nullable — Whether this promotion has been deleted. - `activationDate` string, date-time, nullable — The date the discount was activated. - `expirationDate` string, date-time, nullable — The date the discount will expire. - `status` string, nullable — Current status of the subscription. If missing, then the firm does not have a platform subscription. Possible values: Trialing, Active, Canceled, PastDue, Unpaid, Incomplete, IncompleteExpired. - `interval` string, nullable — Current billing interval of the subscription. Derived from the tiers billing interval. Returns 'None' if a tier is not associated to this subscription. Currently only Monthly and Yearly are supported. Possible values: None, Daily, Weekly, Monthly, Yearly. - `quantity` integer, nullable — The number of user licenses for this subscription. - `createdDate` string, date-time, nullable — The created date of the subscription. - `trialStatus` string, nullable — The trial status of the subscription. * None - The subscription is not trialing a tier or add-on. * Trialing - The subscription is in its trial phase (on signup) or a promotion is applied and a tier or add-on is being trialed. - `trialPeriodStartDate` string, date-time, nullable — The trial period start date of the subscription. Used in conjuction with the trial period end date to determine if the subscription is currently in trial mode. Null if the subscription is not in trial mode. - `trialPeriodEndDate` string, date-time, nullable — The trial period end date of the subscription. Used in conjuction with the trial period start date to determine if the subscription is currently in trial mode. Null if the subscription is not in trial mode. - `currentPeriodStartDate` string, date-time, nullable — The start date of the subscription. - `currentPeriodEndDate` string, date-time, nullable — The end date of the subscription. - `cancellationStatus` string, nullable — The cancellation status of the subscription. * None - The subscription is not canceled and no cancelation requests have been made. * Pending - The subscription has been canceled and will be canceled at a later date. * Canceled - The subscription has been canceled. Possible values: None, Pending, Canceled. - `cancellationType` string, nullable — Represents the most recent cancellation type for the subscription. This can be used alongside the CanceledAt and CancelAt properties to determine the cancellation status and timing. * PeriodEnd - Subscription will be canceled at the end of the billing cycle. * Immediate - Subscription was canceled immediatly. * Date - If not already canceled, the subscription will be canceled at the 'CancelAt' date. Possible values: PeriodEnd, Immediate, Date. - `canceledAt` string, date-time, nullable — If the subscription has been canceled, the date of that cancellation. Otherwise, the date of the cancel request. - `cancelAt` string, date-time, nullable — A date in the future at which the subscription will automatically get canceled and the status will change to 'Canceled'. ## Other responses - `404` — When subscription with specified id does not exist. - `500` — When an error occurs while retrieving the subscription. --- [API](https://skmtc.net/smokeball/apis/api.md) · [All operations](https://skmtc.net/smokeball/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smokeball/api/versions/197984da9b42/schema)