How do you preserve affiliate attribution when a Stripe subscription plan changes?
Short answer: Store the original referral against your own stable customer or account ID, map that identity to the Stripe customer and subscription, and keep the mapping when the customer upgrades or downgrades. Process verified billing events to determine whether the change creates eligible commissionable revenue. Do not infer a new referral from a plan change or pay commission merely because customer.subscription.updated fired.
Stripe Billing supports changing a subscription's price, quantity and billing period, sometimes creating prorations and invoices. The Stripe customer portal can also let customers manage plans. These changes are normal lifecycle events for an existing customer, not new acquisitions. See our free-trial-to-paid attribution guide for how to capture the original partner identity.
Keep the referral mapping outside the changing plan
A reliable data model links internal_account_id to stripe_customer_id, stripe_subscription_id, affiliate_id, referral_id and a versioned attribution rule. A subscription can contain different prices over its lifetime, and customers may switch from monthly to annual billing. Do not use a Stripe price ID as the referral's primary identity.
Persist referral origin, original timestamp and allowed attribution window at signup. When a customer changes email or completes a plan change in another browser, the affiliate mapping should remain stable. When an account transfers ownership, follow a documented ownership policy instead of overwriting the historical source without a review.
Minimum fields for each commissionable event
| Field | Purpose |
|---|---|
| account_id, affiliate_id | Stable relationship to the original referral |
| stripe_customer_id, subscription_id | Connect billing lifecycle to the account |
| invoice_id, invoice_line_id | Identify the specific qualifying charge or credit |
| event_id, event_type | Audit and webhook delivery deduplication |
| eligible_amount, currency | Commission calculation in minor currency units |
| rule_version, commission_status | Reproduce approvals and reversals |
Understand how Stripe handles upgrades and downgrades
Stripe's subscription modification documentation distinguishes billing-related updates, such as changing prices or quantities, from non-billing updates, such as metadata changes. Billing-related updates can generate prorations. Stripe also offers proration previews and pending updates for changes whose payment must succeed before taking effect.
A price upgrade may produce a credit for unused time on the old plan and a charge for remaining time on the new plan. Depending on the request and billing settings, the financial impact may appear on an immediate invoice or later. A downgrade can produce a credit instead of positive incremental revenue. The commission engine must read the actual invoice lines and their settlement state, not calculate a reward from the displayed difference between plan prices.
Illustrative proration calculation
Suppose a customer originally pays $40 per month, then upgrades to $80 per month halfway through the billing period. For illustration, the old plan yields a $20 unused-time credit and the new plan yields a $40 remaining-time charge. The net additional amount is $20. If the affiliate agreement pays 20% on positive incremental eligible revenue, the resulting commission is $4 after the qualifying invoice is paid. The commission is not $16 based on the full $80 price.
This example ignores taxes and discounts for clarity. Real calculations depend on exact billing timestamps, proration settings, coupons and invoice composition. Treat Stripe's computed invoice as the authoritative financial source.
Use the right Stripe events for attribution and payment
Stripe documents customer.subscription.updated for subscription changes and invoice events for billing outcomes. Its subscription webhook guide
- Receive the subscription change event and associate it with the existing account and affiliate mapping.
- Fetch the updated subscription or invoice as needed, using the correct API version.
- Inspect invoice lines for prorations, discounts, taxes and eligible products.
- On the appropriate paid-invoice event, confirm collected eligible revenue and any outstanding adjustments.
- Calculate commission using the original attribution and current rule version.
- Write a pending commission with a unique business key and move it through review and approval.
Webhook deliveries can repeat or arrive out of order. Store event IDs for delivery deduplication and separately enforce uniqueness on the commission's invoice or line-level business key. If a paid invoice arrives before an internal customer mapping is available, queue a retry instead of crediting an unknown partner.
Customer portal changes need the same controls
Whether a plan change originates from your API, a sales representative or the Stripe customer portal, the same commission rules should apply. The portal is an interface for customer actions, not a new attribution channel. Avoid relying on the browser redirect after the portal session to calculate financial rewards; use verified server-side billing data.
Stripe's customer management documentation
Special cases worth testing
Pending update and failed payment
A plan change that depends on a new invoice can fail payment. Do not award incremental revenue commission before the required payment succeeds. Check the final subscription and invoice state before provisioning or paying.
Annual billing and commission caps
Moving from monthly to annual can produce a larger single invoice. Apply the affiliate agreement's duration, cap and eligible revenue definition consistently. A large cash receipt is not automatically equivalent to twelve newly acquired customers.
Stripe API version changes
Stripe's Basil API change moved billing period fields to subscription items for that version. Integration code should read fields according to the configured API version rather than assuming every account returns the same subscription shape.
Refunds and chargebacks
Keep adjustment records linked to the original invoice and commission. A later refund may reverse part of an approved commission according to the written policy. Never delete a paid entry silently; add a linked correction. Our recurring commission tracking guide
Implementation QA checklist
- Change plans through both API and customer portal where enabled.
- Test an immediate upgrade invoice and a deferred proration.
- Verify no commission on a zero-charge metadata update.
- Simulate a failed payment and a later successful retry.
- Replay subscription and invoice webhooks without duplicate rewards.
- Test a downgrade credit and a subsequent renewal invoice.
- Test annual conversion with discount and tax exclusions.
- Reconcile affiliate ledger entries to Stripe invoice IDs and paid amounts.
Frequently asked questions
Does changing a Stripe price reset affiliate attribution?
Not if your system stores attribution independently of the price and retains the customer mapping. Stripe itself does not define your affiliate policy.
Is customer.subscription.updated proof of paid revenue?
No. Inspect the actual invoice and qualifying payment state before awarding revenue-based commission.
Should downgrades create negative commission?
Only under the written program policy. A credit and a cash refund are not always the same event, so reconcile them carefully.
Sources and editorial disclosure
- Stripe: modify subscriptions
- Stripe: subscription webhooks
- Stripe: customer portal
- Stripe: API version billing-period changes
Official documentation reviewed 31 October 2026. Numerical examples are hypothetical. This is an editorial implementation guide, not a hands-on integration test or accounting advice.