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 recordkeeping purposes.

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 the total 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:

Your account has been through Paddle account verification and is active.
The refund amount is less than or equal to 400 USD, or equivalent in another currency.
The refund amount is less than your balance.
The customer paid using a payment method other than bank transfer.

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

Credits

Credits let you give customers some or the total 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.

Revise customer information

Revising customer information for a transaction is another way you can describe updates to a transaction after it's been billed or completed. However, revising a transaction is for updating customer, address, and business information against a transaction.

When you revise customer information for a transaction, Paddle may create an adjustment if there are financial changes. For example, if you add a valid tax or VAT number, Paddle automatically creates an adjustment to refund any tax where applicable.

Ways you can update a completed or billed transaction

Create a refund

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

API

Dashboard

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

Get a transaction and extract items — optional
Get the transaction that you want to refund. Extract some information about transaction items if you only want to refund some line items.
Build request
Build a request that includes a list of transaction items and the amount to refund for each.
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.
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 — optional

Adjustments are for transaction items, so you'll need to get the transaction that you want to create a refund for.

You can refund the total for a transaction, or just some of its line items. If you only want to refund some of the transaction items, extract some information about the transaction line items. You don't need to do this if you want to refund the total transaction.

GEThttps://api.paddle.com/transactions/{transaction_id}

transaction_idstring

Paddle ID of the transaction entity to work with.

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.

200 OK


162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
162        "chargeback_fee": {
163          "amount": "0",
164          "original": null
165        },
166        "earnings": "56589",
167        "currency_code": "USD"
168      },
169      "line_items": [
170        {
171          "id": "txnitm_01j1f28f89k9wfjwns16b1yqww",
172          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
173          "quantity": 10,
174          "totals": {
175            "subtotal": "30000",
176            "tax": "2662",
177            "discount": "0",
178            "total": "32662"
179          },
180          "product": {
181            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",

Build request

Build a request that includes the type field, and optionally an items array.

Specify type to determine whether you want to refund the transaction total or particular items.

typestring

Type of adjustment. Use full to adjust the grand total for the related transaction. Include an items array when creating a partial adjustment. If omitted, defaults to partial.

If you set type to partial, include an items array. Your array should include an object for each transaction item that you'd like 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.

By default, items[].amount is inclusive of tax. Include tax_mode with a value of external in your request to say that amounts are exclusive of tax.

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.

Include transaction_id for the transaction that your refund relates 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 recordkeeping 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 recordkeeping purposes.

Request

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
2  "action": "refund",
3  "type": "partial",
4  "transaction_id": "txn_01j1f27bnwg90nggkgkf52hy34",
5  "reason": "goodwill gesture",
6  "items": [
7    {
8      "item_id": "txnitm_01j1f28f89k9wfjwns1htt8bpw",
9      "type": "full"
10    },
11    {
12      "item_id": "txnitm_01j1f28f89k9wfjwns1csjh996",
13      "type": "partial",
14      "amount": "5000"
15    }
16  ]
17}

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.

201 Created

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "adj_01j1f9cx0g7skrg9kwsxmgxg5p",
4    "action": "refund",
5    "type": "partial",
6    "transaction_id": "txn_01j1f27bnwg90nggkgkf52hy34",
7    "subscription_id": "sub_01j1f28ywb5hn78y2y5tym9y4k",
8    "customer_id": "ctm_01j1f28efp7j4p1ae0hqnd144s",
9    "reason": "goodwill gesture",
10    "currency_code": "USD",
11    "status": "pending_approval",
12    "items": [
13      {
14        "id": "adjitm_01j1f9cx0g7skrg9kwszsbbxs2",
15        "item_id": "txnitm_01j1f28f89k9wfjwns1htt8bpw",
16        "type": "full",
17        "amount": "21666",
18        "proration": null,
19        "totals": {
20          "subtotal": "19900",

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'd like 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 the total of a manually-collected transaction (invoice) amount as a credit.

API

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

Get a transaction and extract items — optional
Get the transaction that you want to credit. Extract some information about transaction items if you only want to credit some line items.
Build request
Build a request that includes a list of transaction items and the amount to credit for each.
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 — optional

Adjustments are for transaction items, so you'll need to get the transaction that you want to create a credit for.

You can credit the total for a transaction, or just some of its line items. If you only want to credit some of the transaction items, extract some information about the transaction line items. You don't need to do this if you want to credit the total transaction.

GEThttps://api.paddle.com/transactions/{transaction_id}

transaction_idstring

Paddle ID of the transaction entity to work with.

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.

200 OK


147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
147        "grand_total": "1437041",
148        "fee": "0",
149        "earnings": "0",
150        "currency_code": "USD"
151      },
152      "payout_totals": null,
153      "adjusted_payout_totals": null,
154      "line_items": [
155        {
156          "id": "txnitm_01j1fcds3vh4rma21djdw6pd2f",
157          "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
158          "quantity": 20,
159          "totals": {
160            "subtotal": "1000000",
161            "tax": "88750",
162            "discount": "0",
163            "total": "1088750"
164          },
165          "product": {
166            "id": "pro_01gsz4vmqbjk3x4vvtafffd540",

Build request

Build a request that includes the type field, and optionally an items array.

Specify type to determine whether you want to credit the transaction total or particular items.

typestring

Type of adjustment. Use full to adjust the grand total for the related transaction. Include an items array when creating a partial adjustment. If omitted, defaults to partial.

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.

Include transaction_id for the transaction that your credit relates 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 recordkeeping 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 recordkeeping purposes.

Request

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
2  "action": "credit",
3  "transaction_id": "txn_01j1fcdrmgxnp2vw6qxtpr44mf",
4  "type": "partial",
5  "reason": "error",
6  "items": [
7    {
8      "item_id": "txnitm_01j1fcds3vh4rma21djq3pd3e7",
9      "type": "full"
10    },
11    {
12      "item_id": "txnitm_01j1fcds3vh4rma21djm79vf9e",
13      "type": "partial",
14      "amount": "100000"
15    }
16  ]
17}

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.

201 Created

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "adj_01j1fcvs6wpjbk0ymqbqcj7k2g",
4    "action": "credit",
5    "type": "partial",
6    "credit_applied_to_balance": false,
7    "transaction_id": "txn_01j1fcdrmgxnp2vw6qxtpr44mf",
8    "subscription_id": "sub_01j1fcex1ygrbc34pxvkz58tw5",
9    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
10    "reason": "error",
11    "currency_code": "USD",
12    "status": "approved",
13    "items": [
14      {
15        "id": "adjitm_01j1fcvs6wpjbk0ymqbqgdf6pg",
16        "item_id": "txnitm_01j1fcds3vh4rma21djq3pd3e7",
17        "type": "full",
18        "amount": "21666",
19        "proration": null,
20        "totals": {

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.

API

Dashboard

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

GEThttps://api.paddle.com/adjustments/{adjustment_id}/credit-note

adjustment_idstring

Paddle ID of the adjustment that you'd like to generate a credit note for.

Response

1
2
3
4
5
6
7
8
1{
2  "data": {
3    "url": "https://paddle-production-invoice-service-pdfs.s3.amazonaws.com/credit_notes/15839/crdnt_01j4scmgpbtbxap16573dtck9n/credit_notes_296-10016_Paddle-com.pdf"
4  },
5  "meta": {
6    "request_id": "e34d4a9c-2088-447d-a3a1-1da5ce74f507"
7  }
8}

Common errors

`adjustment_transaction_invalid_status_for_credit`	Transaction must be `billed` and manually collected to create a credit.
`adjustment_transaction_invalid_status_for_refund`	Transaction must be `completed` to create a refund.
`adjustment_pending_refund_request`	Transaction has a pending refund. Wait for the refund to move to `approved` or `rejected` before creating another.

Events

`adjustment.created`	Occurs when an adjustment is created.
`adjustment.updated`	Occurs when a refund adjustment status changes to `approved` or `rejected`.

Create and issue an invoice

Revise customer details on a billed or completed transaction

Adjustments entity overview

Refund or credit a transaction

How it works

Refunds

Credits

Chargebacks

Revise customer information

Revise a transaction

Create an adjustment

Create a refund

Get a transaction and extract items — optional

Response

Build request

Request

Create adjustment

Response

Handle refund status change — optional

Create a credit

Get a transaction and extract items — optional

Response

Build request

Request

Create adjustment

Response

Generate a credit note document

Response

Common errors

Events

Related pages