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, as they're considered issued invoices. They get an invoice number and are sent to your customers, so changes to them must be correctly recorded along with the original transaction.

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 creates some kinds of adjustments for you:

• When you make changes to a subscription — like upgrading or downgrading — and choose to prorate, Paddle creates a credit if the customer has paid more than they should.
• When a customer disputes a purchase with their card provider or payment platform, Paddle creates an adjustment with the type chargeback or chargeback_warning.

You can only create credit and refund adjustments. chargeback and chargeback_warning adjustments are created by Paddle for you.

You can't create an adjustment for more than the transaction total.

Before you begin

Adjustments are for transactions, so you'll need to get or create a transaction that you'd like to adjust. Transactions must be billed or completed.

Adjustments work at the transaction item level, so extract transaction item IDs and amounts from the transaction.

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
112        "subtotal": "74900",
113        "tax": "14980",
114        "total": "89880",
115        "fee": "4544",
116        "earnings": "70356",
117        "currency_code": "USD"
118      },
119      "line_items": [
120        {
121          "id": "txnitm_01h04sdmkts9z5jafn5aajtbdh",
122          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
123          "quantity": 10,
124          "totals": {
125            "subtotal": "30000",
126            "tax": "6000",
127            "discount": "0",
128            "total": "36000"
129          },
130          "product": {
131            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",

Create a refund

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

Refunds must be reviewed by Paddle. They're created with the status pending_approval, before moving to approved or rejected once reviewed.

You can't create an adjustment for a transaction that has a refund that's pending_approval.

Send a POST request to the /adjustments endpoint.

Request

In your request, include the transaction_id of the transaction that you'd like to refund, along with the item_id of any transaction items that you'd like to refund.

If crediting the total amount of an item, set the type as full. To create a partial credit, set the type as partial and include the amount you'd like to credit. The amount should include tax.

Set the action to refund.

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

Response

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

Refunds are pending_approval until reviewed by Paddle. The adjustment.updated event occurs when its status changes.

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_01h04sxc82g4b6wrpn4wcdr5g6",
4    "action": "refund",
5    "transaction_id": "txn_01h04sd6x5rtz58mqqydwzjs46",
6    "subscription_id": "sub_01h04sejb3nz8j69hq6j2t6pgh",
7    "customer_id": "ctm_01h04sdmcn9dtypgwrscds51hj",
8    "reason": "goodwill gesture",
9    "currency_code": "USD",
10    "status": "pending_approval",
11    "items": [
12      {
13        "id": "adjitm_01h04sxc82g4b6wrpn4z2bxevr",
14        "item_id": "txnitm_01h04sdmkts9z5jafn5aqvnae6",
15        "type": "full",
16        "amount": "30000",
17        "proration": null,
18        "totals": {
19          "subtotal": "25000",
20          "tax": "5000",

Create a credit

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

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 your issued invoice, so the amount the customer owes is reduced.

Credits don't need approval from Paddle.

You can't create credits for automatically-collected transactions. Paddle creates and manages credits for automatically-collected transactions when you make changes to the related subscription and choose to prorate.

Send a POST request to the /adjustments endpoint.

Request

In your request, include the transaction_id of the transaction that you'd like to credit, along with the item_id of any transaction items that you'd like to credit. To reduce the amount owed on an invoice, the transaction must be billed.

If crediting the total amount of an item, set the type as full. To create a partial credit, set the type as partial and include the amount you'd like to credit. The amount should include tax.

Set the action to credit.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
1{
2  "action": "credit",
3  "transaction_id": "txn_01h04vsbhqc62t8hmd4z3b578c",
4  "reason": "credit invoice",
5  "items": [
6    {
7      "item_id": "txnitm_01h04vsbkm3czs3y6d4d8b7kgn",
8      "type": "full"
9    },
10    {
11      "item_id": "txnitm_01h04vsbkm3czs3y6d4dt28brt",
12      "type": "full"
13    }
14  ]
15}

Response

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

Where a credit is used to reduce the amount due on an issued invoice (a manually-collected transaction), credit_applied_to_balance is false.

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_01h04vvc28rmrp86b7zwdak82k",
4    "action": "credit",
5    "credit_applied_to_balance": false,
6    "transaction_id": "txn_01h04vsbhqc62t8hmd4z3b578c",
7    "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
8    "customer_id": "ctm_01h04sdmcn9dtypgwrscds51hj",
9    "reason": "credit invoice",
10    "currency_code": "USD",
11    "status": "approved",
12    "items": [
13      {
14        "id": "adjitm_01h04vvc28rmrp86b7zzzfwqc0",
15        "item_id": "txnitm_01h04vsbkm3czs3y6d4d8b7kgn",
16        "type": "full",
17        "amount": "1479432",
18        "proration": null,
19        "totals": {
20          "subtotal": "1232860",

Events

Related pages