Paddle Billing developer documentation reviewed 11 November 2026. This is a documentation-based implementation guide, not an account test.
When should an affiliate earn commission on a Paddle manual invoice?
Register the referral when the sales opportunity is accepted, but normally approve a cash-based commission only after the manually collected invoice is paid and reconciled. In Paddle Billing, issuing a manual invoice can create a subscription for recurring items before the customer pays. The transaction.billed event therefore confirms that an invoice was issued, not that commissionable cash arrived. A program that pays at contract signature may use a different rule, but it must explicitly fund the risk of unpaid invoices.
For other subscription failure scenarios, see our Paddle Billing dunning and affiliate commission guide. For B2B attribution outside self-serve checkout, read sales-assisted affiliate attribution.
How manual collection differs from Paddle Checkout
Paddle’s invoice guide explains that checkout uses automatically collected transactions, while invoices use collection_mode=manual. A sales team may issue an invoice with payment terms and collect by bank transfer or an enabled checkout payment method. For recurring items, Paddle creates the subscription when the invoice is issued. That early subscription creation is useful for provisioning and CRM linkage, but it must not be mistaken for a settled payment.
| Paddle state or event | Business meaning | Affiliate ledger action |
|---|---|---|
draft / ready |
Invoice is being prepared or ready to issue | Keep opportunity attribution; no earning |
transaction.billed |
Manual invoice issued and invoice number assigned | Record invoice candidate and due date |
subscription.created |
Recurring subscription record exists | Attach affiliate and transaction IDs; no automatic payout |
past_due |
Unpaid after applicable payment terms and processing window | Keep pending or reject per policy |
transaction.paid |
Payment captured, processing may remain | Mark payment received, await full reconciliation |
transaction.completed |
Payment and transaction processing complete | Calculate eligible amount, then apply approval hold |
According to Paddle’s paid event documentation, transaction.paid occurs before all internal processing is complete. The completed event follows when fees, earnings and other details have been processed. This is why an affiliate ledger should distinguish a payment confirmation from a fully reconciled transaction.
Worked example: annual enterprise invoice
A reseller refers a business customer to a $1,000 annual SaaS subscription plus a $200 one-time implementation service. The affiliate contract pays 10% on eligible subscription revenue only. The sales team issues a $1,200 manual invoice with 14-day terms. Paddle creates a subscription record when the recurring invoice is issued, but the customer has not paid. Commission at issue: $0 payable. When the invoice reaches completed status after payment, the eligible base is $1,000 and the candidate commission is $100, subject to the agreed hold and any adjustments. The $200 setup service is excluded by this example’s policy.
If the customer pays late, the commission clock begins at the qualifying payment event, not at invoice issue, if the contract uses a paid-revenue trigger. If the invoice is canceled, no commission is earned. If only part of a transaction is eventually eligible, preserve the line-item calculation instead of applying the rate to a headline contract value.
Preserve attribution across sales and billing
Enterprise buyers may interact with a partner, a sales representative and a finance contact before Paddle issues the invoice. Save a durable attribution record that links the partner, CRM deal, Paddle customer, manual transaction and resulting subscription. Paddle’s subscription.created documentation notes that the creation event contains a transaction_id that can be used to connect the subscription to its originating transaction. Do not depend on a browser referral cookie when an accounts-receivable employee pays weeks later.
Store the agreed commission basis and rule version alongside the partner ID. If a different partner later supplies a referral link, do not silently overwrite an approved registered deal. For competing ownership claims, use the decision process described in our B2B partner deal registration checklist.
Implementation workflow for finance and developers
- Register the opportunity: validate the partner and customer, log consent-appropriate attribution evidence, and resolve duplicate CRM ownership before quoting.
- Create the invoice: use a manual Paddle transaction with customer, address, items and billing details. Persist the transaction ID and invoice number when issued.
- Link the subscription: match the
subscription.createdevent to the originating transaction. A created subscription is a relationship record, not proof of payment. - Verify the webhook: validate Paddle’s signature, acknowledge delivery promptly, handle retries and maintain idempotent event processing. Paddle documents signature verification and simulator testing in its webhook guide.
- Wait for reconciliation: use the completed transaction to inspect eligible items, tax, discount, credit, adjustments, currency and any payout-related totals relevant to your policy.
- Approve after the hold: create one pending commission per qualifying transaction and rule, review refunds and disputes, and move to payable only when conditions are met.
What happens when the invoice becomes past due?
Paddle’s invoice documentation says an unpaid manual invoice becomes past_due 24 hours after the due date; the related subscription generally becomes past due as well, except in certain subscription-change cases. Paddle Retain does not automatically chase these overdue manual invoices. The merchant should operate its own accounts-receivable follow-up workflow. An affiliate should see a clear pending or unpaid state rather than an unexplained clawback.
Do not cancel attribution when an invoice becomes past due. A late payment may still qualify later. Conversely, do not pay just because the subscription remains visible or the sales team marked the CRM deal won. The commission agreement should define a deadline for crediting late payments and a process for cancellations.
Pre-launch QA cases
| Scenario | Expected result |
|---|---|
| Manual invoice issued, no payment | Partner attributed; payable commission zero |
| Subscription created on invoice issue | No duplicate payout on subscription event |
| Invoice paid after due date | Eligible commission calculated once after reconciliation |
| Invoice canceled before payment | No earned commission |
| Two webhooks delivered in reverse order | State machine resolves from stored transaction IDs |
| One-time implementation line on invoice | Included only if written policy allows it |
| Webhook replay | Idempotency prevents duplicate commission |
Frequently asked questions
Does transaction.billed mean the customer paid?
No. For a manually collected transaction, billed means the invoice was issued. Payment may occur later.
Why does Paddle create a subscription before invoice payment?
Paddle creates a subscription for recurring items when the manual invoice is issued. Merchants can provision access based on their own policy, but billing collection remains a separate lifecycle.
Should a reseller earn commission on a signed deal?
That is a commercial agreement choice. A signed-deal bounty is possible, but it should be labeled separately from commission on paid recurring revenue and have an explicit cancellation or non-payment rule.
Official sources reviewed
- Paddle: create and issue manual invoices
- Paddle: transaction.billed
- Paddle: transaction.completed
- Paddle: subscription.created
Editorial disclosure: This is an independent documentation-based operational guide. SaaSAlways has not tested a merchant’s live Paddle account for this article. Commission rates and payment eligibility are illustrative program policies, not Paddle’s default affiliate rules.