How to handle Stripe affiliate commissions on refunds, upgrades and downgrades

A Stripe affiliate commission is a percentage of the cash a customer paid and kept.

Stripe Billing records the payment on invoice.paid, so create the commission there, base it on the pre-tax amount, and shrink it in proportion on charge.refunded, which covers partial refunds too.

With cash as the base, upgrades, downgrades and coupons adjust it through Stripe's own invoice math, and cancellation only stops future commissions.

The worked examples below cover a refund that cuts a $60.00 commission to $40.00 and an upgrade from $99 to $299 that pays $125.87 across 90 days.

The numbers rest on Stripe's 2026 documentation for 8 webhook events, and the last section shows where TrackRev differs.

How should a Stripe affiliate commission react to each event?

Eight Stripe event types touch a commission, and the table sets the action for each. Of the 8 rows, 4 change the amount (invoice.paid, charge.refunded, refund.failed and the dispute pair) and 2 trigger nothing (invoice.payment_failed and checkout.session.completed).

The trigger is invoice.paid, which means Stripe collected the money, and checkout completion is not that signal. checkout.session.completed can fire before money moves in Stripe Checkout. Stripe's fulfillment guide gives ACH Direct Debit as an example, with checkout.session.async_payment_succeeded following later.

In Stripe Checkout, pay on invoice.paid for subscriptions and payment_intent.succeeded for one-time payments.

The refund trigger is charge.refunded, the event Stripe describes as covering partial refunds. The charge.refund.updated event fires only on selected payment methods, so a handler built on it alone can miss them.

Stripe's webhook documentation adds that an endpoint can receive the same event twice and that live deliveries retry for up to 3 days, so recompute from current totals and key each write on an ID.

The guide to affiliate refund clawbacks covers replays, disputes and holds.

How does refund math work with tax on the invoice?

Refund math with tax means scaling the commission by the share of the charge the customer kept.

Tax belongs to the tax authority, so a commission on the gross charge overpays the affiliate by the tax rate, while a refund is gross because it returns the tax too.

Take a $300.00 invoice plus $30.00 of sales tax from Stripe Tax, a 20% commission of $60.00 on the pre-tax amount, and two refunds against the $330.00 charge.

Scaling needs no tax lookup, because the commission was already pre-tax. Reversing 20% of each refund takes back $22.00 and $44.00, which is $6.00 more than the $60.00 credited.

The scaled method assumes a refund returns the $300.00 pre-tax amount and the $30.00 tax in the original ratio. Floor the result at $0.00 either way.

1async function onChargeRefunded(event) {2  const charge = event.data.object; // amount_refunded is the running total3  const commission = await findCommissionByCharge(charge.id);4  if (!commission) return; // not an affiliate sale5 6  const kept = 1 - charge.amount_refunded / charge.amount;7  const next = Math.max(0, Math.round(commission.original_cents * kept));8 9  // event.id is the idempotency key: a repeat delivery changes nothing10  if (next !== commission.current_cents) {11    await setCommission(commission.id, next, event.id);12  }13}

How do upgrades and downgrades change the invoice?

A proration is a credit or debit line that Stripe adds to an invoice when a plan changes.

By default, create_prorations adds a credit line for unused time on the old price and a debit line for the remaining time on the new one, and bills neither at once.

Setting always_invoice bills an upgrade immediately, per the subscription update reference. A downgrade sends no refund: the proration guide says negative prorations are not automatically refunded, and the customer balance guide lists them as credit against the next invoice.

With no charge.refunded event, the affiliate keeps the larger $299 plan's commission.

Take one customer: a $99 plan upgraded to $299 on day 15 of a 30-day cycle, then dropped back to $99 on day 50.

Should a commission follow cash or the plan price?

A commission should follow cash, not the plan price. With always_invoice on the upgrade, the $100.00 is invoiced on day 15 and the day 30 invoice is $299.00, so the commission total stays $125.87 and only the timing moves.

The plan-price rule is $20.00 short on the upgrade and pays $13.33 on credited money at the downgrade, so across 90 days the cash rule pays $125.87 and the plan-price rule $119.20, a $6.67 gap from two errors pulling in opposite directions.

in our experience building TrackRev I would pay on cash, because Stripe has already done the proration arithmetic and a plan-price rule makes you redo it. In your own code the cash figure is amount_paid less the invoice's tax.

To exclude proration, read parent.subscription_item_details.proration on each invoice line.

When does the subscription event matter?

The customer.subscription.updated event is the Stripe webhook that matters when a rule depends on the plan. A percentage of cash needs no plan lookup, but per-plan rates, a tier bonus or a cap such as the first 12 months do.

For example, a 30% rate on the $299 plan and 20% on the $99 plan needs the price ID from this event.

Stripe's subscription webhook guide says customer.subscription.updated also fires for renewals, coupons and added invoice items, so diff previous_attributes against the new object, which per the event object reference holds the whole array when part of one changes.

1function planChange(event) {2  const before = event.data.previous_attributes?.items?.data?.[0]?.price?.id;3  const after = event.data.object.items.data[0].price.id;4  // renewals and coupons arrive here too, with no price change5  return before && before !== after ? { before, after } : null;6}

What happens on annual switches, cancellations and failed renewals?

An annual switch in Stripe Billing bills the new price at once. Stripe's price change guide says that when two prices have different billing intervals, the new price bills from the day of the change.

Take a customer on $99 a month who moves to $990 a year on day 10 of 30.

No invoice follows for 12 months, so a rule that pays 12 months of recurring commission is met by that one payment. Count the window in months of service, because counting invoices pays the annual customer 12 times over.

The customer.subscription.deleted event reverses nothing, because only money returned to the customer undoes a paid invoice. A declined renewal needs no hold in Stripe Billing when commissions are created on invoice.paid, and Stripe marks the subscription past_due while it retries.

How do you test these cases with Stripe test clocks?

A Stripe test clock is a sandbox clock that moves a customer through billing cycles in minutes, so the 6 tests below can cover 90 days of invoices on a $99 plan.

Stripe's test clock simulations advance time in a Stripe sandbox by up to 2 billing intervals per step, so a monthly subscription jumps up to 2 months, and the Run simulation button is disabled for a customer attached to more than 3 subscriptions.

How do you keep channel revenue honest after refunds and upgrades?

Honest channel revenue means debiting every refund from the channel that earned the sale.

Debit a refund from the channel that earned the sale, using the model that credited it, whether last-touch, first-touch or linear, so a linear sale splits its refund across the same touches.

Credit an upgrade from the source stored against the customer, because a plan change in the Stripe Customer Portal happens on a Stripe-hosted page you cannot tag, as Stripe Customer Portal attribution explains.

Normalize annual plans to monthly figures first. Moving from $99 a month to $990 a year books $891 of expansion if counted raw, while the monthly equivalent falls from $99 to $82.50.

TrackRev copies the original click's credit onto each renewal, rescaled to the charge amount, so expansion revenue stays with the channel that brought the customer.

How do other affiliate tools handle these events?

Affiliate tools handle refunds in 2 ways: proportional recalculation, as Rewardful does, or a negative commission keyed on an event ID, as FirstPromoter does.

Rewardful's Stripe integration article says it commissions the amount the customer actually paid, after discounts and account balance debits, and recalculates from the refunded amount on full and partial refunds.

FirstPromoter's refund endpoint creates a negative commission, requires an event ID, and answers a repeat with a 409. In our comparison, Rewardful documents proportional recalculation on partial refunds, while TrackRev reverses the whole commission on a refund of any size.

FirstPromoter needs one event ID per refund, so a replay gets an HTTP 409 instead of a second debit. The Rewardful and TrackRev comparison goes further.

Sources: help.rewardful.com/en · docs.firstpromoter.com/api-reference-v2

What does TrackRev do with each case?

TrackRev is SaaS affiliate software for indie hackers and small SaaS teams, and we built TrackRev's Stripe sync to read charges, not subscription events, using a restricted API key.

Our own sync runs hourly, and an optional webhook for charge.succeeded, charge.refunded and checkout.session.completed runs it at once. The Stripe integration page lists the key permissions.

TrackRev reverses the whole commission on any refund and has no per-plan rates, so pick a tool that documents proportional reversal, as Rewardful does, if you need it.

The affiliate program needs a paid plan from Indie at $29 a month, with no cap on the commission it tracks and 0% fees. The Free plan covers link tracking only, with 50 links and 1,000 tracked events a month.

The pricing page, the affiliate program page and affiliate tracking for recurring subscriptions cover the rest.