Shipping Service

First-Pass Node Dossier

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

What It Is

ShippingService is the priced, constrained shipping record that determines whether a shipment, product offer, or cart item can use a specific delivery or pickup path from a specific inventory location.

Parent hierarchy:

• Fulfillment & Shipping
• Shipping Configuration And Eligibility
• Shipping Service

Primary implementation paths:

• packages/framework/src/Models/ShippingService.php
• packages/framework/src/Actions/ShippingService
• packages/framework/src/Http/Controllers/Api/Admin/ShippingServicesController.php
• packages/framework/src/Actions/Import/Shipping/ShippingServicesImport.php
• packages/framework/src/Http/Controllers/Api/Storefront/ShippingController.php

What Users Can Do With It

Direct capabilities

Operators can:

• list, create, update, and delete shipping services through the admin API
• bulk export and import shipping services through the shipping Excel templates
• attach or remove related zones, postal codes, classes, countries, states, customers, and product-type restrictions through dedicated admin API endpoints
• select an eligible shipping service for an order shipment in the packaged order-shipment block

Indirect capabilities

Other workflows also use ShippingService:

• storefront shipping estimates and available-method lookups
• cart shipment selection
• order shipment and shipping-line recalculation
• pickup-service creation from inventory-location settings
• calendar-rule date validation for shipment pickup or shipping dates

Things users cannot do directly

This pass did not find a standalone packaged Livewire settings page for ShippingService in packages/admin. In the base repo, configuration is primarily API and Excel driven, with packaged UI consumption happening later in order and storefront flows.

Where It Is Managed

Channel	Role	Notes
Admin API	Direct	Main CRUD and attach or detach endpoints
Excel export/import	Direct	First-class shipping template round trip
Order > Shipments block	Parent-owned	Staff select from the already-eligible services for one shipment
Storefront shipping endpoints	Indirect	Shoppers receive filtered services, not raw configuration
Inventory-location pickup automation	Indirect upstream input	Pickup services can be created or refreshed automatically

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/ShippingServicesController.php
• packages/admin/src/Livewire/Admin/Tools/Excel/ExportDialog/ShippingExport.php
• packages/admin/src/Livewire/Admin/Tools/Excel/ImportDialog/ShippingServicesImport.php
• packages/admin/src/Livewire/Admin/Order/Shipments/Block.php
• packages/framework/src/Actions/ProductInventoryLocation/UpdateOrCreatePickupServices.php

Channel-Level Field Coverage

Admin API create and update

The create and update actions validate core fields such as:

• shipping_method_id
• product_inventory_location_id
• price
• price_currency
• delivery_day_min
• delivery_day_max
• order_value_min
• order_value_max
• shipment weight, dimensional-weight, and size ranges
• overprice_per_kg
• overprice_weight_threshold_kg
• free_shipping_amount_threshold
• priority
• price_per_skid
• allow_free_shipping
• except_zips

Sources:

• packages/framework/src/Actions/ShippingService/CreateShippingService.php
• packages/framework/src/Actions/ShippingService/UpdateShippingService.php

Related-restriction endpoints

The admin controller exposes dedicated endpoints for:

• customers
• states
• countries
• shipping postal codes
• shipping zones
• shipping classes
• product types

These are not part of the base create or update payload; they are managed as attached restriction sets.

Source:

• packages/framework/src/Http/Controllers/Api/Admin/ShippingServicesController.php

Excel shipping template

The exported shipping_services sheet includes:

• service UUIDs
• shipping-method and inventory-location UUIDs
• price and pricing modifiers
• country, state, class, zone, and product-type restrictions
• included and excluded customer IDs
• weight and size constraints
• free-shipping and priority flags
• translated disclaimers

The import sheet updates core fields and then separately reconciles related restrictions.

Sources:

• packages/framework/src/Actions/Exports/Shipping/Sheets/ShippingServicesSheet.php
• packages/framework/src/Actions/Import/Shipping/Sheets/ShippingServicesImportSheet.php

Packaged order-shipment UI

The packaged order-shipment block exposes eligible services as selectable cards with:

• shipping method label
• delivery-day range
• presentable price
• service-specific pickup or carrier fields
• optional add-on shipping options

Source:

• packages/admin/resources/views/components/order/shipments/block.blade.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• translatable for disclaimer content
• activity-log aware
• location-bound through product_inventory_location_id
• restriction-aware through many-to-many relations

Important relationships:

• shippingMethod()
• productInventoryLocation()
• shippingZones()
• shippingPostalCodes()
• shippingClasses()
• productTypes()
• states()
• countries()
• customers()
• shippingBoxes()
• shippingOptions()

Operational note:

• a shipping method can have many services, but shopper-facing selection often collapses back to one service per method after eligibility and priority filtering

Source:

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

Rules And Downstream Effects

Availability filtering

GetAvailableShippingServices filters services by:

• customer restrictions
• product-type restrictions
• shipping-postal-code restrictions
• order-shipment, order-item, or product-inventory-item constraints

Then it:

• keeps priority services when they exist within a method group
• calculates final prices through the shipping-price pipeline
• drops zero-price services when allow_free_shipping is false
• adds back non-priority services when a priority service became invalid

Source:

• packages/framework/src/Actions/ShippingService/GetAvailableShippingServices.php

Order and cart side effects

When a shipment changes service:

• the shipment record updates
• order items inherit the selected shipping_service_id
• shipping options can change
• order shipping lines are recalculated
• hold-until date can move with the selected pickup date

Sources:

• packages/framework/src/Actions/OrderShipment/UpdateOrderShipment.php
• packages/framework/src/Actions/Order/CalculateShippingLines.php

Import and configuration caveat

The shipping-service import sheet expects product_types_exclude_codes, while the export sheet labels the excluded column as product_types_codes_excluded.

This is the kind of workbook detail that should be treated carefully during manual Excel editing.

Sources:

• packages/framework/src/Actions/Exports/Shipping/Sheets/ShippingServicesSheet.php
• packages/framework/src/Actions/Import/Shipping/Sheets/ShippingServicesImportSheet.php

Integrations And Automation

Storefront shipping estimates

The storefront uses shipping services in:

• ZIP-based shipping estimates for product offers
• cart-item available shipping-method lookups
• cart shipment payloads

Sources:

• packages/framework/src/Http/Controllers/Api/Storefront/ShippingController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CartShipmentsController.php

Pickup automation

Inventory-location updates can create or refresh pickup services automatically when the location accepts pickup and the project has a warehouse-pickup method configured.

Source:

• packages/framework/src/Actions/ProductInventoryLocation/UpdateOrCreatePickupServices.php

Shipping template workflow

The base repo treats shipping services as a first-class shipping Excel import or export surface.

Sources:

• packages/admin/src/Livewire/Admin/Tools/Excel/ExportDialog/ShippingExport.php
• packages/admin/src/Livewire/Admin/Tools/Excel/ImportDialog/ShippingServicesImport.php
• packages/framework/src/Actions/Exports/Shipping/ShippingTemplatesExport.php

Where It Appears To End Users

ShippingService appears indirectly to shoppers and directly to order operators.

Shoppers experience:

• which shipping methods are available
• the calculated price for each method
• pickup and delivery date choices
• optional shipping add-ons

Operators experience:

• service selection in Order > Shipments
• shipping-line recalculation in order financial details

Current Documentation Takeaways

1. ShippingService is the operational shipping rule and price record, not the shopper-facing method label by itself.
2. In the base repo, direct management is mostly API and Excel based, while packaged UI mainly consumes eligible services later in order workflows.
3. Restrictions, priority, and pricing pipelines all materially change what shoppers and admins can choose.

Open Questions

• The base repo exposes broad admin API coverage, but this pass did not find a standalone packaged Livewire settings screen for shipping-service CRUD.
• Host applications may surface these admin endpoints differently, so downstream projects can have a richer operator UX than the shared package alone.