Commerce Tax

Commerce Tax

Calculate taxes and manage tax jurisdiction settings.

How It Works

1. Identify jurisdiction from the shipping address (postal_code, region, country).
2. Look up applicable tax rates for the jurisdiction.
3. Calculate tax for individual items or entire carts.
4. Apply exemptions when a valid certificate exists.
5. 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