Nexus

First-Pass Node Dossier

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

What It Is

Nexus is the tax-eligibility bridge record that links a state to either the business itself or to a specific customer or address so the tax engine can decide whether TaxJar should calculate tax normally or treat the customer as tax-exempt in that jurisdiction.

Parent hierarchy:

• Tax & Territory
• Tax Definitions
• Nexus

Primary implementation paths:

• packages/framework/src/Models/Nexus.php
• packages/framework/src/Actions/Nexus
• packages/framework/src/Observers/NexusObserver.php
• packages/framework/routes/admin.php
• packages/framework/src/Actions/TaxJar/CreateOrUpdateTaxExemptCustomer.php

What Users Can Do With It

Direct capabilities

Staff users can:

• list nexus records through the admin API
• create nexus records through the staff-only API
• update nexus records through the staff-only API

Indirect capabilities

Other workflows use Nexus to:

• sync tax-exempt customers into TaxJar
• determine whether a shipping state has company nexus
• influence whether order tax calculations proceed in the TaxJar provider

Things users cannot do directly

The inspected shared package does not expose a packaged admin Livewire management screen for Nexus.

Where It Is Managed

Channel	Role	Notes
Admin nexuses API	Direct	Staff-only list/create/update surface
Nexus observer	Indirect	Dispatches TaxJar tax-exempt customer sync
TaxJar order tax provider	Indirect upstream input	Reads nexus state eligibility before tax lookup

Sources:

• packages/framework/src/Actions/Nexus/Requests/Index.php
• packages/framework/src/Actions/Nexus/Requests/Store.php
• packages/framework/src/Actions/Nexus/Requests/Update.php
• packages/framework/routes/admin.php
• packages/framework/src/Observers/NexusObserver.php

Channel-Level Field Coverage

Admin API create and update flow

The Nexus write path validates and persists:

• state_id
• region
• address_id
• customer_id

The index endpoint can include:

• customer
• state
• address

The model also persists:

• region_code
• timestamps
• soft-delete state

Sources:

• packages/framework/src/Actions/Nexus/CreateNexus.php
• packages/framework/src/Actions/Nexus/UpdateNexus.php
• packages/framework/src/Actions/Nexus/Requests/Index.php
• packages/framework/src/Models/Nexus.php
• packages/framework/database/migrations/2023_06_19_121727_create_nexuses_table.php

Configuration And Data Model

Key model characteristics:

• plain Eloquent model
• state-linked
• optional customer link
• optional address link

Important relationships:

• customer()
• state()
• address()

Source:

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

Relationships

Nexus directly connects:

• a company tax state
• a customer
• a shipping address

Practical dependents:

• TaxJar tax-exempt customer sync
• state-level nexus checks during order tax lookup

Rules And Downstream Effects

TaxJar exemption sync

When the tax provider is set to taxjar, creating or updating a nexus record dispatches CreateOrUpdateTaxExemptCustomer.

TaxJar eligibility check

The TaxJar provider checks the shipping state for company nexus before it calculates order tax rates. In the shared model, State::hasCompanyNexus means there is a nexus row for that state with no customer_id.

Sources:

• packages/framework/src/Observers/NexusObserver.php
• packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php
• packages/framework/src/Actions/TaxJar/CreateOrUpdateTaxExemptCustomer.php

Integrations And Automation

TaxJar customer sync

Nexus is the bridge that keeps TaxJar customer exemption state aligned with the internal nexus records.

Sources:

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

Where It Appears To End Users

Nexus is not a shopper-facing concept.

In the inspected package it is primarily a staff API record that affects tax eligibility behind the scenes.

Current Documentation Takeaways

1. Nexus is the state-level tax bridge record, not a general territory concept.
2. Its main business effect is TaxJar exemption sync and TaxJar eligibility gating.
3. The shared package does not ship a packaged admin UI for nexus management in this pass.

Open Questions

• This pass did not find a packaged admin Livewire nexus screen or a dedicated resource serializer.

Sources:

• packages/framework/src/Models/Nexus.php
• packages/framework/src/Actions/Nexus/CreateNexus.php
• packages/framework/src/Actions/Nexus/UpdateNexus.php
• packages/framework/src/Actions/Nexus/Requests/Index.php
• packages/framework/src/Observers/NexusObserver.php
• packages/framework/src/Actions/TaxRate/Provider/TaxJar/GetOrderTaxRates.php