Refund or credit a transaction

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.

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.

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:

• 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 original payment was made using a payment method other than wire transfer.

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 or part-pay for future 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'd like to remove. Paddle automatically applies the credit to the issued invoice, so the amount the customer owes is reduced.

Credits don't need approval from Paddle.

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.
• For chargebacks where we don't get an early warning, we create an adjustment with the type chargeback for the disputed amount.
• 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'd like 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'd like 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.

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

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.

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

Create adjustment

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

Response

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

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    "transaction_id": "txn_01j1f27bnwg90nggkgkf52hy34",
6    "subscription_id": "sub_01j1f28ywb5hn78y2y5tym9y4k",
7    "customer_id": "ctm_01j1f28efp7j4p1ae0hqnd144s",
8    "reason": "goodwill gesture",
9    "currency_code": "USD",
10    "status": "pending_approval",
11    "items": [
12      {
13        "id": "adjitm_01j1f9cx0g7skrg9kwszsbbxs2",
14        "item_id": "txnitm_01j1f28f89k9wfjwns1htt8bpw",
15        "type": "full",
16        "amount": "21666",
17        "proration": null,
18        "totals": {
19          "subtotal": "19900",
20          "tax": "1766",

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 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'd like 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'd like to create a credit for and extract some information about its line items.

Transactions must be billed or completed to create a credit for them. You can get billed and completed transactions using the list transactions operation, passing billed,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.

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

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.

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

Create adjustment

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

Response

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

In this example, the adjustment is for a transaction that is billed so credit_applied_to_balance is false. The amount was applied to the billed transaction, reducing the balance to pay.

For completed transactions, credit_to_balance is true. The amount is added to a credit balance for a customer and used to pay future transactions.

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    "credit_applied_to_balance": false,
6    "transaction_id": "txn_01j1fcdrmgxnp2vw6qxtpr44mf",
7    "subscription_id": "sub_01j1fcex1ygrbc34pxvkz58tw5",
8    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
9    "reason": "error",
10    "currency_code": "USD",
11    "status": "approved",
12    "items": [
13      {
14        "id": "adjitm_01j1fcvs6wpjbk0ymqbqgdf6pg",
15        "item_id": "txnitm_01j1fcds3vh4rma21djq3pd3e7",
16        "type": "full",
17        "amount": "21666",
18        "proration": null,
19        "totals": {
20          "subtotal": "19900",

Events

Related pages