What's new?
We've added a new type field that you can use when creating an adjustment to specify that the grand total for a transaction should be refunded or credited.
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
How it works
You can use adjustments to refund or credit all or part of a transaction and its items.
Previously, to refund or credit all of a transaction then you'd need to get and extract information about all the items on a transaction, then build an array of adjustment items.
We've updated the Paddle API so now you can pass a new type field when creating an adjustment. When type is full, you don't need to specify an array of items. Paddle creates an adjustment for the grand total for a transaction.
If omitted, type default to partial, which mirrors the existing behavior.
Examples
Request
This example creates a refund for all items on an automatically-collected transaction.
/adjustments { "action": "refund", "transaction_id": "txn_01jc679dkb1a5ytsn6vat4m4vt", "reason": "error", "type": "full"}{ "data": { "id": "adj_01jee666qcymxwrqy007wms2xa", "action": "refund", "type": "full", "transaction_id": "txn_01jc679dkb1a5ytsn6vat4m4vt", "subscription_id": "sub_01jc67mq0yhherf6rmrtf4n2hh", "customer_id": "ctm_01jc67jy72jegfk1k72wk87wrg", "reason": "error", "currency_code": "USD", "status": "pending_approval", "items": [ { "id": "adjitm_01jee666qwy5kk7zswwwtg4b4r", "item_id": "txnitm_01jc67jykqp90vmqchzxax3dgs", "type": "full", "amount": "194381", "proration": null, "totals": { "subtotal": "194381", "tax": "0", "total": "194381" } }, { "id": "adjitm_01jee666qwy5kk7zswx072qm45", "item_id": "txnitm_01jc67jykqp90vmqcj01cb8ykr", "type": "full", "amount": "154727", "proration": null, "totals": { "subtotal": "154727", "tax": "0", "total": "154727" } }, { "id": "adjitm_01jee666qwy5kk7zswwsg63j6p", "item_id": "txnitm_01jc67jykqp90vmqchzt0wfqfh", "type": "full", "amount": "233260", "proration": null, "totals": { "subtotal": "233260", "tax": "0", "total": "233260" } } ], "tax_rates_used": [ { "tax_rate": "0", "totals": { "subtotal": "582368", "tax": "0", "total": "582368" } } ], "totals": { "subtotal": "582368", "tax": "0", "total": "582368", "fee": "29507", "earnings": "552861", "currency_code": "USD" }, "payout_totals": { "subtotal": "72652", "tax": "0", "total": "72652", "fee": "3681", "earnings": "68971", "currency_code": "USD" }, "created_at": "2024-12-06T14:32:40.965154Z", "updated_at": "2024-12-06T14:32:40.965154Z" }, "meta": { "request_id": "cc6567d0-1fdb-4e56-824e-8d801b02137b" }}Next steps
This change is available in version 1 of the Paddle API.
It's a non-breaking change, meaning it doesn't impact existing integrations.
Check out our refund or credit a transaction guide to get started.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| Adjustment | adjustment.type | + Added | Field |
| Determines whether an adjustment is for the grand total of a transaction or some items against it. | |||