Should an affiliate earn commission when a Stripe invoice is finalized?
Short answer: Normally no. invoice.finalized means an invoice is ready for payment, not that the customer paid. Record a provisional invoice reference if useful, but calculate an eligible commission after the appropriate invoice.paid event and your own revenue policy. Approval and payout remain separate decisions.
Stripe distinguishes invoice finalization, paid invoices and payment failures. Its invoice lifecycle shows that an invoice can be open and unpaid after finalization. Stripe does not automatically run your affiliate program; the following is a merchant-designed accounting workflow.
Which Stripe events should affect a commission?
| Event | Billing meaning | Affiliate response |
|---|---|---|
invoice.created | Invoice created | Store invoice reference only |
invoice.finalized | Ready for collection | Optional provisional state, no payout |
invoice.payment_failed | Payment attempt failed | Keep commission on hold |
invoice.paid | Invoice became paid | Evaluate amount and eligibility |
| Credit note or refund | Revenue adjusted later | Reconcile and post an offset |
A subscription's active status is not an invoice-level cash receipt. Likewise, a Checkout success redirect does not establish payment. Use billing records for financial decisions and referral records for partner ownership.
Create a reproducible commission ledger
Store the Stripe account, customer ID, subscription ID if available, invoice ID, line-item identifiers, currency, referral owner, policy version, commissionable base and commission state. A unique invoice-and-rule key prevents duplicate awards when Stripe retries a webhook. For line-level rewards, include the invoice line ID in the key.
Preserve both Stripe's event timestamp and the time your system received the event. Asynchronous notifications can arrive out of order. Reconcile against the current invoice state rather than assuming the most recently received event is the newest business state. Keep an immutable original calculation and record subsequent adjustments separately.
Example: discount and tax treatment
Imagine a $120 subscription charge with a $20 discount and $10 tax. If your program pays 20% of eligible subscription revenue excluding tax, the base is $100 and the commission is $20. It is not $26. The treatment of setup fees, credit balances, prorations and tax must be defined in your program terms.
There is an important nuance: Stripe documents that invoice.paid can occur on a trial or zero-amount invoice, or when a customer credit balance covers the amount. It can also be marked paid out of band. Therefore, a paid status does not always mean new cash arrived. Check eligible paid amounts and payment method conditions before awarding a positive commission.
Implementation checklist
- Capture a verified affiliate referral before the checkout begins and bind it to an internal signup record.
- Authenticate incoming Stripe webhooks and store event IDs for deduplication.
- On finalization, associate the invoice with the referral without marking a commission payable.
- On paid, fetch the invoice and evaluate eligible line items, discounts and any credit balances.
- Calculate the commission under the policy effective for this customer and partner.
- Apply approval periods, fraud reviews and minimum payout thresholds.
- Process refunds and credit notes as linked ledger adjustments, never as silent edits.
For referral identity mapping, read Stripe Checkout Session affiliate attribution. For failed collections, use the failed payment commission hold guide.
Seven scenarios to test before going live
Test a normal paid renewal, a failed payment followed by retry, a $0 trial invoice, a coupon-covered invoice, a prorated upgrade, an invoice paid out of band and a credit note after commission approval. Replay each webhook to confirm that ledger counts and balances remain unchanged. Test two events arriving in reverse order and verify that reconciliation produces the same final result.
Document whether commissions are earned on gross billed value, net paid subscription revenue or another defined basis. Explain the approval period and what happens after refunds. A policy might say that eligible commissions accrue on paid subscription invoices excluding tax and become payable after a review window. That is an illustrative merchant policy, not a Stripe setting.
Frequently asked questions
Does invoice.finalized mean a successful payment?
No. Finalization prepares the invoice for collection; it can remain open.
Can invoice.paid happen without a successful PaymentIntent?
Yes. Stripe documents trials, customer credits and out-of-band payment cases. Check actual eligible revenue.
Should payment retries create another commission?
No. Deduplicate by invoice and rule, and reconcile the final paid state.
For approval and reversals, see commission approval workflows and Stripe credit note reconciliation.
Editorial note: Official Stripe documentation reviewed 4 November 2026. Examples are illustrative; no hands-on testing or legal advice is claimed.