A downgrade can change affiliate economics long after the original signup. If your team pays commission before billing records settle, you create avoidable corrections.
Rewardful affiliate downgrades work best when Stripe remains the financial source of truth and Rewardful manages the referral commission record. Your automation should record changes, apply your policy, and preserve every adjustment for finance and partner support.
Set the rules before you switch on live webhooks.
How Rewardful Affiliate Downgrades Work
Rewardful connects to Stripe and uses Stripe billing activity to create and update referral commissions. Its Stripe commission workflow is built around the amount a customer actually pays, not the list price printed on your pricing page.
A subscription downgrade can reduce future invoice amounts, create a proration credit, or change the next renewal charge. Stripe calculates that billing result. Rewardful receives the connected account activity and adjusts the related commission where its rules apply.
A downgrade is not always a refund
A customer moving from a $99 plan to a $49 plan doesn’t always receive cash back. Stripe may create a credit for unused time, apply that credit to a future invoice, or delay the lower price until the next billing cycle.
That distinction matters. Do not reverse an affiliate’s commission only because customer.subscription.updated arrives. First check whether Stripe created a paid invoice, a credit, a refund, or only a scheduled plan change.
Native adjustment versus custom policy
Rewardful states that its automated refund handling adjusts commissions for refunded, upgraded, and downgraded affiliate sales. Its Stripe integration also receives updates for customer creation, invoice payment, and refunds through two-way Stripe sync.
Your custom automation is still useful when your terms require a different action. Common examples include holding commission during dunning, capping recurring commission after a plan change, or creating an internal review task before a payout is released.
Stripe decides what the customer paid. Your commission policy decides what the affiliate keeps.
Map the Stripe-to-Rewardful Workflow
Use one clear flow. Stripe records the subscription change. Rewardful updates commission activity. Your service stores an audit record and handles exceptions.
Keep Stripe as the billing source
Stripe Billing owns the subscription, prices, invoice totals, credits, refunds, and payment status. Use the Stripe customer ID, subscription ID, invoice ID, and refund ID as your primary records.
Stripe describes subscription changes as updates to prices, quantities, and subscription items. These changes can create prorations. Its subscription overview also identifies invoice.payment_failed as the event to use when a recurring payment does not clear.
Let Rewardful own referral attribution
Rewardful owns the affiliate relationship and commission lifecycle. Avoid rebuilding attribution logic from browser cookies inside your webhook service. That creates duplicate records and disagreements between systems.
Instead, store Rewardful commission IDs beside the matching Stripe invoice IDs. When an affiliate questions a reduced payout, your team can trace the result to one customer, one invoice, and one billing event.
Set Commission Rules Before Automation
Automation can move records fast. It cannot decide whether your commercial terms are fair or financially safe.
Write the policy in your affiliate agreement and in an internal operations document. State whether recurring commissions apply to gross invoice value, collected revenue after discounts, or collected revenue after refunds.
| Billing outcome | Recommended commission action |
|---|---|
| Customer upgrades and pays an invoice | Pay commission on the paid invoice amount |
| Customer downgrades for the next period | Keep past approved commission unchanged |
| Downgrade produces a credit or refund | Let the related commission adjust, then review payout status |
| Invoice payment fails | Hold new commission until payment clears |
| Full refund before payout | Remove or void the unpaid commission |
| Chargeback after payout | Create a recovery adjustment under your written terms |
The table keeps finance, support, and affiliate managers on the same rule set. It also stops a common mistake, treating a plan downgrade as proof that the original sale was invalid.
Use a commission hold period
A short hold period protects against refunds and early cancellations. The right length depends on your refund window and customer behavior.
Keep pending, approved, due, paid, and reversed commissions separate. A pending or created commission is potential payout liability. It is not cash you should promise to an affiliate.
Preserve original records
Never overwrite the first commission value after a downgrade or refund. Add an adjustment record instead.
Store the original amount, revised amount, adjustment amount, source event, decision date, reason, and reviewer. A $200 commission that becomes $150 after a $250 refund needs a visible negative $50 adjustment. Finance needs the history.
Configure Stripe and Rewardful First
Connect Rewardful to the correct Stripe account before building custom handlers. Check that a referred test customer appears under the intended affiliate and that the Stripe customer and subscription records match.
Rewardful explains that it receives Stripe refund notifications and recalculates commissions after full or partial refunds in its Stripe account integration guide.
Subscribe to the events you need
At minimum, your Stripe webhook endpoint should process:
customer.subscription.updatedto detect price, quantity, status, and cancellation changes.invoice.paidto release commission-related internal holds after successful collection.invoice.payment_failedto pause new payout eligibility during dunning.- Refund events to create audit entries and trigger a payout review.
customer.subscription.deletedto close internal tracking for canceled subscriptions.
Do not trigger an affiliate payment from customer.subscription.updated alone. That event tells you a subscription changed. It does not prove a customer paid a revised amount.
Store stable identifiers
Create one internal ledger record per billing event. Include:
stripe_event_id, stripe_customer_id, subscription_id, invoice_id, refund_id, rewardful_commission_id, affiliate_id, event_type, decision, and processed_at.
These fields make reconciliation practical. They also give support a record they can reproduce without searching through screenshots and dashboard filters.
Build Idempotent Webhook Logic
Webhook delivery is at least once, not exactly once. Stripe can retry events. Rewardful webhook deliveries can also retry after a failed response. Your handler must safely receive the same event more than once.
Verify first, then queue work
Verify the Stripe webhook signature against the raw request body. Reject invalid requests before parsing business data.
Return a successful response quickly after you save the event. Run the billing and commission logic in a queue worker. Long webhook requests fail more often, and retries can create duplicate actions.
Use the Stripe event ID as an idempotency key. Put a unique database constraint on that field. If the event already exists, return success and do nothing else.
Apply the decision after invoice lookup
Your worker can follow this payload logic:
- Read the event and load the current Stripe subscription and related invoice.
- Check whether the event ID was processed.
- Identify the old and new price, current status, proration lines, paid amount, and refund amount.
- Find the linked Rewardful commission or wait for Rewardful’s commission webhook update.
- Create an immutable adjustment record when your policy requires a hold, reversal, or review.
- Mark the event complete only after the database transaction succeeds.
Do not calculate commission from unit_amount on the new plan. A coupon, tax setting, account credit, or proration can make that figure wrong. Use the settled invoice amount that your terms define as commissionable revenue.
Handle Upgrades, Cancellations, and Refunds
Plan changes are routine. Poor correction handling is what creates payout disputes.
Upgrades and proration
An upgrade can create an immediate invoice. If the invoice is paid, Rewardful can calculate the resulting commission from the collected sale.
A downgrade often produces a credit proration. That credit is not always a refund. Record it, link it to the subscription, and wait for the final invoice or refund outcome before making a manual payout correction.
For Rewardful affiliate downgrades, use the invoice and refund outcome as the decision point. Do not rely on the plan-change timestamp.
Cancellations, refunds, and chargebacks
For an unpaid commission, a full refund can remove the commission record. A partial refund can reduce it. Check your Rewardful activity and your ledger before a payout batch.
Paid commissions need a separate process. Most SaaS programs either offset the amount against future earnings, request repayment, or absorb the loss. Put that rule in the affiliate agreement before the first payout.
A chargeback is not the same as a customer refund. Pause affected commissions while the dispute is open. Release or adjust them only after Stripe shows the final payment outcome.
Treat Failed Payments as a Hold, Not a Reversal
A failed renewal does not always mean the customer has churned. Stripe may retry the payment, the customer may update a card, or the subscription may later cancel.
When invoice.payment_failed arrives, set the related recurring commission to on_hold. Do not delete historical approved commission for prior paid invoices.
When a later invoice.paid event clears the renewal, remove the hold. If the subscription ends without payment, no new commission should become due for that invoice.
This approach keeps your payout report honest. It separates valid past revenue from a renewal that never collected.
Test the Automation Before Production
Run controlled tests in Stripe test mode and your Rewardful test or safe internal setup before enabling live processing. Use a real internal affiliate relationship where possible.
Test a referred signup, upgrade, downgrade, partial refund, full refund, canceled subscription, failed renewal, successful retry, and duplicate webhook delivery.
For each case, confirm the affiliate, Stripe invoice, commission status, adjustment record, and payout eligibility. Test desktop checkout and direct Stripe Checkout links too. Referral tracking can fail when partners bypass the path you tested on your pricing page.
Run one small approved payout batch before you forecast monthly commission costs.
Key Takeaways
Stripe controls subscription math. Rewardful tracks referral commissions and can adjust them as billing outcomes change.
Build custom logic around policy exceptions, payout holds, audit records, and idempotent event processing. Do not overwrite commission history. Add a clear adjustment that links back to the original invoice and event.
A payout is safe only when the commission, customer payment, and correction record agree.
FAQs
Does Rewardful automatically reduce commission after a downgrade?
Rewardful documents automated adjustments for downgraded affiliate sales, upgrades, cancellations, and refunds. Check the related invoice and commission activity before making any manual change. A scheduled downgrade with no refund may not require a reversal of past commission.
Should I reverse a commission when a customer changes to a cheaper plan?
No, not by default. Reverse or reduce commission only when your written terms and Stripe’s final billing outcome support it. A future lower renewal price does not invalidate a previously paid invoice.
What is the best idempotency key for this automation?
Use the Stripe event ID for Stripe webhook processing. Store it in a database table with a unique constraint. For downstream Rewardful events, store the Rewardful event ID or commission ID plus event type, then reject duplicate processing.
What should happen after a partial refund?
Keep the original commission record. Add a negative adjustment for the refunded portion and mark the payout impact. Rewardful can recalculate unpaid commission after a partial refund, but your ledger should still show what changed and why.
