Stripe Subscriptions

Cobalz tracks Stripe-billed subscriptions for recurring commissions: a single referral earns the affiliate a cut of the subscription on the first month, every renewal, or for the first N renewals — whichever you configure.

Setup

• In Stripe Dashboard: create a Cobalz Affiliate webhook endpoint pointing at https://affiliate.cobalz.com/api/stripe/merchant-webhook/<merchant_id>.
• Subscribe to events: checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, charge.refunded.
• Copy the signing secret. Paste it in your Cobalz dashboard at Settings → Store connection → Stripe webhook secret.

Attribution flow

Pass the affiliate ref through Stripe Checkout via metadata:

// Server-side, when creating a Checkout session:
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [...],
  metadata: {
    cobalz_ref: req.cookies._cobz_ref,        // affiliate slug
    cobalz_session: req.cookies._cobz_sess,   // tracker session id
  },
});

At checkout.session.completed, we read the metadata and stamp the subscription with the affiliate. Every subsequent invoice.paid creates a recurring commission row.

Recurring strategies

• first_order_only — commission on the first invoice. Renewals are free.
• all_renewals — commission on every paid invoice, forever.
• first_n_renewals — commission on the first recurring_commission_max_renewals (default 12).

Refunds + chargebacks

charge.refunded triggers the same 3-branch clawback decision tree as WooCommerce. Chargebacks (charge.dispute.created with reason fraudulent) auto-void the commission.