Shipments

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.

erDiagram
    Order ||--o{ Shipment : "has many"
    Shipment ||--o{ ShippingRate : "has many"
    Shipment ||--o{ InventoryUnit : "has many"
    Shipment }o--|| StockLocation : "ships from"
    Shipment }o--|| ShippingMethod : "selected method"
    ShippingMethod ||--o{ ShippingRate : "has many"
    ShippingMethod }o--o{ Zone : "serves"
    ShippingMethod }o--o{ ShippingCategory : "handles"
    ShippingMethod }o--o{ Store : "available in"
    Product }o--|| ShippingCategory : "belongs to"

    Shipment {
        string number
        string tracking
        string state
        decimal cost
        datetime shipped_at
    }

    ShippingMethod {
        string name
        string tracking_url
        integer position
    }

    ShippingRate {
        decimal cost
        boolean selected
    }

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

Shipment States

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',
})

# Get shipments
curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=shipments' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123'

# Select a shipping rate
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123' \
  -H 'Content-Type: application/json' \
  -d '{ "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:

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.

flowchart TB
    A[Order with 3 items] --> B{Stock check}
    B --> C["Item A & B: NYC Warehouse"]
    B --> D["Item C: LA Warehouse"]
    C --> E["Shipment 1: UPS Ground"]
    D --> F["Shipment 2: FedEx 2Day"]

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.

Examples

Simple Setup

A store selling T-shirts to the US and Europe with 2 carriers:

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:

Related Documentation

• 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)