v2

latestOpenAPI 3.0.12026-07-262352981007.0 KB

Subscription Promotions

Get promotion

Retrieves detailed information for a specific promotion.

get/subscriptions/promotions/{id}

Path parameters

idstring uuid required

The unique identifier of the promotion

Response

When request is successful. Returns a 'SubscriptionPromotion' object.

idstring uuid

Unique identifier of the promotion.

hrefstring nullable

relationstring nullable

methodstring nullable

productSuitestring nullable

The product suite that this promotion belongs to.

usagestring[] 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.

namestring nullable

Display name of the promotion.

descriptionstring nullable

Description of the promotion.

durationDaysinteger 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.

amountOffinteger nullable

Fixed amount off (in cents). Only one of AmountOff or PercentOff will be set.

percentOffnumber double nullable

Percentage discount. Only one of AmountOff or PercentOff will be set.

activeboolean

Whether the promotion is currently valid and can be applied.

numUsedinteger

Number of times this promotion has been used.

createdDatestring date-time

When the promotion was created.

expirationDatestring date-time nullable

When the promotion expires. Null if the promotion does not expire.

metadataobject nullable

Additional metadata associated with the promotion code.

isPersistentboolean

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.

isFreeboolean

Whether this promotion makes the targeted tier or add-on free.

deletedboolean nullable

Whether this promotion has been deleted.

Example response

{
  "id": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
  "tiers": [
    {
      "id": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
      "name": "Intake",
      "prices": [
        {
          "default": true,
          "active": true,
          "type": "Recurring",
          "name": "\"$109 per user/month\"",
          "amount": 5900,
          "interval": "Monthly"
        }
      ],
      "createdDate": "2022-04-23T14:00:00Z",
      "updatedDate": "2022-04-23T14:00:00Z"
    }
  ],
  "addOns": [
    {
      "id": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
      "name": "Intake",
      "prices": [
        {
          "default": true,
          "active": true,
          "type": "Recurring",
          "name": "\"$109 per user/month\"",
          "amount": 5900,
          "interval": "Monthly"
        }
      ],
      "createdDate": "2022-04-23T14:00:00Z",
      "updatedDate": "2022-04-23T14:00:00Z"
    }
  ],
  "name": "Summer Sale 2024",
  "description": "Summer Sale 2024",
  "durationDays": 7,
  "amountOff": 2000,
  "percentOff": 20.5,
  "numUsed": 42,
  "createdDate": "2024-01-15T10:00:00Z",
  "expirationDate": "2024-12-31T23:59:59Z",
  "codes": [
    {
      "id": "promo_code_1234",
      "name": "SUMMER2024",
      "description": "100% discount!",
      "code": "SUMMER2024",
      "minimumAmount": 5000,
      "limit": 100,
      "createdDate": "2024-01-15T10:00:00Z",
      "expiratonDate": "2024-12-31T23:59:59Z"
    }
  ]
}