Skip to main content

​
Overview

A shipment represents a package being sent to a customer from a Stock Location. Each order can have one or more shipments — Spree automatically splits orders into multiple shipments when items need to ship from different locations or require different shipping methods. Key relationships:
  • Shipment tracks delivery of items from a Stock Location
  • Shipping Method defines the carrier/service (UPS, FedEx, etc.)
  • Shipping Rate represents the calculated cost for a method
  • Zone defines geographic regions for shipping availability
  • Shipping Category groups products with similar shipping requirements

​
Shipment Attributes

AttributeDescriptionExample
numberUnique shipment identifierH12345678901
trackingCarrier tracking number1Z999AA10123456784
stateCurrent shipment stateshipped
costShipping cost9.99
shipped_atWhen the shipment was shipped2025-07-21T14:36:00Z
stock_locationWhere items ship fromWarehouse NYC
selected_shipping_rateThe rate chosen by the customer{ cost: 9.99, name: "UPS Ground" }

​
Shipment States

1

pending

The shipment has backordered inventory or the order is not yet paid.
2

ready

All items are in stock and the order is paid. Ready to ship.
3

shipped

The shipment is on its way to the customer.
4

canceled

The shipment was canceled. All items are restocked.

​
Selecting Shipping Rates

During checkout, after the customer provides a shipping address, Spree calculates available shipping rates for each shipment. The customer must select a rate before proceeding. 
// Get shipments with available shipping rates
const order = await client.orders.get(orderId, {
  expand: ['shipments'],
})

// Each shipment has available shipping rates
order.shipments?.forEach(shipment => {
  console.log(shipment.number)           // "H12345678901"
  console.log(shipment.shipping_rates)   // [{ id: "sr_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
})

// Select a shipping rate
await client.carts.shipments.update(cartId, shipment.id, {
  selected_shipping_rate_id: 'sr_xxx',
})

​
Shipping Methods

Shipping methods represent the carrier services available to customers (e.g., UPS Ground, FedEx Overnight, DHL International). Each shipping method is scoped to:
  • Zones — geographic regions where the method is available
  • Shipping Categories — product groups the method handles
  • Stores — which stores offer this method
Only methods whose zone matches the customer’s shipping address are offered at checkout.

​
Shipping Categories

Shipping categories group products with similar shipping requirements. For example:
  • Light — lightweight items like stickers
  • Regular — standard products
  • Heavy — items over a certain weight
  • Oversized — large items requiring special handling
Each product is assigned a shipping category. Shipping methods can be restricted to handle only certain categories, and the shipping cost calculator uses the category to determine pricing.

​
Calculators

Each shipping method uses a Calculator to determine the cost. Spree includes these built-in calculators:
CalculatorDescription
Flat rate per orderSame cost regardless of items
Flat rate per itemFixed cost per item
Flat percentPercentage of the order total
Flexible rateOne rate for the first item, another for each additional
Price sackTiered pricing based on order total
You can create custom calculators for more complex pricing. See the Calculators guide.

​
Split Shipments

When items in an order ship from different stock locations or have different shipping categories, Spree automatically splits the order into multiple shipments.

​
How Splitting Works

  1. When an order reaches the delivery step, Spree evaluates where each item is in stock
  2. Items are grouped by stock location and shipping category
  3. Each group becomes a separate shipment with its own shipping rates
  4. The customer selects a shipping rate for each shipment independently

​
Weight Splitting

By default, Spree also splits shipments when a package exceeds a weight threshold (default: 150 units). This prevents individual packages from being too heavy.
Split shipment behavior is customizable. See the Customization Quickstart for details on creating custom splitting rules.

​
Examples

​
Simple Setup

A store selling T-shirts to the US and Europe with 2 carriers:
MethodZonePricing
USPS GroundUS5firstitem+5 first item + 2 each additional
FedExEU$10 per item
This requires:
  • 1 shipping category (default)
  • 1 stock location
  • 2 shipping methods with appropriate zones and calculators

​
Advanced Setup

A store shipping from 2 locations (New York, Los Angeles) with 3 carriers and 3 shipping categories:
Category / MethodDHLFedExUSPS
Light$5/item$10 flat$8/item
Regular$5/item$2/item$8/item
Heavy$50/item20+20 + 15/add’l$20/item
  • Orders — Checkout flow and shipping rate selection
  • Inventory — Stock locations and inventory management
  • Calculators — Shipping rate calculators
  • Addresses — Shipping address and zones
  • Events — Subscribe to shipment events (e.g., shipment.shipped)