Custom shipping handler
This page is for developers who need shipping rules beyond the flat amount of the
Simple shipping event. No shipping handler is shipped in the kernel; the
contract is documented in kernel/classes/ezshippingmanager.php, and this page turns it into a recipe.
Contents
- The contract
- What getShippingInfo returns
- Registering the handler
- How shipping reaches the totals
- Common models
- Testing
The contract
eZShippingManager loads the handler named in shop.ini [ShippingSettings] Handler and calls three methods, each
with the basket's product collection id:
| Method | Called | Returns |
|---|---|---|
getShippingInfo( $productCollectionID ) | Whenever the basket, the confirmation or totals need shipping | An array (below), or nothing for no shipping |
updateShippingInfo( $productCollectionID ) | When an item is added (the update-shipping-info step of addtobasket) | Anything your handler needs; use it to recalculate or store choices |
purgeShippingInfo( $productCollectionID ) | When shipping information should be removed | Nothing |
The class name is <name>ShippingHandler in <name>shippinghandler.php.
What getShippingInfo returns
One shipping line:
return array( 'description' => 'Standard delivery',
'cost' => 6.50,
'vat_value' => 20,
'is_vat_inc' => 1 );Several lines, for example when parcels carry different VAT rates:
return array( 'shipping_items' => array(
array( 'description' => 'Parcel, standard VAT', 'cost' => 5.00, 'vat_value' => 20, 'is_vat_inc' => 1 ),
array( 'description' => 'Parcel, reduced VAT', 'cost' => 3.00, 'vat_value' => 5, 'is_vat_inc' => 1 ) ),
'description' => 'Total shipping',
'cost' => 8.00,
'vat_value' => false,
'is_vat_inc' => 1 );| Key | Meaning |
|---|---|
description | Text shown to the customer |
cost | Amount as a float |
vat_value | VAT percentage as a number, or false when the total combines several rates |
is_vat_inc | 1 if cost includes VAT, 0 if not |
| any other key | Passed to templates, for example management_link to a page where the customer picks a method |
Registering the handler
In your extension's settings/shop.ini.append.php:
[ShippingSettings]
Handler=mystore
ExtensionDirectories[]=mystore_shopand the class in extension/mystore_shop/shippinghandlers/mystoreshippinghandler.php. If the file is not found, the
debug log says "Shipping handler 'mystore' not found" with the directories searched. Remove the simple shipping
workflow from the confirmorder trigger when the handler goes live.
How shipping reaches the totals
eZShippingManager::vatPriceInfo() turns your array into amounts per VAT rate, and the shipped basket info handler
(ezdefault) adds them to the basket's price information per VAT rate and to the total
(Basket info and confirm order handlers). The handle-shipping step of
the confirmorder operation applies shipping when the order is confirmed
(Checkout operations step by step).
Common models
| Model | What the handler reads |
|---|---|
| Free shipping above an amount | The product collection's items and their prices |
| Rates by country or zone | The customer's country (eZVATManager::getUserCountry()) or the account data |
| Rates by weight | A weight field on product classes, times item counts |
| Customer chooses a method | A choice stored by your own view (linked with management_link), read back by getShippingInfo() |
| Carrier rate service | A call to the carrier with the address and parcel data; cache the answer per basket |
Whether shipping carries VAT, and at which rate, is a question for your tax adviser.
Testing
- To do: Unit tests for the calculation with fixed baskets (DB-less PHPUnit tests).
- To do: Basket, confirmation, order view and mail show the same shipping.
- To do: Changing quantities changes shipping when it should.
- To do: Each country or zone you support, and one you do not.
- To do: No second shipping line from an old simple shipping workflow.
Related pages
- Extending the shop
- Shipping and handling (businesses)
- shop.ini walkthrough
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.