Pyle

Tax Line ​

First-Pass Node Dossier

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

What It Is ​

TaxLine is the derived tax-breakdown record that stores the calculated tax amount for a taxable model such as an order item, shipping line, discount line, invoice line, or return line.

Parent hierarchy:

  • Tax & Territory
  • Tax Calculations And Tax Output
  • Tax Line

Primary implementation paths:

  • packages/framework/src/Models/TaxLine.php
  • packages/framework/src/Models/Traits/Taxable.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

What Users Can Do With It ​

Direct capabilities ​

Operators can:

  • inspect tax-line rows attached to orders and returns through admin API resources
  • view the calculated amount in a presentable money format
  • use the tax-line output as part of order review and refund review workflows

Indirect capabilities ​

Other workflows use TaxLine to:

  • drive invoice, fulfillment, and return tax totals
  • feed Stripe checkout tax-rate mapping
  • export tax data into the ERP bridge

Things users cannot do directly ​

The shared package does not expose TaxLine as a manually edited packaged record. It is recalculated from taxable sources.

Where It Is Managed ​

ChannelRoleNotes
Admin order tax-lines APIDirect read-onlyLists tax lines for an order
Admin order-return tax-lines APIDirect read-onlyLists tax lines for a return
Storefront order tax-lines APIDirect read-onlyAuthenticated customer can inspect their order tax lines
Tax calculation traitIndirect upstream inputCreates, updates, and deletes derived tax lines

Sources:

  • 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/Storefront/OrderTaxLinesController.php

Creation Model ​

TaxLine is created and maintained by tax-calculation code, not by a direct packaged create form.

The triggering path is:

  1. a taxable model asks for tax rates
  2. Taxable::calculateTaxesFromModel() builds derived tax-line objects
  3. Taxable::saveTaxLines() updates existing rows, inserts new ones, and deletes stale rows

This same pattern is used by order, invoice, shipping, discount, return, and fulfillment-related tax calculations.

Sources:

  • packages/framework/src/Models/Traits/Taxable.php
  • packages/framework/src/Actions/Order/CalculateTaxes.php
  • packages/framework/src/Actions/OrderItem/CalculateTaxes.php
  • packages/framework/src/Actions/OrderShippingLine/CalculateTaxes.php
  • packages/framework/src/Actions/Invoice/CalculateTaxes.php
  • packages/framework/src/Actions/OrderReturn/CalculateTaxes.php

Configuration And Data Model ​

Key model characteristics:

  • soft-deletable
  • morphs to any taxable parent through taxable()
  • belongs to TaxRate
  • maps to the ERP bridge DTO

Important fields:

  • taxable_id
  • taxable_type
  • tax_rate_id
  • title
  • description
  • jurisdiction
  • percentage
  • amount
  • taxable_amount
  • rate
  • registration_number
  • currency

Useful accessors:

  • amount_decimal
  • amount_presentable

Source:

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

Relationships ​

TaxLine directly connects to:

  • the taxable parent record
  • the tax rate that produced the calculation
  • ERP bridge tax-line export payloads

Practical owners:

  • orders
  • order items
  • shipping lines
  • discount lines
  • invoice lines
  • return lines

Rules And Downstream Effects ​

Inclusive versus exclusive math ​

The tax calculation trait applies inclusive rates to the running total and exclusive rates to the subtotal. That means the order of tax rates can affect the computed amount.

Stale-line cleanup ​

When recalculated tax lines no longer match the current tax-rate set, stale rows are force-deleted.

Provider-driven null cases ​

If the provider cannot determine tax rates for a taxable object, no tax lines are generated.

Parent-tax regrouping ​

Order, return, and invoice tax totals are rebuilt by deleting existing parent tax lines, regrouping child tax lines by tax_rate_id, and recreating aggregate parent lines from that grouped output.

Sources:

  • packages/framework/src/Models/Traits/Taxable.php
  • packages/framework/src/Actions/TaxRate/Provider/Database/GetOrderTaxRates.php
  • packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php
  • packages/framework/src/Actions/Order/CalculateTaxes.php
  • packages/framework/src/Actions/OrderReturn/CalculateTaxes.php
  • packages/framework/src/Actions/Invoice/CalculateTaxes.php

Integrations And Automation ​

ERP bridge export ​

TaxLine implements the bridge contract and converts itself into an ERP DTO.

Sources:

  • packages/framework/src/Models/TaxLine.php
  • packages/framework/src/Actions/ErpBridge/TaxLine/ToDTO.php

Checkout and tax-provider flows ​

Tax lines are consumed downstream by Stripe checkout mapping and by provider-backed tax calculations.

Sources:

  • packages/framework/src/Actions/Stripe/CreateStripeCheckout.php
  • packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php

Where It Appears To End Users ​

TaxLine is mostly invisible as a standalone concept.

It appears as a breakdown inside order, invoice, shipping, and return details. Operators read it; they do not author it directly.

Current Documentation Takeaways ​

  1. TaxLine is calculated output, not a manually managed tax setting.
  2. The same record powers order, invoice, and return tax visibility, while parent totals are rebuilt from grouped child tax lines.
  3. ERP export is the main technical integration surface beyond admin and storefront read-only inspection.

Open Questions ​

  • This pass did not find a packaged create/update UI for tax lines, which is consistent with the derived model behavior.

Sources:

  • packages/framework/src/Models/TaxLine.php
  • packages/framework/src/Models/Traits/Taxable.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/database/migrations/2022_11_26_132353_create_tax_lines_table.php
  • packages/framework/database/migrations/2026_01_02_000000_add_taxable_amount_to_tax_lines_table.php
  • packages/framework/src/Http/Controllers/Api/Storefront/OrderTaxLinesController.php
  • packages/framework/src/Actions/ErpBridge/TaxLine/ToDTO.php