Tax Rate

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

TaxRate is the packaged tax definition record that Pyle uses to describe a percentage-based tax rule for a jurisdiction.

Parent hierarchy:

• Tax & Territory
• Tax Definitions
• Tax Rate

Primary implementation paths:

• packages/framework/src/Models/TaxRate.php
• packages/framework/src/Http/Controllers/Api/Admin/TaxRatesController.php
• packages/admin/src/Livewire/Admin/Settings/Taxes
• packages/framework/src/Actions/TaxRate

What Users Can Do With It

Direct capabilities

Operators can:

• list, create, show, update, and delete tax rates through the admin API
• manage the packaged tax settings surface in the admin Livewire module
• choose whether a tax rate is inclusive, active, or custom
• attach a tax rate to a country, state, or jurisdiction string

Indirect capabilities

Other workflows use TaxRate to:

• calculate tax lines on orders, invoices, returns, discounts, shipping lines, and fulfillment-related documents
• attach customer-specific or order-specific custom tax rates
• mirror tax rate identifiers into Stripe tax-rate objects
• drive TaxJar-backed tax lookups when the provider is set to taxjar
• create or reuse persisted tax-rate rows from TaxJar responses when matching records do not already exist

Things users cannot do directly

The shared package exposes tax-rate management through the admin API and Livewire settings page, not through a shopper-facing surface.

Where It Is Managed

Channel	Role	Notes
Admin tax settings Livewire	Direct	Main packaged settings UI
Admin tax-rates API	Direct	CRUD surface with search, filters, and includes
Order and customer custom-tax-rate actions	Indirect	Adds or removes tax rates on business records
Tax calculation providers	Indirect upstream input	Database and TaxJar providers consume the record
Storefront checkout and order tax APIs	Indirect	Taxes are surfaced as order tax lines, not edited there

Sources:

• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable.php
• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable/EditDialog.php
• packages/framework/src/Http/Controllers/Api/Admin/TaxRatesController.php
• packages/framework/src/Actions/TaxRate/Requests/Admin/Index.php

Channel-Level Field Coverage

Packaged admin create and update flow

The admin settings form and API expose:

• name
• description
• percentage
• inclusive
• custom
• active
• country_id
• state_id
• registration_number

The controller and model also persist or accept:

• jurisdiction
• country_code
• province_code
• acomba_tax_number
• external_id
• uuid

Sources:

• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable/EditDialog.php
• packages/framework/src/Http/Controllers/Api/Admin/TaxRatesController.php
• packages/framework/src/Models/TaxRate.php
• packages/framework/database/migrations/2022_11_26_132155_create_tax_rates_table.php

Configuration And Data Model

Key model characteristics:

• translatable name and description
• soft-deletable
• UUID-based
• searchable through the database engine
• activity-logged

Important relationships:

• country()
• state()

Relevant support fields:

• country_code
• province_code
• custom
• active
• inclusive

Source:

• packages/framework/src/Models/TaxRate.php

Relationships

TaxRate directly connects to:

• country and state lookup data
• customer custom-tax-rate assignments
• order custom-tax-rate assignments
• tax lines created on taxable records

Practical dependents:

• TaxLine
• OrderTaxRateItemCode
• Stripe tax-rate mirroring
• TaxJar order tax calculation

Rules And Downstream Effects

Database-provider lookup

When the database provider is active, order tax rates are selected by:

• shipping country code
• shipping province code
• active tax rates only
• non-custom tax rates unless the order has custom tax rates

Inclusive tax rates are ordered after the lookup and then applied by the tax calculation trait.

Sources:

• packages/framework/src/Actions/TaxRate/Provider/Database/GetOrderTaxRates.php
• packages/framework/src/Models/Traits/Taxable.php

TaxJar-provider lookup

When the TaxJar provider is active, tax calculation depends on:

• the order having a shipping address and subtotal greater than zero
• the shipping state having a company nexus
• cached OrderTaxRateItemCode rows for the same shipping address

If the cached rows do not match the shipping address, the existing item-code rows are cleared and TaxJar is recalculated.

Sources:

• packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php
• packages/framework/src/Actions/TaxJar/GetTaxRates.php
• packages/framework/src/Models/OrderTaxRateItemCode.php
• packages/framework/src/Models/State.php

TaxJar-generated tax rates

The TaxJar path does not only read existing tax rates. It can synthesize or reuse persisted TaxRate rows through FirstOrCreateTaxRate, keyed by country, state, percentage, and jurisdiction.

Sources:

• packages/framework/src/Actions/TaxJar/GetTaxRates.php
• packages/framework/src/Actions/TaxRate/FirstOrCreateTaxRate.php

Custom-tax-rate attachers

Customers and orders can have custom tax rates attached through dedicated admin actions. Those custom assignments are then preferred by the database provider.

This shared-package behavior is asymmetric: the database provider reads order-level custom tax-rate attachments, while the TaxJar provider does not branch on them directly.

Sources:

• packages/framework/src/Actions/Customer/AddCustomTaxRate.php
• packages/framework/src/Actions/Customer/RemoveCustomTaxRate.php
• packages/framework/src/Actions/Order/AddCustomTaxRate.php
• packages/framework/src/Actions/Order/RemoveCustomTaxRate.php
• packages/framework/src/Actions/TaxRate/Provider/Database/GetOrderTaxRates.php
• packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php

Integrations And Automation

Stripe tax-rate mirroring

The shared package can create or reuse Stripe tax-rate objects from a TaxRate record.

Sources:

• packages/framework/src/Actions/Stripe/GetStripeTaxRate.php
• packages/framework/src/Actions/Stripe/CreateStripeCheckout.php

TaxJar automation

When the tax provider is set to taxjar, the shared package schedules tax-transaction creation daily and updates tax-exempt customer state through nexus changes.

Sources:

• packages/framework/src/FrameworkServiceProvider.php
• packages/framework/src/Actions/TaxJar/CreateOrUpdateTaxExemptCustomer.php
• packages/framework/src/Observers/NexusObserver.php

Where It Appears To End Users

TaxRate is mostly an operator concept.

Operators see it in the tax settings area and through order/customer custom-tax-rate actions. Shoppers do not manage tax rates directly; they only experience the effect in checkout totals and order tax lines.

Current Documentation Takeaways

1. TaxRate is the main packaged tax-definition record and the source of truth for tax calculations.
2. The same record feeds both the database provider and the TaxJar flow, but the provider rules are different and TaxJar can create missing records on demand.
3. Country and State are support lookups, not standalone tax concepts in this pass.

Open Questions

• This pass did not inspect any host-app tax-rate management screen beyond the shared admin settings module and API.

Sources:

• packages/framework/src/Models/TaxRate.php
• packages/framework/src/Http/Controllers/Api/Admin/TaxRatesController.php
• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable.php
• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Taxes/DataTable/EditDialog.php
• packages/framework/src/Actions/TaxRate/Provider/Database/GetOrderTaxRates.php
• packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php
• packages/framework/src/Actions/TaxRate/FirstOrCreateTaxRate.php
• packages/framework/src/Actions/Stripe/GetStripeTaxRate.php
• packages/framework/src/Observers/NexusObserver.php