Rolling out
See the tax amount charged after credits are applied
Use a new field in the transaction totals object to see the tax amount charged after credits are applied to a transaction.
What's new?
We've added a new grand_total_tax field to transaction totals that shows the proportional tax amount charged when credits are applied to a transaction.
This change is live on sandbox accounts right now, and rolling out to live accounts. It's scheduled to be available on all accounts by the end of January 2026.
Breakdown of the total for a transaction.
Net tax amount included in the grand total.
How it works
You can access the tax field in transaction.details.totals to see the tax amount for a transaction.
When a credit is applied to a transaction, the tax field shows the full tax amount calculated on the transaction total before any credits are applied.
We've added a new grand_total_tax field to show the tax amount that's charged after any credits are applied. This means you can better understand how credits affect transactions and more easily reconcile your payout breakdowns.
Where there are no credits applied, grand_total_tax is the same as tax. For transactions created before this change, grand_total_tax is the tax value to maintain consistency.
Example
Assuming a transaction for $100 with a 20% tax rate:
| Field | Description | Example |
|---|---|---|
| Subtotal | Subtotal before discount, tax, and deductions. | $100 |
| Tax | Total tax on the subtotal (20%). | $20 |
| Total | Total after discount and tax. | $120 |
| Credit | Total credit applied to this transaction. | $90 |
| Grand total | Total due on a transaction after credits but before any payments. | $30 |
| Grand total tax | Net tax amount included in the grand total. | $5 |
Summary of changes
Fields
This is a summary of the new fields in the Paddle API:
| Entity | Field | Kind |
|---|---|---|
| Transaction | details.totals.grand_total_tax | New field |
| Transaction | details.adjusted_totals.grand_total_tax | New field |
Next steps
This change is rolling out on version 1 of the Paddle API now. It's scheduled to be fully available on all accounts by the end of January 2026. It's available on all sandbox accounts for testing and development.
It's a non-breaking change, meaning it doesn't impact existing integrations. For transactions created before this change rolled out, grand_total_tax is the tax value to maintain consistency.
You can list transactions or get a transaction using the API to see the new grand_total_tax field.