An upgrade can change affiliate economics in seconds. If your system only tracks the original subscription, your affiliate records and Stripe revenue will drift apart.
Rewardful affiliate upgrades work best when Stripe remains the billing source of truth and Rewardful receives the data it needs to update commissions. Your internal automation should then track access, audit records, exceptions, and payout exposure.
Build the flow around paid revenue, not around a pricing-page click or a dashboard total.
REWARDFUL AFFILIATE UPGRADES NEED TWO EVENTS
A subscription upgrade has two separate jobs. First, your product needs to recognize the customer’s new plan. Second, your affiliate program needs to calculate commission from money Stripe actually collects.
Keep Rewardful connected to Stripe
Rewardful uses Stripe activity to track referrals and calculate commissions. Its Stripe sync process receives billing updates such as invoice payments and refunds.
Rewardful also adjusts commissions when a customer upgrades, downgrades, starts a trial, cancels, or receives a refund. The commission base follows the amount paid, not the plan price shown on your site.
This matters when an affiliate refers a customer on a $29 plan who later moves to $99. The original referral can remain attached to that customer, while the paid amount changes over time.
Separate access from commission approval
Use customer.subscription.updated to update product access. Stripe documents this event for plan changes on an existing subscription.
Do not treat that event as a completed commission event. A subscription can update before Stripe collects a proration invoice. It can also change without an immediate charge.
Use invoice payment data to confirm collected revenue. Rewardful’s commission calculation guidance follows the final Stripe amount paid.
An upgraded plan is not affiliate revenue until Stripe records an eligible payment.
MAP THE STRIPE UPGRADE FLOW
Your architecture needs one source of billing truth. That source is Stripe.
Detect the plan change first
Listen for Stripe’s customer.subscription.updated event. Inspect the subscription ID, Stripe customer ID, current status, subscription items, and current Price ID.
The Price ID tells your application which entitlement to apply. Store the prior Price ID too. Without it, you can’t prove whether the event was an upgrade, downgrade, interval change, or a non-commercial update.
Stripe’s subscription webhook reference covers the events you need for billing lifecycle handling.
| Event | Use it for | Do not use it for |
|---|---|---|
customer.subscription.updated | Detecting the new plan and updating access | Confirming a payment |
invoice.paid | Recording collected invoice revenue | Identifying every plan change |
charge.refunded or refund data | Recording a financial adjustment | Overwriting the original sale |
The subscription event tells you what changed. The paid invoice tells you what money arrived.
Handle immediate and delayed billing
An immediate upgrade may create proration charges. If you need Stripe to invoice and attempt collection at once, use the billing behavior supported by your upgrade flow, such as proration_behavior=always_invoice.
Some upgrades apply at renewal. Others require customer authentication. Some invoices fail. Your worker must wait for the financial result before it creates a final internal commission record.
Rewardful handles its own Stripe connection. Your Stripe webhook does not replace it. It gives your team a separate operational record for access control, reporting, and exception handling.
BUILD A DETERMINISTIC COMMISSION RECORD
A dashboard is useful. A fixed ledger is what support, finance, and affiliate managers can audit later.
Store IDs that let you reproduce a result
Create one record per billable affiliate event. Keep these fields:
- Rewardful affiliate ID and campaign or offer reference.
- Stripe customer ID, subscription ID, invoice ID, and payment reference.
- Old Price ID, new Price ID, billing interval, and currency.
- Paid amount, refund amount, commission amount, and status.
- Event ID, event type, received time, processor version, and reviewer.
- Payout batch ID and payout date when money moves.
Do not rely on customer email as a unique key. Emails change. Stripe IDs and invoice IDs do not.
If a team member reports a missing commission, collect the affiliate link, landing-page URL, Stripe IDs, invoice ID, date range, screenshots, and expected result. “Tracking is broken” gives nobody a useful starting point.
Preserve the original amount
Never replace a commission when a refund or downgrade changes it. Add an adjustment entry.
For example, an affiliate earns 20% on a $1,000 annual invoice. The first ledger row records a $200 commission. Stripe later refunds $250. The retained revenue is $750, and the revised commission is $150.
Keep the $200 original row. Add a negative $50 adjustment with the refund ID, event date, reason, and reviewer. This gives your team an audit trail and gives the affiliate a clear explanation.
Rewardful’s custom Stripe integration method also states that commissions adjust for upgrade and refund-related billing changes.
SECURE THE WEBHOOK BEFORE YOU AUTOMATE IT
A webhook endpoint is a public URL. Treat every incoming request as untrusted until Stripe verifies it.
Verify the Stripe signature on the raw payload
Keep the raw request body. Read the Stripe-Signature header. Use Stripe’s official SDK method to construct and verify the event with your endpoint signing secret.
Do not parse and reformat JSON before verification. A changed payload breaks signature validation.
Stripe’s webhook security documentation also recommends returning a fast success response. Put slow work into a queue after the event passes verification.
Make processing idempotent
Stripe can retry delivery. Events can arrive more than once. They can also arrive out of order.
Create an incoming_events table with a unique index on Stripe’s event ID. Your handler checks that key before it changes an entitlement or inserts a ledger record.
Your core handler logic can stay simple:
verify signature -> insert event ID if new -> queue work -> return 200
Your worker then uses stable business keys. For commission entries, use a unique constraint such as invoice_id + affiliate_id + commission_type. For adjustments, use refund_id + affiliate_id.
Log every decision. Record the raw event ID, related Stripe object IDs, action taken, result, error message, and retry count. Keep sensitive payment data out of logs.
PROCESS THE UPGRADE IN A BACKGROUND WORKER
The webhook endpoint should validate and queue. The worker should decide what to change.
Fetch current Stripe objects
Do not calculate a commission from only the webhook payload. Retrieve the current subscription and the related invoice from Stripe when the worker runs.
This handles delayed event delivery and gives you the latest payment state. Confirm the subscription’s active Price ID. Confirm the invoice is paid. Then compare the paid amount with your affiliate terms.
A practical worker sequence looks like this:
- Receive a verified
customer.subscription.updatedevent. - Store the old and new Price IDs, then update product access.
- Wait for a related paid invoice when the upgrade creates a charge.
- Fetch the invoice and confirm
paidstatus. - Match the Stripe customer to the existing Rewardful referral record.
- Create a provisional internal entry or reconcile the Rewardful commission.
- Add refund and chargeback monitoring before the commission becomes payable.
Keep your commercial rules explicit
State whether affiliates earn on gross invoices, collected revenue after discounts, or another defined basis. Set the recurring period, refund window, trial rules, self-referral policy, and payout timing in writing.
Rewardful affiliate upgrades should not create a second commission for the same Stripe invoice. They should update the revenue history of an already attributed customer.
If you run tiered campaigns, store the rate used at the time of the paid invoice. Don’t recalculate old invoices with today’s rate after you change a campaign.
For help reviewing a custom Stripe and Rewardful operating flow before release, Book A Call.
RECONCILE REWARDFUL, STRIPE, AND PAYOUTS
Automation reduces manual work. It does not remove review work.
Review accepted records, not event volume
A system that creates 50 commissions and needs hours of correction is not efficient. Track the records your team can approve without repair.
Review these numbers by affiliate and campaign each month:
- Referred customers with paid invoices.
- Pending, approved, due, paid, and reversed commissions.
- Refund and chargeback rate.
- Referred recurring revenue.
- Missing attribution records and duplicate claims.
- Review minutes and correction time.
Clicks are attention. A paid invoice is revenue. A paid affiliate commission is cash movement. Keep each stage separate.
Match source records every month
Export or save records from Stripe and Rewardful on a fixed schedule. Compare Stripe paid invoices, refunds, Rewardful commission entries, and completed payout batches.
Investigate mismatches before you fund payouts. Common causes include failed invoices, expired attribution, a later affiliate touchpoint, self-referrals, refunds, and checkout paths that lost referral context.
Keep the original exports, report date, file name, reviewer decision, and adjustment entries. Finance should be able to trace a payout back to an eligible paid invoice.
TEST IN A CONTROLLED STRIPE ENVIRONMENT
Test the full customer path before production. Do not test only the webhook URL.
Run these cases before launch
Use Stripe test mode where your connected setup supports it. If Rewardful test behavior is not available in your account, run a low-risk controlled production test only after you document the cost and approval owner.
Test a referred signup on the entry plan. Upgrade it with an immediate prorated charge. Upgrade it at renewal. Fail a payment. Issue a partial refund. Issue a full refund. Cancel the subscription. Retry the same webhook event.
Check desktop, mobile, hosted checkout, and direct-to-checkout links. A referral can work on a pricing page and fail on a shortcut to checkout.
Test the recovery path too
Disable the worker briefly and confirm queued events recover. Replay a known event in your test process. Confirm your unique event constraint blocks duplicate processing.
Then compare the final result across four places: Stripe subscription, Stripe invoice, Rewardful referral or commission view, and your internal ledger.
Do not release the workflow until those records agree.
LAUNCH CHECKLIST FOR AFFILIATE UPGRADE AUTOMATION
- Connect Rewardful to the intended Stripe account and confirm live permissions.
- Subscribe to
customer.subscription.updatedand the payment events your workflow requires. - Verify signatures with the raw payload and Stripe endpoint secret.
- Deduplicate by Stripe event ID before processing.
- Update access from the subscription Price ID, not invoice data alone.
- Create final commission records from eligible paid invoice amounts.
- Add adjustment rows for refunds, cancellations, and chargebacks.
- Store affiliate, customer, subscription, invoice, event, and payout IDs.
- Test upgrade, downgrade, failure, refund, and replay scenarios.
- Review a small batch of real records before forecasting payouts.
BUILD A RECORD YOU CAN DEFEND
Rewardful and Stripe can keep affiliate commissions aligned with subscription changes. The reliable setup separates product access from collected revenue and preserves every adjustment.
The strongest control is a fixed commission ledger. It turns an upgrade, refund, or payout dispute into a record your team can trace instead of a dashboard number somebody has to guess about.
FAQ
Does an upgrade automatically increase an affiliate’s commission?
Rewardful calculates commissions from what Stripe records as paid. If the customer remains attributed and the upgraded invoice is eligible under your campaign rules, the commission base can increase with the payment amount.
The exact outcome depends on your campaign rate, recurring rules, discounts, refunds, and affiliate terms.
Should I create commissions from customer.subscription.updated?
No. Use that event to detect the new plan and update access. Wait for the related paid invoice before treating the upgrade as collected revenue for commission reporting.
A plan change can occur without an immediate successful payment.
What should happen after a refund?
Keep the original commission record. Add a separate negative adjustment that references the refund, invoice, affiliate, amount, reason, and date.
Do not assume a completed affiliate payout will reverse automatically. Your written terms should state whether your team offsets future earnings, requests repayment, or absorbs the loss.
