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.
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:
- 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 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:
Get a transaction and extract items
Get the transaction that you'd like to refund, then extract transaction item IDs.
Build a request that includes a list of transaction items and the amount to refund for each.
Send the request to create your adjustment. Paddle creates it. Its status is
pending approval
orapproved
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
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.
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, passingcompleted
as a value to thestatus
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.
162163164165166167168169170171172173174175176177178179180181162 "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 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
.
List of transaction items to adjust.
Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_
.
Type of adjustment for this transaction item. Include amount
when creating a partial
adjustment.
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.
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 ofrefund
.- 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.
How this adjustment impacts the related transaction. Most refund
adjustments must be approved by Paddle, and are created with the status pending_approval
.
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.
123456789101112131415161{
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.
12345678910111213141516171819201{
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:
Get a transaction and extract items
Get the transaction that you'd like to credit, then extract transaction item IDs.
Build a request that includes a list of transaction items and the amount to credit for each.
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.
Paddle ID of the transaction entity to work with.
Transactions must be
billed
orpast_due
to create a credit for them. You can get billed and past due transactions using the list transactions operation, passingbilled,past_due
as a value to thestatus
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.
147148149150151152153154155156157158159160161162163164165166147 "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 an items
array. Your array should include an object for each transaction item that you'd like 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
.
List of transaction items to adjust.
Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_
.
Type of adjustment for this transaction item. Include amount
when creating a partial
adjustment.
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.
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 ofcredit
.- 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.
How this adjustment impacts the related transaction.
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.
123456789101112131415161{
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, credit_applied_to_balance
is false
meaning that the amount was applied to the billed transaction, reducing the balance to pay.
12345678910111213141516171819201{
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",
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'd like to generate a credit note for.
Paddle ID of the adjustment that you'd like to generate a credit note for.
Response
123456781{
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 . |
Related pages
- Refund or credit a transaction
- How it works
- Refunds
- Credits
- Chargebacks
- Create a refund
- Get a transaction and extract items
- Build request
- Create adjustment
- Handle refund status change — optional
- Create a credit
- Get a transaction and extract items
- Build request
- Create adjustment
- Generate a credit note document
- Common errors
- Events
- Related pages