---
title: "Get subscription promotions"
method: GET
path: "/subscriptions/{id}/promotions"
tags: ["Subscriptions"]
---

# Get subscription promotions

`GET /subscriptions/{id}/promotions`

Retrieves promotions available for the specified subscription.

## Path parameters

- `id` string, required

## Query parameters

- `Offset` integer
- `Limit` integer

## Response `200`

When request is successful. Returns a paged collection of 'SubscriptionPromotion' objects.

- SubscriptionPromotionPagedCollection
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable
  - `self` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `value` SubscriptionPromotion[], nullable
    - `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.
  - `offset` integer, nullable
  - `limit` integer, nullable
  - `size` integer
  - `first` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `previous` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `next` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `last` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable

## Other responses

- `404` — When subscription with specified id does not exist.
- `500` — When an error occurs while retrieving the subscription promotions.

---

[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)