store/add-tax-rate adds a tax rate for a country, optionally narrowed to a state, in a given tax class.
If tax calculation is switched off for the store, it says so plainly — because the rate would then be stored and never applied.
At a glance
| Ability | store/add-tax-rate |
| Toolset | WooCommerce — toolset/woocommerce |
| Group | WooCommerce › Store Configuration |
| Requires | WooCommerce, active on the site |
| Capability | manage_options |
| Safety | Writes data |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
This records a decision somebody else made
What rate to set is a decision about the business and its obligations, not about the software. This records the decision; it does not make it. A wrong rate here does not error — it under- or over-charges every affected customer until somebody notices, which is typically at the next return.
How it works
The check on tax calculation exists because the failure is otherwise invisible. The rate is added, the response is a success, the rates screen shows it correctly, and no customer is ever charged it. Saying so at the point of the write is the only place anybody will read it.
Priority decides which rate applies when several match: only one rate per priority is used, and rates at different priorities compound. That is how a store charges a state tax on top of a federal one, and it is also how a store accidentally charges twice.
The shipping flag decides whether the rate applies to shipping as well as goods, which varies by jurisdiction and is not something to guess at.
The label is what appears at checkout, so it should be the name a customer recognises — VAT, GST, Sales Tax.
Not idempotent: adding the same rate twice creates two rates, which at the same priority is a conflict and at different priorities is double taxation.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
country | string | Yes | Two-letter country code, for example GB. |
rate | string | Yes | The percentage, for example 20 for twenty per cent. |
state | string | No | State or county code. |
name | string | No | Label shown at checkout, for example VAT. |
class | string | No — defaults to standard | Tax class. |
priority | integer | No | Priority; only one rate per priority applies. |
shipping | boolean | No | Whether the rate also applies to shipping. |
confirm | boolean | Yes — must be true | The irreversibility gate. Without it the call is refused before anything is touched. |
What comes back
| Name | Type | What it is |
|---|---|---|
tax_rate_id | integer | The rate that was created. |
taxes | array | The rates in that class afterwards. |
note | string | Any warning, including tax calculation being switched off. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Add 20% VAT for the UK.
It resolves to one call:
{
"ability": "store/add-tax-rate",
"parameters": {
"country": "GB",
"rate": "20",
"name": "VAT",
"shipping": true,
"confirm": true
}
}Worth knowing
- A rate added while tax calculation is off is stored and never applied. The response says so.
- Only one rate per priority applies; different priorities compound.
- Not idempotent — a duplicate rate is a real problem.
- Whether shipping is taxed varies by jurisdiction.
Related abilities
- Get Tax Rates — read what exists first
- Update Store Settings — switch tax calculation on
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category