Create partial refunds using tax exclusive amounts

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.

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:

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
1{
2  "action": "refund",
3  "transaction_id": "txn_01jq9da1hjv6q1zevhm70a6m72",
4  "reason": "error",
5  "tax_mode": "external",
6  "items": [
7    {
8      "item_id": "txnitm_01jq9da1k3rvf1wtxncxk9qbe8",
9      "type": "partial",
10      "amount": "1000"
11    }
12  ]
13}

Response

If successful, the response includes the new adjustment entity. The totals across the adjustment include tax calculated on top of the amounts passed.

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_01jqbggxraw0j29rsjm3tstzft",
4    "action": "refund",
5    "type": "partial",
6    "transaction_id": "txn_01jq9da1hjv6q1zevhm70a6m72",
7    "subscription_id": "sub_01j1aes7zkfyzkgz8dx7q242by",
8    "customer_id": "ctm_01hsx6vhb5j6ex73wy1cnjwxyq",
9    "reason": "error",
10    "currency_code": "USD",
11    "status": "approved",
12    "items": [
13      {
14        "id": "adjitm_01jqbggxraw0j29rsjm7j5ta5r",
15        "item_id": "txnitm_01jq9da1k3rvf1wtxncxk9qbe8",
16        "type": "partial",
17        "amount": "1200",
18        "proration": null,
19        "totals": {
20          "subtotal": "1000",

Summary of changes

Fields

This is a summary of the changes to fields in the Paddle API:

Errors

This is a summary of the changes to errors in the Paddle API:

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.

Learn more