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:

A code can be redeemed in two places:

1. At purchase creation — pass the coupon field to POST /api/purchases/create/.
2. 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 and has not been archived immediately or on its scheduled archive date.
• The coupon has not passed its redemption 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.

Expiry and Archive Dates

The Redemption Expiry Date is the last day customers can apply the code to a new purchase. Expiry does not remove the discount from subscriptions that already redeemed it.

The optional Archive Date ends renewal discounts after that day. Leave it blank to let existing subscriptions keep the discount until the coupon is archived manually, its duration is used up, or its plan no longer matches the coupon's scope. Both dates include the selected day through 11:59:59 PM.

Subscription Plan Scope

In the admin dashboard, choose which purchases can use a coupon. The default, Any purchase, preserves the original behavior. Other choices are:

Scope is checked both when a coupon is redeemed and when a subscription renews with that coupon. If a subscription changes to a plan outside the coupon's scope, its next invoice is charged without the coupon. Broad scopes automatically include future matching products; specific-plan scopes must be updated when the eligible plans change.

Duration (Subscriptions)

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

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;
• the subscription has not used up the coupon's duration; and
• the subscription's current plan is still within the coupon's scope.

Expiry does not stop a renewal discount. A scheduled archive date or the manual Archive action does. To give each customer a discount for their first year, use duration (e.g. 12 monthly invoices); use expiry to close the code to new customers after a promotion.

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

The Archive Date schedules when a coupon stops being usable and when existing subscription discounts end. The admin dashboard's Archive action does both immediately. Existing coupons retain their previous behavior: their current expiry date is also used as their archive date.