Shipping Zone

First-Pass Node Dossier

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

What It Is

ShippingZone is the geographic coverage record that groups or derives eligible postal codes for shipping services.

Parent hierarchy:

• Fulfillment & Shipping
• Shipping Configuration And Eligibility
• Shipping Zone

Primary implementation paths:

• packages/framework/src/Models/ShippingZone.php
• packages/framework/src/Actions/ShippingZone
• packages/framework/src/Http/Controllers/Api/Admin/ShippingZonesController.php
• packages/framework/src/Actions/Import/Shipping/ShippingZonesImport.php

What Users Can Do With It

Operators can:

• list, create, update, and delete shipping zones through the admin API
• define the country and optional state a zone belongs to
• define radius-based coverage from a postal-code origin
• maintain excluded ZIPs
• attach or detach postal codes from a zone
• export and import zones through the shipping Excel templates

Indirectly, zones are used to:

• constrain shipping-service availability by geography
• provide bulk postal-code coverage instead of managing individual ZIPs one by one

Where It Is Managed

Channel	Role	Notes
Admin API	Direct	Main CRUD and postal-code attach or detach surface
Excel shipping templates	Direct	First-pass packaged bulk workflow
Shipping service configuration	Parent-owned	Services attach zones as eligibility rules
Storefront	Indirect	Shoppers experience the result, not the zone itself

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/ShippingZonesController.php
• packages/admin/src/Livewire/Admin/Tools/Excel/ImportDialog/ShippingZonesImport.php
• packages/framework/src/Actions/Exports/Shipping/Sheets/ShippingZonesSheet.php

Channel-Level Field Coverage

Admin API create and update

Core validated fields are:

• name
• country_id
• optional state_id
• radius_zip_origin
• radius_km
• except_zips

The controller also supports loading:

• country
• state
• shipping postal codes
• shipping postal-code origin

Sources:

• packages/framework/src/Actions/ShippingZone/CreateShippingZone.php
• packages/framework/src/Actions/ShippingZone/UpdateShippingZone.php
• packages/framework/src/Http/Controllers/Api/Admin/ShippingZonesController.php

Excel shipping template

The exported shipping_zones sheet contains:

• zone UUID and name
• radius ZIP origin and radius kilometers
• country and state codes
• shipping-postal-code ID
• excluded ZIPs

The import sheet either resolves country and state from explicit codes or falls back to the radius-origin postal code.

Sources:

• packages/framework/src/Actions/Exports/Shipping/Sheets/ShippingZonesSheet.php
• packages/framework/src/Actions/Import/Shipping/Sheets/ShippingZonesImportSheet.php

Configuration And Data Model

Key model characteristics:

• searchable
• soft-deletable
• country and optional state scoped
• can sync derived postal codes asynchronously or synchronously

Important relationships:

• country()
• state()
• shippingServices()
• shippingPostalCode()
• shippingPostalCodes()
• shippingPostalCodeOrigin()

Source:

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

Rules And Downstream Effects

Postal-code syncing

Creating or updating a zone dispatches postal-code synchronization.

That means a zone is not only a label:

• its postal-code membership is recalculated from the defined geography
• services attached to the zone inherit that new geography

Sources:

• packages/framework/src/Actions/ShippingZone/CreateShippingZone.php
• packages/framework/src/Actions/ShippingZone/UpdateShippingZone.php
• packages/framework/src/Models/ShippingZone.php

Service eligibility

Shipping services can attach zones in included or excluded mode. Those zone links then participate in service-availability filtering.

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/ShippingServicesController.php
• packages/framework/src/Models/ShippingService.php
• packages/framework/src/Models/Traits/ShippingService/IsAvailableForShippingPostalCode.php

Integrations And Automation

Shipping template workflow

Zones are a first-class part of the shipping report and shipping-zone import flow.

Sources:

• packages/admin/src/Livewire/Admin/Tools/Excel/ExportDialog/ShippingExport.php
• packages/admin/src/Livewire/Admin/Tools/Excel/ImportDialog/ShippingZonesImport.php

Postal-code substrate

Zones depend on ShippingPostalCode records for ZIP validation, country or state matching, and geographic linking.

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/ShippingPostalCodesController.php
• packages/framework/src/Actions/ShippingPostalCode/FindAndLinkShippingZones.php

Where It Appears To End Users

ShippingZone is not directly shopper facing.

Its practical effect is indirect:

• shipping services become available or unavailable for a destination
• shipping estimates change by geography
• pickup and delivery options vary by region

Current Documentation Takeaways

1. ShippingZone is the reusable geography layer that feeds shipping-service eligibility.
2. The base repo manages it mainly through admin API and Excel, not through a dedicated packaged Livewire settings page.
3. Radius rules, state or country scope, and excluded ZIPs all matter because they drive postal-code sync.

Open Questions

• This pass did not inspect every lower-level postal-code sync pipe, only the main model, actions, and controllers that make the zone behavior visible.