Paddle Billing
Search

Refund or credit a transaction

Create an adjustment to record a change to a billed or completed transaction, like a refund or credit. Most refunds for live accounts have to be approved by Paddle.

If you need to change a billed or completed transaction, you can create an adjustment. Adjustments let you refund or credit a transaction after it's been billed or completed.

Adjustments sit alongside transactions. The existing transaction entity remains on your system unchanged for record-keeping purposes.

Illustration of a credit note from Paddle

How it works

Billed and completed transactions are financial records, so they can't be deleted or changed. This is especially important when working with manually-collected transactions because they're considered issued invoices. Paddle assigns them an invoice number and sends them to customers, so any financial adjustments must be correctly recorded.

Use adjustments to refund or credit all or part of a transaction and its items. A transaction may have multiple adjustments where you've refunded or credited different items.

Paddle automatically sends a credit note to customers as a PDF so they have a record of a refund or credit. You can also download credit notes from the Paddle dashboard or generate a URL to them using the API.

Refunds

Refunds let you return some or all of a transaction amount to customers. The money is returned to the original payment method that the customer used.

To keep the platform safe for everyone, most refunds for live accounts require approval from Paddle. They're created with the status of pending_approval, before moving to approved or rejected once reviewed.

For live accounts, Paddle automatically approves refunds when:

For sandbox accounts, Paddle automatically approves all refunds every ten minutes.

Credits

Credits let you give customers some or all of a transaction amount as a credit. You can create credits for manually-collected transactions (invoices) to reduce the amount due on issued invoices.

For example, if you create and issue an invoice then want to remove an item, you can create an adjustment for the item you want to remove. Paddle automatically applies the credit to the issued invoice, reducing the amount the customer owes.

When you credit the full value of a transaction, it's marked as completed. It's no longer due.

Credits don't need approval from Paddle.

Credits in Paddle are always related to existing transactions. They adjust an amount that's been paid, or an amount that's due on an issued invoice. They're not promotional credits, which are credits given to customers for things like referral schemes or promotions.

Chargebacks

When paying by card and some other kinds of payment methods, customers may dispute a charge with their payment method issuer. Issuers investigate disputes and may choose to reverse a charge. This is called a chargeback.

Paddle automatically creates adjustments for chargeback events for you:

  • For some kinds of chargebacks, we get an early warning and create an adjustment with the type chargeback_warning for the disputed amount. The amount is refunded.
  • For chargebacks where we don't get an early warning, we create an adjustment with the type chargeback for the disputed amount. The amount is refunded.
  • The Paddle team contests chargebacks for you. Where a chargeback is contested successfully, Paddle creates an adjustment with the type chargeback_reverse to return the amount held.

Create a refund

Create an adjustment with the action of refund to return some of all of a transaction amount to customers.

Create a refund for a transaction using the API in four steps:

  1. Get a transaction and extract items

    Get the transaction that you want to refund, then extract transaction item IDs.

  2. Build request

    Build a request that includes a list of transaction items and the amount to refund for each.

  3. Create your adjustment

    Send the request to create your adjustment. Paddle creates it. Its status is pending approval or approved depending on the amount and whether you're using a sandbox or live account.

  4. Handle refund status change — optional

    Most refunds are created pending_approval. If you present refunds to customers in your app, handle refund approval or rejection.

You can't create an adjustment for a transaction while it has an existing adjustment that's pending approval. Wait for the adjustment to become approved or rejected, then create your adjustment.

Get a transaction and extract items

Adjustments are for transaction items, so you'll need to get the transaction that you want to create a refund for and extract some information about its line items.

Transactions must be completed to create a refund them. You can get completed transactions using the list transactions operation, passing completed as a value to the status query parameter.

Response

If successful, Paddle responds with the transaction entity.

For each item in transaction.details.line_items[], extract id and totals.total and save these for later — we'll use this in the next step.

Build request

Build a request that includes an items array. Your array should include an object for each transaction item that you want to refund, where each object contains an item_id and a type.

To refund the total for a transaction item, set type to full.

To refund part of the total for a transaction item, set type to partial and include an amount.

itemsarray[object]

List of transaction items to adjust.

item_idstring

Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_.

typestring

Type of adjustment for this transaction item. Include amount when creating a partial adjustment.

amountstring or null

Amount adjusted for this transaction item. Required when adjustment type is partial.

Along with your items array, include transaction_id for the transaction that the items you're refunding relate to.

transaction_idstring

Paddle ID for the transaction related to this adjustment, prefixed with txn_.

To specify that this adjustment should refund the amount to the payment method that the customer used, you must include:

  • action with the value of refund.
  • A reason why you're refunding this amount.

The reason is important for record-keeping purposes. It's displayed in the Paddle dashboard and retained for future reference.

actionstring

How this adjustment impacts the related transaction. Most refund adjustments must be approved by Paddle, and are created with the status pending_approval.

reasonstring

Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes.

Request

This example creates a refund for two items on an automatically-collected transaction. One item is refunded in full, and another is partially refunded.

Create adjustment

Send a POST request to the /adjustments endpoint with the request you built.

POSThttps://api.paddle.com/adjustments

Response

If successful, Paddle responds with the new adjustment entity. It includes calculated totals.

Handle refund status change — optional

Most refunds for live accounts are created with the status of pending_approval until reviewed by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves refunds every ten minutes.

From pending_approval, adjustments move to:

  • approved

    Refund approved by Paddle. The amount is refunded to the original payment method that the customer used. This may take a few days to process.

  • rejected

    Refund rejected by the Paddle team. Contact the Paddle seller support team if you want to understand more about why a refund was rejected.

The adjustment.updated event occurs when the status of an adjustment changes. Subscribe to this event to get notified when adjustments are approved or rejected. If you've built a billing information page in your app, you might like to update the status of the refund on this page.

Create a credit

Create an adjustment with the action of credit to give customers some or all of a manually-collected transaction (invoice) amount as a credit.

Create a credit for a transaction using the API in three steps:

  1. Get a transaction and extract items

    Get the transaction that you want to credit, then extract transaction item IDs.

  2. Build request

    Build a request that includes a list of transaction items and the amount to credit for each.

  3. Create your adjustment

    Send the request to create your adjustment. Paddle creates it.

You can only create credits for manually-collected transactions (invoices). You can't create credits for automatically-collected transactions.

Get a transaction and extract items

Adjustments are for transaction items, so you'll need to get the transaction that you want to create a credit for and extract some information about its line items.

Transactions must be billed or past_due to create a credit for them. You can get billed and past due transactions using the list transactions operation, passing billed,past_due as a value to the status query parameter.

Response

If successful, Paddle responds with the transaction entity.

For each item in transaction.details.line_items[], extract id and totals.total and save these for later — we'll use this in the next step.

Build request

Build a request that includes an items array. Your array should include an object for each transaction item that you want to credit, where each object contains an item_id and a type.

To credit the total for a transaction item, set type to full.

To credit part of the total for a transaction item, set type to partial and include an amount.

itemsarray[object]

List of transaction items to adjust.

item_idstring

Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_.

typestring

Type of adjustment for this transaction item. Include amount when creating a partial adjustment.

amountstring or null

Amount adjusted for this transaction item. Required when adjustment type is partial.

Along with your items array, include transaction_id for the transaction that the items you're crediting relate to.

transaction_idstring

Paddle ID for the transaction related to this adjustment, prefixed with txn_.

To specify that this adjustment should create a credit for the customer, you must include:

  • action with the value of credit.
  • A reason why you're crediting this amount.

The reason is important for record-keeping purposes. It's displayed in the Paddle dashboard and retained for future reference.

actionstring

How this adjustment impacts the related transaction.

reasonstring

Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes.

Request

This example creates a credit for two items on a manually-collected transaction. One item is credited in full, and another is partially credited.

Create adjustment

Send a POST request to the /adjustments endpoint with the request you built.

POSThttps://api.paddle.com/adjustments

Response

If successful, Paddle responds with the new adjustment entity. It includes calculated totals.

In this example, credit_applied_to_balance is false meaning that the amount was applied to the billed transaction, reducing the balance to pay.

Generate a credit note document

Credit notes were introduced in September 2024. You can't generate credit notes for adjustments created before then.

Generate a credit note document as a PDF to give to a customer as a record of a refund or credit.

Send a POST request to the /adjustments/{adjustment_id}/credit-note endpoint, passing the Paddle ID of the adjustment entity that you want to generate a credit note for.

Response

Common errors

adjustment_transaction_invalid_status_for_creditTransaction must be billed and manually-collected to create a credit.
adjustment_transaction_invalid_status_for_refundTransaction must be completed to create a refund.
adjustment_pending_refund_requestTransaction has a pending refund. Wait for the refund to move to approved or rejected before creating another.

Events

adjustment.createdOccurs when an adjustment is created.
adjustment.updatedOccurs when a refund adjustment status changes to approved or rejected.

Related pages