A discount defines a series of Discount Periodicities. Each discount periodicity will be processed in order, and only when all defined discount periodicities are complete will the Account be charged the recurring periodicity defined by the Plan.
Discounts can be applied to multiple plans (through Offers). As such, you should be mindful of how you define discount periodicities (e.g., it is unlikely you will want to connect a discount that sets the price of the first term to $1 with an annual plan).
Discount Periodicity
A discount periodicity can either inherit its pricing scheme from the underlying plan, or define a bespoke periodicity.
If you want the length of the discount periodicity to match that of the underlying plan, it will be of type inherit (e.g., "save 50% for the first month"). If you want to ensure that a specific time period is always honored, it will be of type bespoke (e.g., "pay $1 for the first 60 days").
Bespoke discount periodicities can be used to offer free trials. To create a 30-day free trial, create a bespoke discount periodicity where type=day, duration=30, and cents=0.
If a discount periodicity is of type inherit, the underlying data model will be a Savings Object . The savings object will apply the desires savings amount against the defined periodicity of the plan for as many payment cycles as you want.
Attributes:
| Name | Type | Description |
|---|---|---|
| type | string | One of: bespoke or inherit. |
| bespoke | object | Embedded Periodicity Object. This attribute is only set if type is to bespoke. |
| inherit | object | Embedded Savings Object. This attribute is only set if type is set to inherit. |
Savings
The savings object cannot exist by itself: rather, it is attached to a baseline periodicity.
Savings objects are usually inferred from an underlying Plan .
Savings of type fixed-discount are used to always reduce the base periodicity's cents by the defined amount. E.g., if you wanted to let someone save $5 for the next 3 billing cycles, you would create a Savings where type=fixed-discount, amount=500, and cycles=3.
Savings of type fixed-price are used to directly overwrite the base periodicity's cents. E.g., if you wanted to let someone pay $0.99 for the next 3 billing cycles, you would create a Savings where type=fixed-price, amount=99, and cycles=3.
Savings of type percent are used to reduce the base periodicity's cents by the percentage defined by the amount. E.g., if you wanted to let someone save 25% for the next 3 billing cycles, you would create a Savings where type=percent, amount=25, and cycles=3.
It is impossible to charge a negative amount. If a savings is attached with a fixed-discount of 500, but the baseline periodicity only charges 399, the billing cycle will simply be skipped (effectively, the Account will be charged 0 cents).
Attributes:
| Name | Type | Description |
|---|---|---|
| type | string | One of: fixed-discount, percent, or fixed-price. |
| amount | integer | If this is a fixed-discount this is the number of cents to discount from the regular recurring price.If this is a fixed-price, this is the number of cents to charge for each period.If this is a percent, it is the percentage (as an integer) to discount (e.g., "Save 25%" would be encoded as a percent with an amount of 25). |
| cycles | integer | How many billing cycles to apply the defined savings. A value of 0 will create a never-ending discount. |