Shipping Zone

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/Actions/ShippingZone/ShippingPostalCode
• 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 packaged admin settings UI
• define the country and optional state a zone belongs to
• define radius-based coverage from a postal-code origin
• maintain excluded ZIPs inline from the zone detail page
• attach or detach individual postal codes from a zone through the included-postal-codes table
• preview the radius coverage on a map when a Google Maps API key is configured
• 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 settings UI	Direct	Packaged index, create dialog, and detail/edit pages
Admin API	Direct	CRUD and postal-code attach or detach surface
Excel shipping templates	Direct	Packaged bulk workflow via the shipping workbook
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/framework/src/Actions/Exports/Shipping/Sheets/ShippingZonesSheet.php

Channel-Level Field Coverage

Admin settings UI — create dialog

The create dialog collects:

• name (required)
• country_id (required — drives the state dropdown)
• optional state_id (filtered to the selected country)
• optional radius_zip_origin
• optional radius_km
• except_zips — added by searching and selecting individual postal codes

After a successful create the user is redirected to the new zone's detail page.

Sources:

Admin settings UI — detail / edit page

The edit page exposes the same fields as the create dialog and adds:

• inline add and remove for excluded ZIPs (persisted immediately, without a full save)
• a paginated, searchable included-postal-codes table driven by PostalCodesTable
• individual postal-code attach (AddShippingPostalCode) and detach (RemoveShippingPostalCode) actions
• a Google Maps radius preview — activated when both a radius origin and radius km are present
• a technical-details panel showing ID, UUID, timestamps, country, and state
• a delete confirmation flow that soft-deletes the zone and redirects to the index

Dispatch events:

• shipping-zone-updated — emitted after a successful save; PostalCodesTable listens and refreshes

Sources:

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

Postal-code attach and detach actions

Two new framework actions handle individual postal-code membership:

• AddShippingPostalCode — syncs the postal code onto the zone's relationship without detaching others, then touches the zone's updated_at
• RemoveShippingPostalCode — detaches the postal code from the zone's relationship, then touches updated_at

Both are called from PostalCodesTable and surface confirmations or errors through Flux toast messages.

Sources:

• packages/framework/src/Actions/ShippingZone/ShippingPostalCode/AddShippingPostalCode.php
• packages/framework/src/Actions/ShippingZone/ShippingPostalCode/RemoveShippingPostalCode.php

Shipping template workflow

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

Sources:

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 admin package now provides a fully packaged settings UI — an index page, a create dialog, and a detail/edit page — in addition to the API and Excel channels.
3. Excluded ZIPs are persisted immediately from the edit page without requiring a full save.
4. Individual postal-code attach and detach are available inline via the PostalCodesTable component and two dedicated framework actions.
5. A Google Maps radius preview is available on the detail page when ADMIN_GOOGLE_MAPS_API_KEY is configured.
6. Radius rules, state or country scope, and excluded ZIPs all matter because they drive postal-code sync.

Open Questions

• The map preview integration relies on ADMIN_GOOGLE_MAPS_API_KEY. Projects that omit this key still see the "Open in Google Maps" fallback link.