Discounts
A discount is a temporary or permanent reduction in price that can be applied when creating a subscription. A discount can be scoped to a Metered Component, an Add-on, or the entire invoice. If you haven’t already, we recommend reading the Subscription and Price Plan documentation before understanding discounts.
Discounts are useful when the primary goal is to create subscriptions for specific customers with a certain discount applied to the price plan. This allows for the customer to have a permanent or temporary recurring discount that will always apply to the entire invoice or a certain line item.
For ephemeral and non-recurring discounts that are more custom, we recommend creating coupons.
Discounts can be applied when creating a subscription or updating an existing subscription. Simply go to the customer’s page and create/edit the subscription. Then click the Add Discount button in the discount section of the modal:
Discounts can be scoped to the revenue generated by a specific Add-on. The Add-on must be on the price plan, but does not have to be added to the subscription. Simply select “An Add-on” and then provide the name of the Feature that the Add-on refers to:
Discounts can also be scoped to the revenue generated by a Metered Component. If the Metered Component has labels, the labels chosen must exactly match one of the sets of labels defined on the price list. This means that a value must be provided for each label key. Simply select “A Metered Component”, choose the desired one from the next drop-down, and select a value for each label:
For more detail on what labels you can provide for a Metered Component Discount, see below. Given the following price list csv:
The following labels inputs would be valid:
The following labels inputs would be invalid:
The duration of the discount, in units of billing cycle length, can be specified using billing_cycle_duration. Billing cycle length is determined by price plan period. For example, if the price plan period is month and the billing_cycle_duration is 2, the discount will last 2 months. For permanent discounts this field should be null.
The start date of the discount can be specified using billing_cycle_start_offset. Similar to billing_cycle_duration, this provides an offset in units of billing cycle length before the discount is applied to the subscription. For example if the price plan period is month and the billing_cycle_start_offset is 1, the discount will start applying in the next month. If set to 0, the discount will be applied immediately.
- If a subscription is deleted, its active discounts will expire at the same time the subscription expires.
- If a subscription is updated, its discounts do not carry over into the new subscription, and will expire when the initial subscription expires.
- If a subscription is updated_in_place with new discounts, the existing discounts will expire at the start of the current billing cycle. The new discounts will be effective at the start of the current billing cycle.
You can apply multiple discounts to a single subscription. However, multiple discounts cannot be applied to the same line item at the same time. For example, two discounts cannot be applied to the same add on or the same set of labels on a metered component. Additionally, there can only be one INVOICE_TOTAL discount on a subscription active at a time.
However, as discounts can be temporary, it is possible to have one discount for a line item in one billing cycle, and then replace it with a different discount for the line item in the next billing cycle.
When computing the discounted revenue, we first apply the scoped discounts, and then apply the invoice total discount (if there is one) to the total revenue minus the amount discounted by the scoped discounts.