Tax
The 13 tools of the Tax toolset in the Store area, with their permissions, approval rules and inputs.
On this page
Toolset tax, 13 tools.
Records
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
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
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
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:
{
"tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c",
"rule": {
"reference": "product_type",
"reference_id": "019bb640-bbc5-7c31-9d38-37305d1c7ef0"
}
}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:
{
"tax_region_id": "019bb78a-9066-71df-9b1b-7a100f98c712",
"name": "ÁFA 5%",
"code": "AFA5",
"rate": 5
}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:
{
"tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c"
}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:
{
"tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c",
"rule_id": "019bb795-4308-77ed-a2b9-39d1cdb2e554"
}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:
{
"tax_rate_id": "019bb77c-4027-71d6-9021-06becc88d52c",
"rate": 27
}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:
{
"country_code": "hu",
"provider_id": "tp_system",
"default_tax_rate": {
"rate": 27,
"code": "AFA27",
"name": "ÁFA 27%"
}
}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:
{
"tax_region_id": "019bb78a-9066-71df-9b1b-7a100f98c712"
}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:
{
"tax_region_id": "019bb78a-9066-71df-9b1b-7a100f98c712",
"provider_id": "tp_system"
}