21 "summary": "Tax Groups, Tax Regions, and Manual Tax Mappings all live under `/billing/v1/...` — not `/ecom/v1/...` like Discount Rules, and not `/stores/v2/...` like Coupons. Guessing the ecom prefix by analogy with sibling commerce-extension entities is the most likely first-try mistake."
26 "summary": "A Tax Group only categorizes products; it carries no tax rate. The rate for a (group, region) pair lives in a separate Manual Tax Mapping record (only meaningful when the region's calculator is the Wix manual calculator, not Avalara). A product joins a group via the product's own `taxGroupId` field on Wix Stores Catalog V3 (Update Product), not via any call in this domain."
27 },
28 {
29 "code": "query-tax-groups-excludes-defaults",
30 "severity": "blocker",
31 "summary": "Every site already has default tax groups (e.g. Products, Shipping and delivery, Services, Cancellation fees) inherited from its installed apps. Query Tax Groups returns ONLY custom groups a site created — it never returns the defaults. Call List Default Tax Groups (GET /billing/v1/tax-groups/default-tax-groups) to see or resolve a default group's id; this is flagged by Wix's own docs as the most common mistake when looking up a group id such as the shipping group."
36 "summary": "A Tax Region requires an appId naming an installed tax calculator, and calculator appIds are installation-scoped. Resolve them with List Tax Calculators immediately before creating a region; never reuse an ID from another site or documentation example. For a manually transcribed rate, select the Wix Manual Tax Calculator by display name rather than hardcoding its installation-specific ID, and do not select Avalara."
41 "summary": "LIVE-VERIFIED (2026-08-12, not stated explicitly in docs): calling Calculate Tax for a line item whose tax group has NO manual tax mapping for the matched region returns exactly zero tax (taxAmount/taxableAmount both \"0\", empty taxBreakdown[]) rather than an error or a fallback rate. This is the correct primitive for representing a genuinely tax-exempt product/category: create one dedicated tax group for it and deliberately create no manual tax mapping for that group in any region, instead of enumerating a 0% mapping per region."
42 },
43 {
44 "code": "iso-codes-not-display-names",
45 "severity": "blocker",
46 "summary": "`country` (ISO 3166-1 alpha-2) and `subdivision` (ISO 3166-2 without the country prefix, e.g. `NY` not `US-NY`) are stored as codes only — no display name is kept anywhere. Storing a display name like `Georgia` instead of `GA` doesn't error; it just silently matches nothing at calculation time. Subdivision-level regions are only accepted for AU, BR, CA, FR, DE, IN, IT, MX, NL, PT, ES, AE, GB, and US; for any other country, omit `subdivision` (or pass `*`) to create a country-level region."
51 "summary": "A Tax Region created without a Manual Tax Mapping is not inert: Wix's own Tax Locations UI lists it immediately with a visible warning icon and \"Add rates to this location to collect tax at checkout\" — merchant-facing, not just an internal API state. A diagnostic create-then-forget-to-delete cycle leaves real warnings on the live site. Always pair a diagnostic createTaxRegion with a matching deleteTaxRegion in the same session, and independently re-verify via the Tax Locations page (or Query Tax Regions) that nothing was left behind — do not rely on the create/delete call sequence in a script having actually run to completion."