saleor-shipping

# Saleor Shipping Configuration

## Before writing code

**Fetch live docs**:
1. Web-search `site:docs.saleor.io shipping zones methods configuration` for shipping zone and method setup
2. Web-search `site:docs.saleor.io warehouse allocation shipping` for warehouse-based stock allocation strategies
3. Web-search `site:docs.saleor.io shipping app SHIPPING_LIST_METHODS_FOR_CHECKOUT` for custom shipping App patterns
4. Fetch `https://docs.saleor.io/docs/developer/shipping` and review shipping zone, method, and pricing models
5. Web-search `site:docs.saleor.io click and collect warehouse pickup` for local pickup configuration

## Shipping Zones

A shipping zone groups countries that share the same shipping methods and rates:

| Field | Description |
|-------|-------------|
| `name` | Display name for the zone (e.g., "Domestic", "Europe") |
| `countries` | List of ISO 3166-1 alpha-2 country codes |
| `default` | Whether this is the fallback zone for unmatched countries |
| `channels` | Channels where this zone is available |
| `shippingMethods` | Shipping methods available in this zone |
| `warehouses` | Warehouses assigned to this zone |

### Zone Mutations

| Operation | Mutation | Notes |
|-----------|----------|-------|
| Create zone | `shippingZoneCreate` | Set name, countries, channels |
| Update zone | `shippingZoneUpdate` | Modify countries, channels, warehouses |
| Delete zone | `shippingZoneDelete` | Remove zone and its methods |

Zones can map to specific countries, overlap (customer sees all methods), or use a `default` zone as fallback. Zones are channel-scoped — only matching zones appear at checkout.

## Shipping Methods

Each zone contains one or more shipping methods:

### Method Types

| Type | Pricing Basis | Description |
|------|---------------|-------------|
| Price-based | Order subtotal | Rates determined by the total price of the order |
| Weight-based | Order weight | Rates determined by the total weight of the order |

### Method Configuration

| Field | Description |
|-------|-------------|
| `name` | Display name shown to customers |
| `type` | `PRICE` or `WEIGHT` |
| `minimumOrderPrice` | Minimum order total for this method (price-based) |
| `maximumOrderPrice` | Maximum order total for this method (price-based) |
| `minimumOrderWeight` | Minimum order weight for this method (weight-based) |
| `maximumOrderWeight` | Maximum order weight for this method (weight-based) |
| `channelListings` | Per-channel price and min/max order price |
| `maximumDeliveryDays` | Maximum estimated delivery days |
| `minimumDeliveryDays` | Minimum estimated delivery days |

### Method Mutations

| Operation | Mutation | Notes |
|-----------|----------|-------|
| Create method | `shippingPriceCreate` | Add method to a zone |
| Update method | `shippingPriceUpdate` | Modify method settings |
| Delete method | `shippingPriceDelete` | Remove method from zone |
| Update channel listing | `shippingMethodChannelListingUpdate` | Set per-channel pricing |

### Channel-Specific Pricing

Each shipping method has per-channel pricing:

| Field | Description |
|-------|-------------|
| `price` | Shipping cost in the channel currency |
| `minimumOrderPrice` | Channel-specific minimum order price |
| `maximumOrderPrice` | Channel-specific maximum order price |

## Free Shipping Thresholds

Configure free shipping by setting price ranges on methods:

| Approach | Configuration |
|----------|---------------|
| Free above threshold | Create a price-based method with `minimumOrderPrice` set and `price: 0` |
| Paid below threshold | Create a separate method with `maximumOrderPrice` at the threshold |
| Voucher-based | Use a free shipping voucher (see promotions skill) |

## Excluded Products

Shipping methods can exclude specific products:

| Operation | Mutation | Notes |
|-----------|----------|-------|
| Exclude products | `shippingPriceExcludeProducts` | Products that cannot use this method |
| Remove exclusion | `shippingPriceRemoveProductFromExclude` | Allow previously excluded products |

> Exclusions work at the product level. If any line in the checkout contains an excluded product, the shipping method becomes unavailable.

## Custom Shipping Apps

For dynamic shipping rates (e.g., real-time carrier rates), implement a shipping App:

### Sync Webhook: SHIPPING_LIST_METHODS_FOR_CHECKOUT

| Aspect | Description |
|--------|-------------|
| Trigger | Saleor calls the App when a checkout needs shipping methods |
| Input | Checkout data including lines, shipping address, channel |
| Output | List of available shipping methods with prices and delivery estimates |
| Use case | Real-time carrier API integration (UPS, FedEx, DHL, etc.) |

### App Response Format

The shipping App returns an array of methods:

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique method identifier |
| `name` | Yes | Display name for the method |
| `amount` | Yes | Shipping cost |
| `currency` | Yes | Currency code |
| `maximumDeliveryDays` | No | Maximum delivery estimate |
| `minimumDeliveryDays` | No | Minimum delivery estimate |

## Warehouse-Based Allocation

Saleor supports multi-warehouse stock allocation:

### Allocation Strategies

| Strategy | Description |
|----------|-------------|
| Prioritize sorting order | Allocate from warehouses in the order they are sorted in the channel |
| Prioritize by distance | Allocate from the warehouse closest to the shipping address |

### Warehouse Configuration

| Field | Description |
|-------|-------------|
| `name` | Warehouse display name |
| `slug` | URL-friendly identifier |
| `shippingZones` | Zones this warehouse serves |
| `address` | Physical warehouse address |
| `clickAndCollectOption` | `DISABLED`, `LOCAL_STOCK`, or `ALL_WAREHOUSES` |
| `isPrivate` | Whether warehouse is hidden from customers |

### Warehouse Mutations

| Operation | Mutation |
|-----------|----------|
| Create warehouse | `createWarehouse` |
| Update warehouse | `updateWarehouse` |
| Delete warehouse | `deleteWarehouse` |

## Click-and-Collect / Warehouse Pickup

Enable customers to pick up orders from physical locations:

| Option | Description |
|--------|-------------|
| `DISABLED` | No pickup available at this warehouse |
| `LOCAL_STOCK` | Pickup available only for items in stock at this warehouse |
| `ALL_WAREHOUSES` | Pickup available; stock can be transferred from other warehouses |

### Checkout Integration

When click-and-collect is enabled:

| Step | Description |
|------|-------------|
| 1. Set shipping address | Customer sets their address (or warehouse address) |
| 2. Query delivery methods | `checkout.deliveryMethod` returns both shipping and pickup options |
| 3. Select pickup | Use `checkoutDeliveryMethodUpdate` with warehouse ID |
| 4. Complete checkout | Standard checkout completion flow |

> **Fetch live docs** for the `DeliveryMethod` union type which includes both `ShippingMethod` and `Warehouse` for pickup locations.

## Best Practices

- Create separate shipping zones for domestic and international shipping
- Use price-based methods for flat-rate/tiered shipping; weight-based when weight significantly affects cost
- Implement a custom shipping App for real-time carrier rate calculation
- Assign warehouses to shipping zones to control which locations fulfill which regions
- Use channel listings to set different shipping prices per channel and currency
- Configure a default shipping zone as a fallback for unmatched countries
- Set delivery day estimates to improve customer experience
- Enable click-and-collect on warehouses that serve as customer-facing pickup points

Fetch the Saleor shipping and warehouse documentation for exact mutation inputs, webhook payloads, and allocation strategy configuration before implementing.