Pyle

Tax & Territory ​

Tax & Territory is the domain that defines which taxes exist, determines when they apply to orders and returns, and supplies the geographic reference data used by tax, shipping, and regional segmentation logic.

This first pass treats the domain as four connected layers:

  • tax definitions and operator-maintained rates
  • derived tax results on commercial records
  • nexus and exemption-aware tax selection
  • shared territorial data used across tax and adjacent domains

Status ​

  • [x] Domain overview written
  • [x] Subdomains reviewed
  • [x] Technical node pages linked
  • [x] End-user concept pages linked
  • [x] Task guides linked

Responsibility ​

This domain is responsible for:

  • storing reusable tax-rate definitions by jurisdiction, country, and state
  • calculating and persisting derived tax lines on orders, returns, invoices, and other taxable records
  • selecting rates from either the database provider or the TaxJar provider
  • supporting customer and order-level custom tax-rate overrides
  • recording nexus records used for tax-exempt customer handling and provider-specific eligibility
  • exposing shared country, state, geo-region, and sale-region data to other domains

Subdomains ​

  • Tax Definitions And Operator Setup
    • TaxRate
    • admin Settings > Taxes
    • tax provider configuration
  • Derived Tax Results
    • TaxLine
    • order tax lines
    • order return tax lines
  • Nexus And Exemption Routing
    • Nexus
    • customer-level exemption sync
    • order and customer custom tax-rate overrides
  • Shared Territory Model
    • GeoRegion
    • SaleRegion
    • Country
    • State

Classification Decisions ​

Standalone technical pages ​

Standalone end-user pages ​

Standalone task guides ​

Folded into parent pages for now ​

  • SaleRegion
    • folded into Geo Region and Regions because the shared package exposes sale regions mainly as supporting segmentation data rather than a first-pass workflow owner
  • Country
    • folded into Tax Rate and Regions because country data is user-visible reference data used by address entry, tax setup, and shipping flows
  • State
    • folded into Tax Rate, Nexus, and Regions because state selection is central to tax setup, address entry, and eligibility checks but not a standalone authored business concept
  • OrderTaxRateItemCode
    • folded into Tax Rate and Tax Line because it is provider-side caching and mapping infrastructure rather than a direct operator workflow
  • customer and order custom-tax-rate attachments
    • folded into Tax Rate because they are downstream override behaviors attached from customer and order review flows
  • address-to-region syncing
    • folded into Geo Region because it is an automation detail, not a standalone user-facing capability

Explicitly not getting standalone end-user concept pages in this pass ​

  • Nexus
  • Tax Line

Nexus is important technically, but the inspected shared package exposes it primarily through admin API and tax-provider behavior rather than a polished shared operator destination. TaxLine is a derived financial result, not something a user authors directly.

Evidence Highlights ​

Framework ownership ​

  • packages/framework/src/Models/TaxRate.php
  • packages/framework/src/Models/TaxLine.php
  • packages/framework/src/Models/Nexus.php
  • packages/framework/src/Models/GeoRegion.php
  • packages/framework/src/Models/SaleRegion.php
  • packages/framework/src/Models/Country.php
  • packages/framework/src/Models/State.php

Admin and operations surfaces ​

  • packages/admin/src/Livewire/Admin/Settings/Taxes
  • packages/framework/src/Http/Controllers/Api/Admin/TaxRatesController.php
  • packages/framework/src/Http/Controllers/Api/Admin/TaxLinesController.php
  • packages/framework/src/Http/Controllers/Api/Admin/OrderTaxLinesController.php
  • packages/framework/src/Http/Controllers/Api/Admin/OrderReturnTaxLinesController.php
  • packages/framework/src/Http/Controllers/Api/Admin/GeoRegionsController.php
  • packages/framework/src/Actions/Nexus/Requests/Index.php
  • packages/framework/routes/admin.php

Storefront and shared read surfaces ​

  • packages/framework/src/Http/Controllers/Api/Storefront/OrderTaxLinesController.php
  • packages/framework/src/Http/Controllers/Api/World/StatesController.php

Core behavior and automation ​

  • packages/framework/src/Actions/TaxRate/GetOrderTaxRates.php
  • packages/framework/src/Actions/TaxRate/Provider/Database/GetOrderTaxRates.php
  • packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php
  • packages/framework/src/Actions/TaxJar/GetTaxRates.php
  • packages/framework/src/Models/Traits/Taxable.php
  • packages/framework/src/Observers/NexusObserver.php
  • packages/framework/src/Actions/GeoRegion/SyncAddresses.php
  • packages/framework/src/Actions/GeoRegion/SyncShippingPostalCodes.php
  • Tax Rate is the operator-authored tax definition. Tax Line is the calculated money result attached to a taxable record.
  • Nexus here is not just company nexus. The shared model can point to a customer or address and is also used for wholesale-exemption behavior with TaxJar.
  • Geo Region and Sale Region are not the same thing. Geo regions hold geographic shapes and postal-code matching logic; sale regions are higher-level groupings built from geo regions.
  • Country and State are shared reference data used by this domain, not tax-only concepts.
  • The inspected shared package clearly exposes Tax Rates in admin UI. Most other territory behavior is experienced through address forms, location setup, and order review rather than through a dedicated packaged region workspace.

Priority Technical Pages ​

Priority End-User Pages ​

Priority Task Guides ​