| name | commerce-tax |
| description | Calculate taxes and manage tax rates. Use when running `stateset-tax`, calculating cart tax, validating exemptions, or configuring tax jurisdiction settings. |
Commerce Tax
Calculate taxes and manage tax jurisdiction settings.
How It Works
- Identify jurisdiction from the shipping address (
postal_code, region, country).
- Look up applicable tax rates for the jurisdiction.
- Calculate tax for individual items or entire carts.
- Apply exemptions when a valid certificate exists.
- Report tax breakdown by jurisdiction and line item.
Usage
- CLI:
stateset-tax ... or stateset "calculate tax for cart CART-123"
- Writes require
--apply.
- MCP tools:
calculate_tax, calculate_cart_tax, get_tax_rate, list_tax_rates, create_tax_exemption, validate_tax_exemption.
Permissions
- Read:
calculate_tax, calculate_cart_tax, get_tax_rate, list_tax_rates, validate_tax_exemption — no --apply needed.
- Write:
create_tax_exemption — requires --apply.
Examples
stateset tax calculate --cart CART-123 --region US-CA
stateset tax rate get --jurisdiction US-CA --category electronics
stateset tax exemption create --customer cust_456 --certificate EX-2026-789 --apply
stateset tax rates list --country US --format json
Status Flows
Exemption: Submitted -> Validated -> Active (or Expired/Revoked)
Output
{"tax_total":7.25,"jurisdiction":"US-CA","rate":0.0725,"exemptions_applied":0,"line_items":[{"sku":"WIDGET-001","tax":3.63}],"order_id":"ord_789","amount":103.63,"status":"calculated"}
Present Results to User
- Tax rates used, jurisdiction, and effective date.
- Exemptions applied, if any, with certificate IDs.
- Final tax totals, per-line breakdown, and rounding method.
- Any tax-exempt items flagged.
Troubleshooting
- Missing address fields: collect
postal_code and region before calculating.
- Invalid exemption: verify certificate number, expiry date, and jurisdiction match.
- Rate not found: ensure the jurisdiction has been configured with
create_tax_rate.
- Zero tax on taxable item: check if an unintended exemption is active for the sku.
Error Codes
JURISDICTION_NOT_FOUND: No tax rates configured for the given region.INVALID_EXEMPTION: Tax exemption certificate is expired or does not match jurisdiction.MISSING_ADDRESS: Shipping address fields required for tax calculation are absent.
Related Skills
- commerce-checkout — applies tax during cart checkout
- commerce-invoices — includes tax breakdown on invoices
- commerce-currency — currency conversion for cross-border tax
References
- references/tax-commands.md
- /home/dom/stateset-icommerce/cli/.claude/agents/tax.md
