> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Create partial refunds using tax exclusive amounts

Use the new `tax_mode` field when creating an adjustment to specify that amounts for a partial refund are tax exclusive. Paddle calculates tax on the amounts for you.

---

## What's new?

We've added a new `tax_mode` field that you can use when [creating an adjustment](https://developer.paddle.com/build/transactions/create-transaction-adjustments.md) to specify that amounts are exclusive of tax.

- **tax_mode** (string): 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](https://developer.paddle.com/api-reference/adjustments/overview.md) to refund or credit all or part of a [transaction](https://developer.paddle.com/api-reference/transactions/overview.md) 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](https://developer.paddle.com/build/transactions/create-transaction-adjustments.md) 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.

{% callout type="info" %}
You can only include `tax_mode` for partial line item refunds. You can't specify that credits are exclusive of tax.
{% /callout %}

## Examples

### Request

This example creates a partial refund for a tax exclusive amount on a transaction.

{% api-example method="POST" path="/adjustments" %}

```json {% title="Request" %}
{
  "action": "refund",
  "transaction_id": "txn_01jq9da1hjv6q1zevhm70a6m72",
  "reason": "error",
  "tax_mode": "external",
  "items": [
    {
      "item_id": "txnitm_01jq9da1k3rvf1wtxncxk9qbe8",
      "type": "partial",
      "amount": "1000"
    }
  ]
}
```

```json {% title="Response" %}
{
  "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"
  }
}
```

{% /api-example %}

## 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](https://developer.paddle.com/build/transactions/create-transaction-adjustments.md) to get started.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `adjustment.tax_mode` | Field | added | Adjustment | Determines whether the amounts to be adjusted are inclusive or exclusive of tax. |
| `adjustment_tax_mode_not_allowed` | Field | added | Adjustment | Returned when including tax_mode for an adjustment that's a credit, or where the type is full. |