Calculate tax from buyer geography

Purpose

Commerce determines line tax from the configured provider and the buyer’s applicable location.

How It Works

An administrator prepares tax zones and their effective rates through the API. During calculation Commerce chooses the matching location and applicable product-type rates. The result retains component amounts so staff can understand the line’s tax. Checkout and display calculation treat absent address information differently. An invalid rate interval or country selection prevents saving the configuration. Staff currently edit Accounting tax configuration in the console, which does not make it the active Commerce provider. The product should choose one coherent ownership and configuration path before designing tax administration.

Relationships

The calculate and explain a buyer’s item price capability supplies related configuration or assessment used in this work.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Each taxable line is taxed by the most specific zone the purchaser’s address falls in.A purchase that requires an address to be taxed is prevented from being placed without one.
Surfaces: api
Intent sources: services-commerce:docs/milestones/plans/COMM-realignment-2026-10-22.md (proposed, awaiting Andrew)

Controls

19 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.tax-zones.read`	api	tenant
`commerce.tax-zones.create`	api	tenant
`commerce.tax-zones.update`	api	tenant
`commerce.tax-zones.delete`	api	tenant
`commerce.tax-zones.bulk`	api	tenant

Business Rules

10 rules, 8 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	A tax zone uses an assigned two-letter country code, optionally narrowed by region and postal prefix; invalid country codes are refused on the country field. no proof recorded yet	validation	api, database	test services-commerce:modules/configuration/tests/e2e/tax-zones.e2e.spec.js#answers 400 to a country code that is not two upper-case letters, naming the field
`02`must prove Proposed	A tax rate requires a name, an integer number of basis points within the supported ceiling, and dates whose start does not exceed their end. no proof recorded yet	validation	api, database	test services-commerce:modules/configuration/tests/e2e/tax-zones.e2e.spec.js#answers 400 to a rate past the ceiling and to a rate without a name, naming the field
`03`must prove Proposed	Tax edits reject whitespace-only optional values and clear a field such as postal prefix only when an explicit null is supplied. no proof recorded yet	validation	api	test services-commerce:modules/configuration/tests/unit/api/blank-tax-zone-values.spec.js#refuses a whitespace-only postal_code_prefix on a replacement 400 naming the field, instead of clearing H2X
`04`must prove Proposed	A rate with no product-type selection covers all types; a selected list limits coverage to those types and cannot exceed one hundred entries. no proof recorded yet	calculation	service, api	test services-commerce:modules/pricing/tests/unit/tax/zone-tax-calculation.spec.js#applies to every product type when it names none, and to the named ones alone otherwise
`05`must prove Proposed	Tax determination selects the most specific matching active zone, preferring postal prefix over region over country and retaining list order for equal specificity. no proof recorded yet	calculation	service	test services-commerce:modules/pricing/tests/unit/tax/zone-tax-calculation.spec.js#scores a prefix over a region over a country alone
`06`must prove Proposed	Line tax sums separately calculated rates, each rounded to a whole minor currency unit with exact halves moving away from zero. origin: COMM-M1 D5 (docs/milestones/COMM-M1-set-up-what-you-sell.md) no proof recorded yet	calculation	service	test services-commerce:modules/pricing/tests/unit/tax/zone-tax-calculation.spec.js#sums every applicable rate per line, each rounded on its own, and names each component
`07`must prove Proposed	Potentially taxable checkout lines require a tax address; an address-free display quote instead reports zero tax and a warning. no proof recorded yet	policy	service	test services-commerce:modules/pricing/tests/unit/tax/zone-table-tax.spec.js#refuses a line a zone’s rate for every product type could tax, naming the line and its product
`08` Proposed	Commerce uses workspace tax zones unless configured to delegate tax to Accounting, and rejects quotes configured with an unknown provider.	policy	service	test services-commerce:modules/pricing/tests/unit/tax/commerce-tax-port.spec.js#is zone-table when the variable is unset or blank
`09` Proposed	Replacing a tax zone replaces its rates at the read version, and removing the zone removes its rates.	invariant	service, database	test services-commerce:modules/configuration/tests/e2e/tax-zones.e2e.spec.js#deletes a zone with its rates, after which it reads 404; deleting it again is 404
`10`must prove Proposed	Tax-zone inspection requires read permission, while creation, replacement and removal require administrator write permissions. no proof recorded yet	permission	api	test services-commerce:modules/configuration/tests/e2e/configuration-security.e2e.spec.js#lists and reads the tax zones

Scenarios

Id	Given	When	Then	Provenance
`01`	Canada and a more specific Quebec H2X zone are configured	Calculate for a Quebec address beginning H2X	The prefix-specific zone supplies the tax rather than the country-only zone	test services-commerce:modules/pricing/tests/unit/tax/zone-tax-calculation.spec.js#matches the most specific zone the address satisfies

Planning

Calculate tax from buyer geography ​

Purpose ​

How It Works ​

Relationships ​