Discount

A Discount reduces the amount charged for a Plan during billing. Discounts always belong to a Product of type Plan and cannot be applied to add-ons.

Scope

• A Discount cannot exist without a Plan. Only one active Discount is allowed per Plan at any time; to replace one, cancel the existing one first.
• The type is chosen at creation and cannot be changed afterwards.
• Discounts cannot outlive their Plan and do not transfer between Plans — when the customer changes Plans, create a new Discount for the new one.

Types

• amount — a fixed monetary reduction. Set amount_off and currency. Supports the is_prorated flag.
• percentage — a percentage reduction. Set percentage_off (integer). The percentage itself is never prorated; it is always applied to the actual billed Plan amount.

Both types require name and is_recurrent, and support optional metadata (for example, a coupon_id).

The final charged amount is floored at 0. Any unused portion of a fixed amount Discount is not carried over to a future cycle.

Recurrence

The is_recurrent flag controls how many billing cycles the Discount applies to:

• One-time (is_recurrent: false) — applies to a single cycle.
• Multi-cycle (is_recurrent: true, max_recurring_intervals: N) — applies for N cycles (minimum: 2). Each cycle the Discount is applied counts as one interval; it terminates at the exact cycle boundary once the last interval is reached.
• Ongoing (is_recurrent: true, max_recurring_intervals unset) — applies at every renewal until canceled or until the Plan ends.

The response includes times_used tracking how many cycles the Discount has already covered.

Lifecycle

• Applied — the Discount is active.
• Canceled — explicitly canceled through the API. Effect on the current cycle depends on the Plan type and is_prorated (see below).
• Terminated — reached its natural end (max intervals hit, one-time consumed, or Plan ended).

How a Discount is created

• Dedicated endpoint — POST /discounts with the target product_id.
• At Order creation — include a discounts array under the ordered Product in the POST /orders body.

Discounts cannot be created against a Subscription directly. The related Subscription is surfaced in the response under _embedded.subscription.

How a Discount applies

The amount deducted depends on the Plan type and, for fixed amount Discounts, on is_prorated.

Postpaid Plans

is_prorated is available on amount Discounts:

• is_prorated: true — the fixed amount is prorated by the number of days the Discount was active during the cycle.
• is_prorated: false (default) — the full nominal amount applies to the cycle, even if the Discount was active only part of it.

For percentage Discounts, is_prorated does not apply. The percentage is calculated against the actual billed Plan amount — prorated when the Plan itself is prorated, full otherwise.

Prepaid Plans

Prepaid Discounts are never prorated; is_prorated: true is not supported.

The current prepaid cycle is already paid at the moment it begins, so Discounts always take effect from the next renewal. Creating or canceling a Discount during a cycle does not recalculate the current cycle. Fixed amount Discounts apply at their full nominal value at renewal; percentage Discounts are calculated against the full renewal price.

API Reference

See the full list of endpoints, request and response schemas, examples, and version information in the Discounts section of the API Reference.