OrcaQubits Saleor Shipping Configuration
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io shipping zones methods configurationfor shipping zone and method setup - Web-search
site:docs.saleor.io warehouse allocation shippingfor warehouse-based stock allocation strategies - Web-search
site:docs.saleor.io shipping app SHIPPING_LIST_METHODS_FOR_CHECKOUTfor custom shipping App patterns - Fetch
https://docs.saleor.io/docs/developer/shippingand review shipping zone, method, and pricing models - Web-search
site:docs.saleor.io click and collect warehouse pickupfor 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
DeliveryMethodunion type which includes bothShippingMethodandWarehousefor 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.