Coupons

Discount codes that adjust an order's price before payment is collected.

Overview

Coupons are created per application in the admin dashboard and distributed by the merchant. Each coupon is one of:

Type	Effect
Percentage off	Reduces the order amount by N%
Fixed price	Overrides the order amount with a set price in a specific currency

A code can be redeemed in two places:

At purchase creation — pass the coupon field to POST /api/purchases/create/.
On the pending order page — the customer opens the order URL (/purchases/{id}), enters the code, and clicks Apply. The order's pricing is rebuilt with the discount before the customer continues to PayPal.

The PayPal order is only created when the customer clicks Pay with PayPal, so a coupon applied on the order page always reaches the payment collector at the adjusted price. If a coupon was applied after a PayPal order already existed, the stale order is discarded and a fresh one is created at the new price on the next pay click.

Redemption Rules

A code is accepted when all of the following hold:

The coupon belongs to the same application as the order.
The coupon is active — not archived. Archived coupons are dead: they cannot be redeemed and stop discounting renewals.
The coupon has not passed its expiry date (expired).
The coupon was not created by the purchasing account (self-referral guard).
The order is still PENDING (a paid, expired, or canceled order cannot take a coupon).

Failed redemptions on the order page show an inline error; the order is unchanged.

Duration (Subscriptions)

duration controls how many invoices of a subscription the discount applies to:

Duration	Behavior
Forever (default)	Every invoice of the subscription is discounted
First invoice only (`1`)	Only the invoice the coupon was applied to; renewals bill at full price
First N invoices (`N`)	The first N invoices carrying the coupon; later renewals bill at full price

Duration is evaluated per subscription: it counts the subscription's paid invoices that carry the coupon, not global redemptions. A coupon applied mid-subscription (e.g. at the 5th invoice) with duration = 3 discounts invoices 5–7.

Renewals

When a subscription renews, the most recent coupon on the subscription is carried forward to the new invoice only while the coupon continues:

it is not archived,
it is not expired, and
the subscription has not used up the coupon's duration.

Otherwise the renewal bills at full price. Note that expiry is calendar-based and cuts off all subscribers at the same moment. To give each customer a discount for their first year, use duration (e.g. 12 monthly invoices) — use expiry for "this code cannot be used or continue past the promo season."

100% Discounts

A coupon that reduces the order amount to zero resolves the order immediately: no payment gateway is engaged and the order becomes PAID (same behavior as free-tier products).

Killing a Discount

Archiving a coupon (admin dashboard → Coupons → Archive) is the kill switch: it blocks new redemptions and stops the discount on every subscription still renewing with that code.