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: false and applies on the referrer's next subscription payment, then consumedPaymentId records which pay_... 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.redeemed after code redemption (grantKey + redemptionId); referral.converted when 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).

Coupons and referrals - overview | Zevio