∧pex

Coupon tracking

Partners promote with discount codes on YouTube, podcasts, Instagram, and newsletters. Apex credits them automatically — with or without a click. A coupon code is an alternative attribution path: even if the customer never clicked a partner link, using the code at checkout attributes the conversion to the partner who owns it.

How it works

  1. A partner is assigned a coupon code (e.g. SARAH20) — either auto-generated or manually set
  2. The code is synced to the merchant's payment system based on the program's couponSyncMode
  3. When a customer uses the code at checkout, Apex attributes the conversion to the owning partner
  4. The matching commission rule fires and the conversion enters the standard payout pipeline

The three sync modes

Set couponSyncMode on the program to control how codes reach the payment system.

stripe — automatic Stripe Promotion Code sync

Apex creates a Stripe Promotion Code for each partner's coupon code:

  1. Partner is assigned code SARAH20
  2. Apex calls stripe.promotionCodes.create under the merchant's Stripe account, linking the code to the program's configured Stripe Coupon
  3. Customer enters SARAH20 at Stripe Checkout → Stripe attaches the Promotion Code to the checkout.session or invoice
  4. Apex ingests the webhook event, reads the Promotion Code metadata, and attributes to Sarah

Best for: merchants using Stripe Checkout, Stripe Billing, or Stripe Payment Links.

webhook — external system fires attribution events

For merchants using non-Stripe checkout flows (Shopify, custom carts, etc.):

  1. Partner is assigned code SARAH20 in Apex
  2. Merchant configures their checkout to send a webhook to api.apex.inc/webhooks/coupon-redemption with { code: "SARAH20", orderId: "...", amountUsd: 49.99 }
  3. Apex looks up the code → finds Sarah's membership → creates the conversion

Best for: merchants with custom checkout or non-Stripe payment processors.

manual — merchant attributes conversions by hand

  1. Partner is assigned code SARAH20 in Apex
  2. Merchant tracks redemptions in their own system
  3. Merchant creates conversions via the SDK or dashboard: apex.createConversion({ couponCode: "SARAH20", amountUsd: 49.99 })

Best for: offline events, invoiced sales, or any flow where automatic sync isn't feasible.

Code generation patterns

MethodHow it works
Auto-generatedApex generates a unique code per partner per program: {HANDLE}-{RANDOM} (e.g. SARAH-7X2K). Merchant can set a prefix.
Partner-chosenPartner requests a custom code via the portal. Merchant approves or rejects.
Merchant-assignedMerchant sets the exact code in the dashboard or SDK: apex.assignCouponCode(membershipId, "SARAH20")

Codes are unique within a program. The same code string can exist in different programs without collision.

Code lifecycle

Coupon codes follow the membership lifecycle:

Membership statusCode stateStripe Promotion Code
activeActive — redeemableActive
pausedDeactivated — returns "invalid code" at checkoutDeactivated via stripe.promotionCodes.update({ active: false })
terminatedPermanently deactivatedDeactivated

When a paused membership is reactivated, the code (and Stripe Promotion Code) is re-enabled automatically.

Dual attribution

A single conversion can be attributed via both link click and coupon code. When this happens:

  1. If both point to the same partner — one conversion, one commission (no double-counting)
  2. If they point to different partners — the coupon code wins, because it represents a more intentional action (the customer typed the code)

Coupon + subscription renewals

When a customer subscribes using a coupon code, all future subscription_renewal events on that subscription are attributed to the code's owning partner — same as link-based attribution.

SDK reference

// Assign a code
await apex.assignCouponCode(membershipId, "SARAH20");

// List codes for a program
const codes = await apex.listCouponCodes(programId);

// Deactivate a code
await apex.deactivateCouponCode(membershipId);

Related

NextOverview