Paddle Billing Dunning: Affiliate Commission Rules for Past-Due Subscriptions

Official documentation reviewed 7 November 2026 · Documentation-based guide

Should a SaaS affiliate earn commission while a Paddle subscription is past due?

Normally, no new revenue-based affiliate commission should be created while the related Paddle transaction is unpaid and past due. Keep the original referral attribution, place the renewal in a pending or recovery state, and create the commission only after the qualifying payment has completed under your program rules.

Paddle Billing distinguishes a past-due transaction from a completed transaction. A subscription can return to active after a recovered payment, but a subscription status change alone is not proof that a particular renewal has completed. Use the transaction record to determine whether the payment was processed, then create one commission entry for the eligible transaction.

This guide focuses on dunning and payment recovery. For platform selection, see the Paddle Billing affiliate software buyer guide. For separate pause and resume rules, see Paddle subscription pause and resume affiliate commissions.

Understand transaction.past_due and subscription.past_due

Paddle documents two related events. transaction.past_due fires when a transaction becomes past due and its status changes to past_due. For an automatically collected subscription renewal, this happens when a payment attempt fails. For a manually collected transaction, it happens when payment has not arrived 24 hours after the due date. When the transaction belongs to a subscription, the related subscription also changes to past due and Paddle emits subscription.past_due, except for subscription-change transactions with origin=subscription_update.

The subscription event is useful for understanding account state. The transaction event identifies the unpaid billing record. Store both, but do not create a commission from either event.

Know the difference between automatic and manual collection

Payment recovery depends on the collection mode. Paddle’s current documentation says Payment Recovery in Paddle Retain works with automatically collected subscriptions. It can be configured to notify customers, retry payments and determine whether a past-due subscription pauses or cancels after recovery attempts are exhausted.

For manually collected subscriptions, Paddle does not automatically retry, pause or cancel the overdue subscription through Payment Recovery. The merchant needs a separate follow-up workflow for unpaid invoices. Do not apply automatic-card-retry assumptions to manual invoice collection.

Paddle also documents that, without Paddle Retain, automatically collected Paddle Billing subscriptions can be retried up to seven times over a 30-day window before cancellation. If Retain is enabled, the available recovery settings and final pause-or-cancel behaviour should be checked in the live account because configuration determines the workflow. Paddle notes that Retain uses live billing data and cannot be integrated or tested with sandbox accounts.

Write the commission rule before building the webhook handler

A robust policy should answer four questions:

1. What counts as earned revenue? For example, a completed renewal transaction after discounts and eligible credits, excluding taxes if your agreement says so.
2. What happens during dunning? Keep the commission pending or on hold while the transaction is past due. Do not delete the referral or mark the partner as invalid simply because a card retry failed.
3. What happens after recovery? If the same transaction completes, calculate the commission once against that transaction and preserve its original referral attribution.
4. What happens when recovery fails? If the subscription is paused or canceled, no commission is created for the unpaid renewal. Apply any separate refund or clawback rule to previously paid commissions.

Do not silently change a recurring commission from a paid basis to an active-subscription basis. If the agreement rewards active subscriptions rather than collected invoices, define how past-due periods, grace periods and partial recoveries are treated.

Build an event-safe commission workflow

1. Receive the Paddle webhook and verify its signature using the official webhook verification process.
2. Store the event ID, event type, occurrence time, transaction ID and subscription ID where available.
3. When transaction.past_due arrives, mark the transaction as recovery pending. Do not issue a commission.
4. When subscription.past_due arrives, update the subscription status without replacing the transaction-level record.
5. When subscription.updated arrives, refresh the subscription state. This event covers many types of changes, so it must not be treated as a payment-success event.
6. When transaction.completed arrives, confirm the transaction ID has not already been processed, verify the referral mapping and apply the program’s commission policy.
7. Reconcile the transaction and subscription records periodically so missed notifications or delayed processing do not leave a commission stuck in the wrong state.

Paddle states that a transaction moves to completed after it has been paid and its internal processing is finished. For automatically collected transactions, that processing adds payment details and the related subscription and invoice identifiers. This makes the completed transaction a stronger commission trigger than a general subscription update.

Worked example: a failed renewal that later recovers

Assume a referred customer has a $100 monthly renewal and the affiliate agreement pays 20% of eligible collected subscription revenue.

If the recovery attempts are exhausted and the subscription is paused or canceled, the unpaid renewal remains non-commissionable under this example policy. A later new subscription should be evaluated as a new billing event, while the original referral and prior paid commissions remain auditable.

Implementation checklist

• Store the original partner and referral identifiers independently of subscription status.
• Use a unique constraint or idempotency key for each processed transaction.
• Keep transaction status and subscription status in separate fields.
• Do not pay on past_due or subscription.updated alone.
• Use transaction.completed as the payment-processing confirmation, then apply the program’s commission terms.
• Separate automatic collection from manual invoice follow-up.
• Test duplicate notifications, late recovery and exhausted recovery paths.
• Reconcile refunds and adjustments through a separate policy, such as the Paddle refund reconciliation guide.

Frequently asked questions

Does past due mean a Paddle subscription is canceled?

No. Paddle documents past due as an unpaid transaction state. For automatically collected subscriptions, recovery settings determine what happens after retries are exhausted. The subscription may be paused or canceled depending on configuration.

Does Paddle Retain retry manual invoices?

No. Paddle’s documentation says Payment Recovery works with automatically collected subscriptions. Manual invoices need a separate follow-up process.

Should a commission be created when subscription.updated fires?

No. That event can represent many subscription changes. Check the specific transaction and its completed status before calculating a revenue-based commission.

Can I test Paddle Retain in a sandbox?

Paddle’s current Retain setup documentation says it works with live billing data and cannot be integrated or tested with sandbox accounts. Plan a controlled production rollout and confirm the current account configuration.

Sources and editorial disclosure

Primary references: Paddle transaction.past_due, Paddle subscription.past_due, Paddle transaction.completed, Paddle subscription.updated and Paddle payment recovery and dunning settings. Reviewed 7 November 2026.

This is documentation-based implementation guidance, not legal or financial advice. No live Paddle account was accessed and no hands-on integration test is claimed.