Commerce Shipping
Provides core shipping functionality for Drupal Commerce, including shipment management, rate calculation, and shipping method configuration.
commerce_shipping
Install
composer require 'drupal/commerce_shipping:8.x-2.15'
Overview
Commerce Shipping is the official shipping module for Drupal Commerce that provides comprehensive shipping functionality for e-commerce stores. It enables store owners to define shipping methods, calculate shipping rates, and manage shipments throughout the order fulfillment process.
The module introduces four main entity types: Shipments (content entity tracking shipped items and their status), Shipping Methods (content entity defining how shipping rates are calculated), Shipment Types (bundle configuration for shipments), and Package Types (configuration entity defining box dimensions and weight).
Commerce Shipping integrates seamlessly with the Commerce checkout flow through a dedicated checkout pane that collects shipping addresses and displays available shipping rates. It supports multiple shipments per order, allowing items to be split across different packages or shipped to different addresses.
The module provides a pluggable architecture for shipping methods, allowing third-party integrations with carriers like UPS, FedEx, and USPS. Built-in shipping methods include Flat Rate and Flat Rate Per Item for simple shipping cost calculations.
Features
- Shipment entity management with workflow states (Draft, Ready, Shipped, Canceled)
- Multiple shipping methods with conditions-based applicability
- Flat rate and flat rate per item shipping method plugins included
- Package type configuration for defining box dimensions and weight
- Checkout pane for shipping address collection and rate selection
- Automatic shipping rate calculation and recalculation on address changes
- Shipment confirmation emails with tracking information
- Integration with Commerce Promotions for shipping discounts (fixed amount off, percentage off)
- Integration with Commerce Tax for shipping tax calculation with multiple strategies
- Support for multiple shipments per order
- Product variation traits for shippable products (weight and dimensions)
- Packer system for organizing order items into shipments
- Full lifecycle event system for customization
- Views integration for shipment administration
- JSON API field access protection for sensitive shipment data
Use Cases
Simple Flat Rate Shipping
Configure a single flat rate shipping method for all orders. Create a shipping method with the 'Flat rate' plugin, set a fixed rate amount (e.g., $5.00), and enable it for your stores. All shippable orders will show this rate at checkout.
Free Shipping Over Threshold
Offer free shipping for orders over a certain amount. Create two shipping methods: one with a flat rate and conditions restricting it to orders below the threshold, and another with $0 amount and conditions for orders at or above the threshold.
Weight-Based Shipping Tiers
Charge different rates based on shipment weight. Create multiple shipping methods with shipment_weight conditions using range operators. For example: $5 for 0-1kg, $10 for 1-5kg, $20 for 5-10kg.
Regional Shipping Rates
Charge different rates by geographic region. Create shipping methods with shipment_address conditions using address zones. Configure zones for domestic, regional, and international shipping with appropriate rates.
Per-Item Shipping for Heavy Products
Charge shipping per item for products that can't be combined. Use the 'Flat rate per item' shipping method plugin. Set a per-unit rate that multiplies by the total quantity.
Multiple Shipments for Split Orders
Handle orders requiring multiple shipments to different addresses or with different fulfillment sources. The packer system automatically creates separate shipments based on configuration, and checkout displays rate selection for each shipment.
Shipping Tax Calculation
Apply taxes to shipping costs based on destination. Create a 'Shipping' tax type and select a strategy: 'proportional' applies each item's tax rate to the shipping proportionally, 'highest' uses the highest rate found in the order.
Shipping Promotions
Run shipping promotions like free shipping codes or discounted shipping. Create promotions with 'Fixed amount off the shipment amount' or 'Percentage off the shipment amount' offers. Optionally restrict to specific shipping methods.
Shipment Tracking Integration
Provide tracking information to customers. When shipping a shipment, enter the tracking code. If your shipping method plugin supports tracking URLs (common with carrier integrations like UPS/FedEx modules), customers will see clickable tracking links.
Custom Packing Logic
Implement custom logic for organizing items into shipments. Create a custom packer service implementing PackerInterface, tag it with 'commerce_shipping.packer' and set priority. Your packer can group items by vendor, weight limits, or other criteria.
Tips
- Enable the 'Shippable' trait on product variation types before adding products, as existing variations won't automatically get weight values.
- Use address zones in shipping method conditions for geographic-based rate variations instead of creating many individual conditions.
- The checkout pane's auto-recalculate feature provides the best user experience but increases server load. Disable it for high-traffic sites if needed.
- Configure multiple package types if you have different box sizes. The shipment form will show a package type selector when multiple options exist.
- Shipment confirmation BCC is useful for fulfillment team notifications without requiring custom code.
- The 'proportional' tax strategy is most accurate for mixed-tax-rate orders but requires Commerce Tax configuration.
- Custom shipping method plugins can implement getTrackingUrl() to provide carrier tracking links.
- Use the SHIPPING_RATES event to modify calculated rates, such as adding handling fees or applying dynamic discounts.
Technical Details
Admin Pages 9
/admin/commerce/config/shipping
Main shipping configuration landing page providing access to all shipping-related configuration including shipping methods, shipment types, and package types.
/admin/commerce/shipping-methods
List and manage all shipping methods. Shipping methods define how shipping rates are calculated and which stores they apply to. Methods can have conditions that control their availability based on order or shipment properties.
/admin/commerce/shipping-methods/add
Form for creating a new shipping method with plugin selection, store assignment, and condition configuration.
/admin/commerce/config/shipment-types
Manage shipment type bundles. Each shipment type can have different profile types and email confirmation settings.
/admin/commerce/config/shipment-types/add
Form for creating a new shipment type with profile type selection and confirmation email settings.
/admin/commerce/config/package-types
Define reusable package/box types with specific dimensions and weight. Package types are used during shipment creation to calculate total shipment weight.
/admin/commerce/config/package-types/add
Form for defining a new package type with dimensions and empty weight.
/admin/commerce/orders/{commerce_order}/shipments
View and manage shipments for a specific order. Displays all shipments with their items, status, and allows state transitions.
/admin/commerce/orders/{commerce_order}/shipments/add/{commerce_shipment_type}
Form for creating a new shipment within an order, selecting items, package type, shipping method, and entering tracking information.
Permissions 4
Hooks 2
hook_commerce_shipping_methods_alter
Alter shipping methods loaded for rate calculation
commerce_shipping.filter_shipping_methods event
Event-based alternative to hook for filtering shipping methods
Troubleshooting 6
Verify: 1) The order type has shipping enabled and a shipment type selected, 2) Product variations have the 'Shippable' trait enabled and weight values set, 3) At least one shipping method exists and is enabled, 4) The checkout flow includes the 'Shipping information' pane, 5) Shipping method conditions (if any) match the order.
Enable 'Auto recalculate shipping costs when the shipping address changes' in the Shipping information checkout pane configuration. Also ensure 'Hide shipping costs until an address is entered' is enabled for this to work.
Edit the shipment type and enable 'Send customer an email confirmation when shipped'. Emails are sent when shipments transition to the 'Shipped' state via the ship transition.
Shipment types cannot be deleted while shipments of that type exist. Delete all associated shipments first, or reassign them to a different shipment type.
Check the condition operator setting (AND vs OR). With AND, all conditions must pass. Verify condition configuration values match actual order/shipment data. Use debugging to inspect condition evaluation.
Shipment weight includes both item weights and the package type's empty weight. Verify product variation weights are set correctly and the selected package type has the correct empty weight.
Security Notes 4
- All shipping administration permissions are marked as 'restrict access' and should only be granted to trusted roles.
- The commerce_shipping.field_access service protects sensitive shipment fields (amount, adjustments, shipping_method) from unauthorized access via JSON API.
- Shipping profile data contains customer addresses - ensure proper access controls on shipment and profile entities.
- Shipment confirmation emails should be reviewed to ensure no sensitive order data is exposed inappropriately.