See tax rates applied to adjustments in webhooks

What's new?

We've added a new tax_rates_used array to the adjustment.created and adjustment.updated webhook payloads. This groups adjustment amounts by tax rate, showing the subtotal, tax, and total for each rate applied.

How it works

You can use adjustments to refund or credit all or part of a transaction and its items. Previously, webhook payloads included the adjustment total broken down by subtotal and tax, but didn't show which tax rates were applied to the adjustment.

We've updated the adjustment.created and adjustment.updated webhook payloads to include a tax_rates_used array. Each object in the array represents a unique tax rate applied to the adjustment, with aggregated subtotal, tax, and total amounts for that rate. Most adjustments will have a single tax rate, but the array structure supports cases where a transaction included items taxed at different rates.

This mirrors the tax rate information available on transaction and adjustment entities, providing a consistent view of tax across the full lifecycle of a transaction. It makes it easier to reconcile adjustments for accounting purposes and handle tax reporting accurately.

Examples

This example shows an adjustment where the refund is taxed at 20%.

1
2
3
4
5
6
7
8
9
10
1"tax_rates_used": [
2  {
3    "tax_rate": "0.2",
4    "totals": {
5      "subtotal": "416",
6      "tax": "83",
7      "total": "499"
8    }
9  }
10]

This example shows an adjustment split across 0% and 25% tax rates.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
1"tax_rates_used": [
2  {
3    "tax_rate": "0",
4    "totals": {
5      "subtotal": "1000",
6      "tax": "0",
7      "total": "1000"
8    }
9  },
10  {
11    "tax_rate": "0.25",
12    "totals": {
13      "subtotal": "10999",
14      "tax": "2750",
15      "total": "13749"
16    }
17  }
18]

tax_rates_used is null if no tax rates apply to the adjustment.

1
1"tax_rates_used": null

Summary of changes

This is a summary of the new fields in webhooks:

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. All new adjustment webhook payloads include the tax_rates_used field.

Learn more