Paddle Billing Affiliate Refund Reconciliation

How should affiliate commissions be reconciled after a Paddle refund?

Short answer: Tie every affiliate commission to its original Paddle transaction and eligible revenue basis. Ingest adjustment.created for every refund, credit or dispute adjustment, then process adjustment.updated when a pending refund changes status. Calculate a commission adjustment only under the program's written policy, and never reverse the same amount twice when webhook deliveries repeat.

Paddle Billing adjustments can represent full or partial refunds, credits and chargebacks. They are not identical accounting events. An adjustment can be pending approval, approved, rejected or reversed. Your affiliate ledger needs both the original commission and each related adjustment so finance can reconstruct the net amount. For integration compatibility, see our Paddle Billing affiliate integration guide.

Understand Paddle's adjustment event lifecycle

Paddle documents adjustment.created as the event sent when an adjustment is first created. Some refunds begin in pending_approval and later become approved or rejected; adjustment.updated records those changes. But some refunds are approved immediately, and credits are normally approved at creation. Therefore a system listening only for adjustment.updated will miss valid adjustments.

Chargebacks and related dispute adjustments can be created automatically. Do not assume a chargeback warning equals a finalized lost dispute, or that a later reversal cannot occur. Model the actual action and status fields. The adjustment.created and adjustment.updated references define the documented payloads.

Preserve transaction, subscription and adjustment IDs

Each commission record should retain merchant or program ID, affiliate ID, Paddle transaction ID, subscription ID if present, currency, original eligible amount, commission rule version and payout status. Each adjustment record should include its own adjustment ID, source event ID, action, status, original transaction ID, affected line items and calculated commission delta.

Paddle's custom data documentation describes how transaction custom data can propagate to a subscription and subsequent transactions. This can help preserve an internal attribution reference through renewals, but it does not replace a validated server-side commission ledger. Avoid storing unnecessary personal information in custom data.

Calculate partial refunds against the right base

Suppose a customer pays $200 for an eligible subscription period and the affiliate earns 15% of eligible revenue. The initial commission is $30. Later, an approved $50 partial refund reduces the eligible base to $150. Under a proportional reversal policy, the commission reduction is $7.50, leaving $22.50 net commission.

That example assumes the entire $200 and $50 are commissionable or refundable on the same basis. In a real Paddle transaction, taxes, discounts, currency conversions, prorations and multiple line items may affect the eligible base. Use the actual adjustment line items and totals, not a simple percentage of the customer-facing total unless your contract explicitly defines it that way. Paddle added a tax_rates_used breakdown to adjustment webhook payloads in February 2026, which can assist tax-aware reconciliation where available.

Do not apply a refund to unrelated revenue

If a transaction contains a $150 subscription and a $50 setup fee but only the subscription earns commission, a $50 refund of the setup fee should not automatically reverse one quarter of the affiliate commission. Map the adjustment item IDs to the corresponding transaction items and their eligibility flags.

Build a resilient reconciliation pipeline

1. Verify Paddle webhook signatures and store the raw event ID and receipt timestamp.
2. Deduplicate delivery events before queuing work, then fetch canonical transaction or adjustment data when needed.
3. Match the adjustment's transaction_id to a previously recorded commission and confirm merchant scope.
4. Update adjustment status idempotently; do not create a final reversal for an unapproved refund.
5. Calculate the delta from eligible line items and the rule version effective on the original transaction.
6. Write an immutable ledger entry referencing the adjustment ID, commission ID and calculated amount.
7. If a payout was already sent, record a recoverable balance or future offset according to the partner agreement; do not silently edit historical payouts.
8. Reconcile aggregate net commissions with Paddle transaction and adjustment reports at month-end.

Keep separate idempotency controls for provider event IDs and financial adjustment IDs. Multiple events can describe one adjustment as it changes status; only the appropriate final status transition should create the intended financial delta.

Handle disputes and chargeback reversals

A dispute may create a chargeback adjustment and later a related reversal if the outcome changes. Treat the dispute as its own state machine. Depending on policy, you may hold an unpaid commission during an open dispute, reverse it on a confirmed loss, and reinstate eligible credit if the dispute is won. Maintain links between the original chargeback and its reversal so the ledger does not over-credit the affiliate.

Finance should also distinguish commission recovery from the payment processor's dispute fee. The fee may not be part of the revenue basis used in the affiliate agreement. Our SaaS affiliate commission clawback guide covers policy wording and recovery timing.

Controls and QA tests before production

1. Create a paid test transaction and confirm a single eligible commission.
2. Issue a partial refund and observe pending approval, then approved or rejected transitions.
3. Test an immediately approved refund that does not emit an update event.
4. Replay both webhook events and verify only one net adjustment.
5. Refund a non-commissionable line item and check the result.
6. Test chargeback, warning and reversal states where sandbox fixtures support them.
7. Check the original currency and rounding to the smallest currency unit.
8. Compare an export of commissions, adjustments and payouts to Paddle reports.

Frequently asked questions

Does adjustment.updated fire for every Paddle refund?

No. Paddle states that some refunds are approved at creation and not every adjustment passes through pending approval. Listen to adjustment.created as well.

Should an affiliate lose commission while a refund is pending?

That depends on the written policy. A provisional payout hold can be safer than a final reversal until the refund is approved.

Can a refunded commission be reinstated?

Yes, if the underlying financial event is reversed and the program policy permits reinstatement. Record a linked correcting entry instead of deleting the original reversal.

Sources and editorial disclosure

• Paddle: adjustment.created
• Paddle: adjustment.updated
• Paddle: custom data propagation
• Paddle: adjustment tax rates update

Official Paddle Billing documentation reviewed 30 October 2026. Calculations are illustrative; this article is not a hands-on product test, accounting opinion or legal advice. Validate exact payout terms and financial treatment with your finance team.