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

is_start_prorated

ONLY applicable if the 'discount_type' is PERCENT.

If TRUE, start the coupon application when it is applied. Otherwise, start at the start of the current billing cycle (see example below).

Boolean

Optional (by default this is false and the coupon will apply from beginning of current billing cycle)

is_end_prorated

ONLY applicable if the discount_type is PERCENT.

If TRUE, end the coupon application when the duration is reached. Otherwise, defer until the end of the billing cycle. (see example below).

Boolean

Optional (by default this is false and the coupon will end on the last day of the duration billing cycle)

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 provide greater flexibility due to proration. This is shown in the diagram below. The diagram below assumes that the customer's price plan period is month, they have received a "20% Off" coupon with a 'duration' of 2 months, and the coupon was applied on February 15th. The behavior of the the coupon will be based on the 'is_start_prorated' and 'is_end_prorated' parameters.

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.


Did this page help you?