Refund or credit a transaction
Create an adjustment to record a change to a billed or completed transaction, like a refund or credit. Refunds 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.
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
orchargeback_warning
.
You can only create
credit
andrefund
adjustments.chargeback
andchargeback_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
.
API
List transactions by making a GET request to the /transactions
endpoint. Work your way through the results to find the transaction that you'd like to work with.
Dashboard
Head to Paddle > Transactions, then use the search box to find the transaction you'd like to cancel. Copy the ID from the transaction page.
Adjustments work at the transaction item level, so extract transaction item IDs and amounts from the transaction.
112113114115116117118119120121122123124125126127128129130131112 "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 toapproved
orrejected
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
.
123456789101112131415161{
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.
12345678910111213141516171819201{
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
.
1234567891011121314151{
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
.
12345678910111213141516171819201{
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",
Notifications
adjustment.created | Occurs when an adjustment is created. |
adjustment.updated | Occurs when an adjustment is updated. Only occurs when its status changes from pending_approval to approved . |