Coupons and referrals - overview
The Promotions module in the panel (/dashboard/promotions) extends built-in offer promotions (trial, discounts) with promo codes and referral programs. Coupons are code pools the customer enters at payment. Referral programs generate unique links for active subscribers - after a successful referee payment both sides may receive a percentage discount on future subscription payments.
Two tabs in the panel
- Coupons (/dashboard/promotions/coupons) - create pools, generate or upload codes, redemption limits, archive.
- Referral programs (/dashboard/promotions/referral) - referee and referrer discount rules, limits, link and conversion stats.
Enable on an offer
After creating coupon pools or a referral program, enable them in the offer form under code redemption: select accepted coupon pools and/or a referral program. Without this step the customer will not see Promo code or referral benefits on that offer.
How codes affect subscription billing
Coupon and referral codes are redeemed after a successful payment (not at preview). Zevio stores two layers: PromotionRedemption (audit grant: which code, which payment triggered it) and subscription.subscriptionPromotions.entries (billing state for the next invoices). Each entry uses redemptionId as a grant key (redeem_{paymentId} or referrer_{refereePaymentId}) matching PromotionRedemption.idempotencyKey - not the internal redemptionId column on the grant row.
- Coupon / referee once - discount on the payment where the code was used; entry is marked consumed with consumedPaymentId = that
pay_.... - Referrer once - reward is granted when the referee pays; entry starts with
consumed: falseand applies on the referrer's next subscription payment, then consumedPaymentId records whichpay_...settled it. - Forever - stays active until program rules change; multiple referrer rewards stack up to the program cap.
- Subscription details show billingSummary.promotionPlanSteps (active/used). Payment records store only the total applied discount in
typeData, not per-code breakdown. - Webhooks:
promotion.redeemedafter code redemption (grantKey + redemptionId);referral.convertedwhen referrer reward is granted (referrer_{refereePaymentId}). See Webhooks.
Related sections
- Coupons (code pools) - discount types, duration, codes, limits.
- Referral programs - links, rewards, referrer caps.
- Offer - promotions - built-in offer promotions (trial, discounts) plus coupons/referral.
- Offer - additional charges - charge catalog and offer Charges tab.
Two modules under Promotions
Panel Promotions holds Coupon pools and Referral programs. Offer-level promotions (trial, general discount, schedule) live in the offer form → Promotions tab.
Access
Organization context only. MEMBER has no access (404 on direct URL).