--- title: "Get promotion" method: GET path: "/subscriptions/promotions/{id}" tags: ["Subscription Promotions"] --- # Get promotion `GET /subscriptions/promotions/{id}` ## Request - Base URL: `https://api.smokeball.com` - URL: `https://api.smokeball.com/subscriptions/promotions/{id}` - Auth: API key in header `x-api-key` and API key in header `Authorization` Retrieves detailed information for a specific promotion. ## Path parameters - `id` string, uuid, required ## Response `200` When request is successful. Returns a 'SubscriptionPromotion' object. - 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, Archie tiers, and add-ons are all empty, the promotion can be applied to any product. - `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 the pricing option. - `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: The interval of the price. - `createdDate` string, date-time: The created date of the tier. - `updatedDate` string, date-time: The updated date of the tier. - `archieTiers` ArchieTier[], nullable: List of Archie tiers this promotion can be applied to. If tiers, Archie tiers, and add-ons are all empty, the promotion can be applied to any product. - `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 the pricing option. - `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: The interval of the price. - `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, Archie tiers, and add-ons are all empty, the promotion can be applied to any product. - `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 the pricing option. - `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: The interval of the price. - `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. ## Other responses - `400`: When promotion with specified id does not exist or is not valid. - `500`: When an error occurs while retrieving promotion. ## Changes - **2026-10-28** `2fe552c5d11d`: 1 info - added the optional property `archieTiers` to the response with the `200` status [Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/subscriptions/promotions/:id/get.md) --- [API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)