Coupons
Customizable Discounts
Coupons are reusable discounts. You can specify who the discount applies to (i.e., which customers) and whether it should be applied on a recurring on non-recurring basis. Additionally, you can share coupon codes with customers so that they can apply the coupons themselves.
Coupon Definition
| Field | Description | Type | Required |
|---|---|---|---|
| name | Unique name for this coupon. | String | Required |
| discount_type | Determines whether the discount is a flat dollar amount or a percentage of the final invoice amount. One of: [ FLAT, PERCENT] | Enum | Required |
| discount_amount | The amount of discount to apply based on type. | Integer | Required |
| frequency | Whether the coupon is One of: [ONCE, RECURRING] | Enum | Required |
| duration_length | The time when the coupon will stop being effective one its applied. The duration includes the application day and hence the coupon will stop applying at duration + application day. | Integer | Optional (required when frequency is 'recurring') |
| duration_unit | The unit to use for the duration length specified. One of: [ hour, day, week, month, year] | Enum | Optional (required when 'duration_length' is specified) |
| expiration_time | The time at which this coupon will expire and can no longer be applied. This differs from 'duration' as the latter determines how long the coupon will be valid AFTER it is applied. | Datetime | Optional (by default coupons will never expire) |
| max_uses | The maximum number of such coupons that can be applied. NOTE: A coupon can only be applied by one 'customer' once. Hence this determines the number of different customers that can use this coupon. | Integer | Optional (by default there is no limit on max uses) |
| code | User-facing code that can be given out to end-customers. (e.g. SPECIAL25) | String | Optional |
| excluded_customers | List of all customers who cannot use this coupon. | [String] | Optional |
| excluded_price_plans | List of all price plans who's customers cannot use this coupon | [String] | Optional |
Frequency & Duration
The two frequencies available are ONCE and RECURRING. When the frequency is set as ONCE, the coupon will only be applied to a SINGLE price plan period and will not be applied henceforth.
When the frequency is set as RECURRING, it is important to provide the duration of the coupon lifetime, once it is applied. For example, if the coupon lasts 30 days and was applied on January 1, it will stop working on 1 + 30 = 31st January at midnight. If application date/end date of the coupon is in the middle of the price plan period, the behavior of the discount applied will vary based on discount types.
Discount Types
Flat Discounts
Flat discounts are a direct dollar amount reduced from the invoice amount at the end of the price plan period. It does not matter whether the application date or the end date are in the middle of a price plan period, the flat discount will be applied to the invoice.
For example, assume the flat discount is $100, the frequency is RECURRING with a duration of 10 days, and the customer price plan period is month. If the application date of the coupon was June 25th, the flat discount will be applied to the invoice of June as well as July. Additionally, even if the entire duration is encapsulated within one price plan period, the flat rate will apply to the entire period.
Percentage Discounts
Percentage discounts are a reduction off of a customer's invoice based on a proportion of revenue accrued. Unlike a flat discount, a percentage discount is based on the customer’s usage. For example, a 20% off coupon will remove $20 from a $100 invoice.
Restricting Coupon Access
Coupon access to customers can be restricted in two ways that can both work at the same time. The first way of restricting coupon access is to use 'max_uses' which will determine how many unique customers can use this coupon before it will not be accepted when applying. A single customer will NOT be able to apply the same coupon multiple times. The second way of restricting usage is via the expiration_timestamp which determines the last day when the coupon can still be applied.
NOTE: 'max_uses' and 'expiration_timestamp' work together and are applied on top of each other and hence the more restrictive of the two will stop coupon usage first.
Finally, if the coupon that you are creating is only meant for specific price plans or customers, you can simply exclude the ones for which this coupon will not work by specifying the 'excluded_customers' and 'excluded_price_plans' respectively. These also will be applied on top of each other and the more restriction of the will apply first.
Use Cases
Internal Uses
Coupons do not need to be exposed to customers, instead they can also be used as a way of storing common discounts that you apply on Price Plans and Subscriptions often.
External Uses
Coupons can be directly handed to customers by setting the 'code'. The 'code' will can be used by end users and an Add Coupon API call can be made to Octane in order to state that a customer has applied a coupon.
Usage of Discounts and Coupons
Discounts and Coupons cannot be applied together. A customer can either have an active coupon or an active discount but not both. This implies that if a customer has an active discount on their price plan/subscription then they will not be able to use any issues coupons.
Updated 11 months ago