# Tax (/ai/reference/store/tax)

Toolset `tax`, 13 tools.

## Records [#records]

### `tax_provider` [#tax_provider]

A tax calculation provider a tax region can use. Its id is the provider_id of a tax region.

- Permission: `settings.read`
- Tools: `tax_provider_list`

### `tax_rate` [#tax_rate]

A tax rate of a tax region: its percentage (27 means 27%), code, whether it is the default of the region, and on get the rules that apply it to certain products or product types instead of the default.

- Permission: `settings.read`
- Tools: `tax_rate_list`, `tax_rate_get`
- Sorts: `created_at`, `name`, `rate`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |
| `tax_region_id` | list of string |  |  |
| `is_default` | string |  | one of "true", "false" |

### `tax_region` [#tax_region]

The tax rules of one country (or of a province inside a country, with parent_id set): which tax provider calculates it and, on get, its tax rates with their rules and the province regions under it. Rows are compact; get has the rates.

- Permission: `settings.read`
- Tools: `tax_region_list`, `tax_region_get`
- Sorts: `created_at`, `country_code`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |
| `country_code` | list of string |  | Lower-case ISO codes, e.g. ["hu"] |
| `province_code` | list of string |  |  |
| `parent_id` | list of string |  | Only the provinces of these tax regions |

## Actions [#actions]

### `tax_rate_add_rule` [#tax_rate_add_rule]

Apply a tax rate to one product or product type.

- Action key: `tax_rate.add_rule`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tax_rate_id` | string | yes | Tax rate ID (txr_…) |
| `rule` | object | yes |  |
| `rule.reference` | string | yes | What the rule matches, e.g. product, product_type. at least 1 characters |
| `rule.reference_id` | string | yes | The id of that product or product type. at least 1 characters |

Example input:

```json
{
  "tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c",
  "rule": {
    "reference": "product_type",
    "reference_id": "019bb640-bbc5-7c31-9d38-37305d1c7ef0"
  }
}
```

### `tax_rate_create` [#tax_rate_create]

Add a tax rate to a tax region.

rate is a percentage (27 for 27%). Only one rate per region is the default. rules apply the rate to chosen products or product types instead of the default; each rule names a reference and its id.

- Action key: `tax_rate.create`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tax_region_id` | string | yes |  |
| `name` | string | yes | at least 1 characters |
| `code` | string | yes | at least 1 characters |
| `rate` | number |  | 0 to 100 |
| `is_default` | boolean |  |  |
| `is_combinable` | boolean |  |  |
| `rules` | list of object |  |  |
| `rules[].reference` | string | yes | What the rule matches, e.g. product, product_type. at least 1 characters |
| `rules[].reference_id` | string | yes | The id of that product or product type. at least 1 characters |

Example input:

```json
{
  "tax_region_id": "019bb78a-9066-71df-9b1b-7a100f98c712",
  "name": "ÁFA 5%",
  "code": "AFA5",
  "rate": 5
}
```

### `tax_rate_delete` [#tax_rate_delete]

Delete a tax rate from its tax region.

- Action key: `tax_rate.delete`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tax_rate_id` | string | yes | Tax rate ID (txr_…) |

Example input:

```json
{
  "tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c"
}
```

### `tax_rate_remove_rule` [#tax_rate_remove_rule]

Stop applying a tax rate to the product or product type of a rule.

- Action key: `tax_rate.remove_rule`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tax_rate_id` | string | yes | Tax rate ID (txr_…) |
| `rule_id` | string | yes | Rule ID from the rules of tax_rate_get |

Example input:

```json
{
  "tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c",
  "rule_id": "019bb795-4308-77ed-a2b9-39d1cdb2e554"
}
```

### `tax_rate_update` [#tax_rate_update]

Change the percentage, name, code or default flag of a tax rate.

Only the fields passed change. rules replaces the whole rule list; use tax_rate_add_rule and tax_rate_remove_rule to change single rules. A changed rate applies to new carts and orders, not to orders already placed.

- Action key: `tax_rate.update`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tax_rate_id` | string | yes | Tax rate ID (txr_…) |
| `name` | string |  | at least 1 characters |
| `code` | string |  | at least 1 characters |
| `rate` | number |  | 0 to 100 |
| `is_default` | boolean |  |  |
| `is_combinable` | boolean |  |  |
| `rules` | list of object |  |  |
| `rules[].reference` | string | yes | What the rule matches, e.g. product, product_type. at least 1 characters |
| `rules[].reference_id` | string | yes | The id of that product or product type. at least 1 characters |

Example input:

```json
{
  "tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c",
  "rate": 27
}
```

### `tax_region_create` [#tax_region_create]

Add the tax rules of a country, or of a province under an existing tax region.

A country needs a provider_id from tax_provider_list. A province region needs parent_id and province_code. default_tax_rate creates the region's default rate in the same step (rate is a percentage, 27 for 27%). A country has one tax region.

- Action key: `tax_region.create`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country_code` | string | yes |  |
| `provider_id` | string or null |  |  |
| `province_code` | string or null |  |  |
| `parent_id` | string or null |  |  |
| `default_tax_rate` | object |  |  |
| `default_tax_rate.rate` | number |  | 0 to 100 |
| `default_tax_rate.code` | string | yes | at least 1 characters |
| `default_tax_rate.name` | string | yes | at least 1 characters |
| `default_tax_rate.is_combinable` | boolean |  |  |

Example input:

```json
{
  "country_code": "hu",
  "provider_id": "tp_system",
  "default_tax_rate": {
    "rate": 27,
    "code": "AFA27",
    "name": "ÁFA 27%"
  }
}
```

### `tax_region_delete` [#tax_region_delete]

Delete the tax rules of a country or province, with its tax rates.

Orders in that country are no longer taxed by it until a tax region is set up again.

- Action key: `tax_region.delete`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tax_region_id` | string | yes | Tax region ID (txreg_…) |

Example input:

```json
{
  "tax_region_id": "019bb78a-9066-71df-9b1b-7a100f98c712"
}
```

### `tax_region_update` [#tax_region_update]

Change a tax region's provider or province code.

- Action key: `tax_region.update`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tax_region_id` | string | yes | Tax region ID (txreg_…) |
| `provider_id` | string |  |  |
| `province_code` | string or null |  |  |

Example input:

```json
{
  "tax_region_id": "019bb78a-9066-71df-9b1b-7a100f98c712",
  "provider_id": "tp_system"
}
```