Reference → Shipping — Reference

Shipping — Reference

The Shipping surface is the fulfilment-cost plane for every SGEN site that sells physical goods. It owns the catalogue of destinations a site will ship to, the methods offered at checkout, the rate calculation that decides what each shipment costs, the package-dimension defaults that feed into carrier quotes, and the carrier credentials that bind the site to a third-party logistics service.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a fulfilment integration. Customer-facing setup walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Shipping lives under the Ecommerce → Shipping module in SG-Admin. The module renders four primary views — the zone list, the per-zone method list, the rate editor, and the carrier credential editor — and exposes write operations for zone create, zone edit, method attach, rate edit, carrier connect, and zone delete.

The module is paired by convention with the Orders surface. Shipping decisions made here are read at checkout by the cart engine, written onto the order record at purchase time, and consulted again by the fulfilment workflow when a label is generated. Engineers reading the SG-Admin source will see the read half (zone resolution, method enumeration, rate quoting) split from the write half (zone CRUD, rate edits, carrier credential storage); the reference below describes the combined surface as it appears to a calling integration.

A second surface — package presets — lives adjacent under the same module. Presets describe the default boxes a fulfilment operator packs into, with weight and dimension defaults. Carrier integrations consume preset data when quoting; the surface is described here because it shares the same write entry points.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Ecommerce → Shipping
URL prefix: /sg-admin/shipping/
View templates: application/views/Admin/Shipping/

The module surface is scoped to fulfilment cost. Tax (covered in the Taxes reference), inventory (Products reference), and order processing (Orders reference) live in adjacent surfaces. This page covers only the destination-rate-method-carrier plane.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Ecommerce → Shipping [+ Add zone] │├──────────────────────────────────────────────────────────────────────┤│ Zone name Regions Methods Status ││ ───────────────── ──────────────────── ───────────── ────────────││ Domestic PH Philippines Flat, Free Active ││ Southeast Asia ID, MY, SG, TH, VN Calculated Active ││ Rest of World [all other] Calculated Active ││ Local Pickup (no region) Pickup Active ││ ││ [⋯ Edit] [⋯ Methods] [⋯ Rates] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Shipping surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.

List zones

Returns the shipping zones configured for the current site, in display order. Each zone row carries its name, its assigned regions, the count of attached methods, and an active flag. The default sort is the operator-defined display order, used by the checkout engine to resolve a shipping address into a zone — the first matching zone wins.

Create zone

Opens an empty zone form. Required fields: zone name, region list. The region list accepts country codes, country-and-subdivision pairs (for example a state or province), or postal-code ranges. On submit, the surface validates that the region selection does not collide with an earlier zone in the resolution order and persists the new zone.

Edit zone

Loads an existing zone into the same form shape used for create. Submit replaces the stored zone definition. Reordering zones is a separate write — the display-order field carries resolution priority and is changed by drag-reorder in the list view.

Attach method

Adds a shipping method to a zone. Methods are the offerings presented to the buyer at checkout. The surface ships with four method types: flat-rate, free, calculated (carrier-quoted), and local pickup. Each method type opens a different editor — flat-rate prompts for a single price, free prompts for a minimum-order threshold, calculated prompts for a carrier binding, pickup prompts for a pickup-location label.

Edit rate

For flat-rate and free methods, the rate editor is the same form used to attach the method. For calculated methods, the rate editor exposes the markup or discount applied on top of the carrier quote, plus the handling fee added per shipment.

Detach method

Removes a method from a zone. Existing orders that used the method are unaffected — the method definition is retained on the order record. Future checkouts in that zone no longer see the method.

Connect carrier

Opens the carrier credential form. Each carrier integration prompts for the credential set the carrier requires — API key, account number, region. On submit, the surface stores the credentials encrypted at rest and verifies them by making a single test quote against the carrier. A failed verification returns a structured error naming the credential field that the carrier rejected.

Edit package preset

Lists the package presets configured for the site, with default weight, length, width, height, and a label. Submit replaces the preset definition. Presets are referenced by Product records and by the fulfilment workflow when computing dimensional weight.

Delete zone

Removes a zone and all attached methods. The surface prompts for confirmation, lists the orders that previously used the zone (for audit), and on confirm removes the zone. Existing orders retain their shipping-method snapshot and are unaffected.

Data model

A shipping zone carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`id`	integer	Primary key. Stable across edits.
`name`	string	Display name shown to operators. Not shown to buyers.
`regions`	array	Country codes, subdivision pairs, or postal-code ranges.
`display_order`	integer	Resolution priority at checkout — lower wins.
`status`	enum	`active` or `inactive`. Inactive zones are skipped at checkout.
`created_at`	timestamp	Set on create, immutable.
`updated_at`	timestamp	Touched on any edit.

A shipping method (attached to a zone) carries:

Field	Type	Notes
`id`	integer	Primary key.
`zone_id`	integer	Foreign key to the parent zone.
`type`	enum	`flat` · `free` · `calculated` · `pickup`.
`title`	string	Label shown to the buyer at checkout.
`cost`	decimal	Flat methods only. Free methods set this to zero.
`min_order`	decimal	Free methods only. Order subtotal threshold.
`carrier_id`	integer	Calculated methods only. Foreign key to the carrier record.
`markup`	decimal	Calculated methods only. Added to the carrier quote.
`handling_fee`	decimal	Added per shipment, all method types.
`status`	enum	`active` or `inactive`.

A carrier credential record carries:

Field	Type	Notes
`id`	integer	Primary key.
`carrier_slug`	string	Identifier for the integration — for example, `fedex`, `dhl`, `usps`.
`credentials`	encrypted blob	Carrier-specific. Stored encrypted at rest, never returned in reads.
`verified_at`	timestamp	Last successful test quote.
`verified_status`	enum	`ok` or `failed`.

A package preset carries:

Field	Type	Notes
`id`	integer	Primary key.
`label`	string	Operator-facing name.
`weight`	decimal	Empty-box weight, in the site's configured weight unit.
`length`	decimal	In the site's configured length unit.
`width`	decimal	Same.
`height`	decimal	Same.

SHIPPING ZONE├── id integer primary key├── name string operator-facing label├── regions array country codes / subdivisions / postal ranges├── display_order integer resolution priority at checkout└── status enum active | inactive↓ has manySHIPPING METHOD├── type enum flat | free | calculated | pickup├── title string buyer-facing label├── cost / markup decimal per method type├── carrier_id integer calculated methods only└── handling_fee decimal added per shipment↓ references (calculated only)CARRIER CREDENTIAL├── carrier_slug string fedex | dhl | usps | local├── credentials blob encrypted at rest└── verified_at timestamp

Zone resolution. At checkout the cart engine walks the zone list in display_order ascending, takes the first zone whose region list contains the destination, and presents that zone's active methods. If no zone matches, checkout returns a structured rejection naming the destination region.

Snapshot on order. When a buyer selects a method and the order is placed, the chosen method's title, cost, markup, and handling_fee are snapshotted onto the order record. Subsequent edits to the method definition do not retroactively change the order.

Permissions

Access to the Shipping surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Shipping surface.

Layer 2 — per-action capability. Within SG-Admin, each Shipping action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:

Capability	Administrator	Editor	Viewer
List zones	✔	✔	✔
Create zone	✔	—	—
Edit zone	✔	—	—
Reorder zones	✔	—	—
Attach method	✔	✔	—
Edit rate	✔	✔	—
Detach method	✔	—	—
Connect carrier	✔	—	—
Edit package preset	✔	✔	—
Delete zone	✔	—	—

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Carrier credential isolation. Carrier credentials are stored encrypted and are never returned in read responses. The credential editor accepts new values but does not display the existing value — only a masked indicator and a "rotate" action. The audit log records that a rotation happened, not the value rotated to.

Audit. Every write — zone create, zone edit, method attach, rate edit, carrier connect, carrier rotate, zone delete — emits an Activity Log entry. The log records the acting operator, the target record, and the change shape (field-level diff for edits). Activity Log retention is governed by the site's general settings.

REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Carrier credential │ read returns mask, never plaintext│ isolation │ write rotates, audit records event└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry

Related references

Orders — Reference. Order records snapshot the chosen shipping method's title, cost, markup, and handling fee at purchase time. The fulfilment workflow on the order surface consumes that snapshot.
Products — Reference. Product records carry weight and dimension fields that feed into calculated-rate quotes. Products may reference a package preset directly.
Taxes — Reference. Tax is computed alongside shipping at checkout. Some jurisdictions tax the shipping line; that toggle lives in the Taxes surface.
Settings — Reference. Owns the site's weight unit, length unit, currency, and the role capability map that gates this surface.
Customer Accounts — Reference. Saved buyer addresses feed the destination resolver. Address validation rules live in the customer-accounts surface.
Payments — Reference. The chosen shipping method's total is added to the cart total before the payment processor is called.

For the corresponding customer-facing walkthrough — adding a zone, setting up a flat rate, connecting a carrier — see the Shipping section of the customer docs at /docs/shipping.

On this page

Guides

Reference

Changelog

Roadmap