What's new?
We've added a new tax_mode field that you can use when creating an adjustment to specify that amounts are exclusive of tax.
Whether the amounts to be adjusted are inclusive or exclusive of tax. If internal, adjusted amounts are considered to be inclusive of tax. If external, Paddle calculates the tax and adds it to the amounts provided
How it works
You can use adjustments to refund or credit all or part of a transaction and its items. You can refund all or part of a line item, useful for cases where you want to refund some users for a plan or a certain number of credits.
When passing an amount for partial line item refunds, amounts are considered inclusive of tax. This means that Paddle interprets the amounts you provide as already including tax, automatically calculating the pretax and tax components internally.
We've updated the Paddle API so now you can pass a new tax_mode field when creating an adjustment that you can use to determine if amounts should be inclusive or exclusive of tax. When tax_mode is external, amounts are considered exclusive of tax. Paddle calculates the tax on the amounts you provide.
For example, if you create a request for a partial line item refund of $110:
| Amount passed in request | $110 | $110 |
| Tax mode | internal | external |
| Tax rate | 10% | 10% |
| Subtotal | $100 | $110 |
| Total tax | $10 | $11 |
| Grand total | $110 | $121 |
If omitted, tax_mode defaults to internal, which mirrors the existing behavior.
You can only include tax_mode for partial line item refunds. You can't specify that credits are exclusive of tax.
Examples
Request
This example creates a partial refund for a tax exclusive amount on a transaction.
/adjustments { "action": "refund", "transaction_id": "txn_01jq9da1hjv6q1zevhm70a6m72", "reason": "error", "tax_mode": "external", "items": [ { "item_id": "txnitm_01jq9da1k3rvf1wtxncxk9qbe8", "type": "partial", "amount": "1000" } ]}{ "data": { "id": "adj_01jqbggxraw0j29rsjm3tstzft", "action": "refund", "type": "partial", "transaction_id": "txn_01jq9da1hjv6q1zevhm70a6m72", "subscription_id": "sub_01j1aes7zkfyzkgz8dx7q242by", "customer_id": "ctm_01hsx6vhb5j6ex73wy1cnjwxyq", "reason": "error", "currency_code": "USD", "status": "approved", "items": [ { "id": "adjitm_01jqbggxraw0j29rsjm7j5ta5r", "item_id": "txnitm_01jq9da1k3rvf1wtxncxk9qbe8", "type": "partial", "amount": "1200", "proration": null, "totals": { "subtotal": "1000", "tax": "200", "total": "1200" } } ], "tax_rates_used": [ { "tax_rate": "0.2", "totals": { "subtotal": "1000", "tax": "200", "total": "1200" } } ], "totals": { "subtotal": "1000", "tax": "200", "total": "1200", "fee": "85", "earnings": "915", "currency_code": "USD" }, "payout_totals": { "subtotal": "1000", "tax": "200", "total": "1200", "fee": "85", "earnings": "915", "currency_code": "USD" }, "created_at": "2025-03-27T09:56:51.091685Z", "updated_at": "2025-03-27T10:00:01.753771Z" }, "meta": { "request_id": "a6cd5efb-ff61-48b8-91d9-b7f22a0f1d12" }}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. tax_mode defaults to internal, meaning there are no changes required.
Check out our refund or credit a transaction guide to get started.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| Adjustment | adjustment.tax_mode | + Added | Field |
| Determines whether the amounts to be adjusted are inclusive or exclusive of tax. | |||
| Adjustment | adjustment_tax_mode_not_allowed | + Added | Field |
| Returned when including tax_mode for an adjustment that's a credit, or where the type is full. | |||