Shipping Method Development

Overview

Creating custom shipping methods in Bagisto allows you to tailor delivery options to meet your specific business needs. Whether you need special handling for fragile items, express delivery options, or region-specific shipping rules, custom shipping methods provide the flexibility your e-commerce store requires.

For our tutorial, we'll create a

Custom Express Shipping

method that demonstrates all the essential concepts you need to build any type of shipping solution.

When to Apply

Activate this skill when:

Creating new shipping methods

Integrating shipping carriers (FedEx, UPS, DHL, USPS, etc.)

Adding shipping options to checkout

Modifying existing shipping configurations

Creating admin configuration for shipping methods

Implementing rate calculation logic

Bagisto Shipping Architecture

Bagisto's shipping system is built around a flexible carrier-based architecture that separates configuration from business logic.

Core Components

Component

Purpose

Location

Carriers Configuration

Defines shipping method properties

Config/carriers.php

Carrier Classes

Contains rate calculation logic

Carriers/ClassName.php

System Configuration

Admin interface forms

Config/system.php

Service Provider

Registers shipping method

Providers/ServiceProvider.php

Shipping Facade

Collects and manages rates

Webkul\Shipping\Shipping

Key Features

Flexible Rate Calculation

Support for per-unit, per-order, weight-based, or custom pricing.

Configuration Management

Admin-friendly settings interface.

Multi-channel Support

Different rates and settings per sales channel.

Localization Ready

Full translation support.

Extensible Architecture

Easy integration with third-party APIs. Step-by-Step Guide Step 1: Create Package Directory Structure mkdir -p packages/Webkul/CustomExpressShipping/src/ { Carriers,Config,Providers } Step 2: Create Carrier Configuration File: packages/Webkul/CustomExpressShipping/src/Config/carriers.php

[ 'code' => 'custom_express_shipping' , 'title' => 'Express Delivery (1-2 Days)' , 'description' => 'Premium express shipping with tracking' , 'active' => true , 'default_rate' => '19.99' , 'type' => 'per_order' , 'class' => 'Webkul\CustomExpressShipping\Carriers\CustomExpressShipping' , ] , ] ; Configuration Properties Explained Property Type Purpose Description code String Unique identifier Must match the array key and $code property in carrier class. title String Default display name Shown to customers during checkout (can be overridden in admin). description String Method description Brief explanation of the shipping service. active Boolean Default status Whether the shipping method is enabled by default. default_rate String/Float Base shipping cost Base shipping cost before calculations. type String Pricing model per_order (flat rate) or per_unit (per item). class String Carrier class namespace Full path to your carrier class. Note: The array key ( custom_express_shipping ) must match the code property in your carrier class, system configuration key path, and should be consistent throughout. Step 3: Create Carrier Class File: packages/Webkul/CustomExpressShipping/src/Carriers/CustomExpressShipping.php isAvailable ( ) ) { return false ; } return $this -> getRate ( ) ; } /** * Get shipping rate. * * @return \ Webkul \ Checkout \ Models \ CartShippingRate */ public function getRate ( ) : CartShippingRate { $cart = Cart :: getCart ( ) ; $cartShippingRate = new CartShippingRate ; $cartShippingRate -> carrier = $this -> getCode ( ) ; $cartShippingRate -> carrier_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> method = $this -> getMethod ( ) ; $cartShippingRate -> method_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> method_description = $this -> getConfigData ( 'description' ) ; $cartShippingRate -> price = 0 ; $cartShippingRate -> base_price = 0 ; $baseRate = ( float ) $this -> getConfigData ( 'default_rate' ) ; if ( $this -> getConfigData ( 'type' ) == 'per_unit' ) { foreach ( $cart -> items as $item ) { if ( $item -> getTypeInstance ( ) -> isStockable ( ) ) { $cartShippingRate -> price += core ( ) -> convertPrice ( $baseRate ) * $item -> quantity ; $cartShippingRate -> base_price += $baseRate * $item -> quantity ; } } } else { $cartShippingRate -> price = core ( ) -> convertPrice ( $baseRate ) ; $cartShippingRate -> base_price = $baseRate ; } return $cartShippingRate ; } } Step 4: Create System Configuration File: packages/Webkul/CustomExpressShipping/src/Config/system.php 'sales.carriers.custom_express_shipping' , 'name' => 'Custom Express Shipping' , 'info' => 'Configure the Custom Express Shipping method settings.' , 'sort' => 1 , 'fields' => [ [ 'name' => 'title' , 'title' => 'Method Title' , 'type' => 'text' , 'validation' => 'required' , 'channel_based' => true , 'locale_based' => true , ] , [ 'name' => 'description' , 'title' => 'Description' , 'type' => 'textarea' , 'channel_based' => true , 'locale_based' => false , ] , [ 'name' => 'default_rate' , 'title' => 'Base Rate' , 'type' => 'text' , 'validation' => 'required|numeric|min:0' , 'channel_based' => true , 'locale_based' => false , ] , [ 'name' => 'type' , 'title' => 'Pricing Type' , 'type' => 'select' , 'options' => [ [ 'title' => 'Per Order (Flat Rate)' , 'value' => 'per_order' , ] , [ 'title' => 'Per Item' , 'value' => 'per_unit' , ] , ] , 'channel_based' => true , 'locale_based' => false , ] , [ 'name' => 'active' , 'title' => 'Enabled' , 'type' => 'boolean' , 'validation' => 'required' , 'channel_based' => true , 'locale_based' => false , ] , ] , ] , ] ; System Configuration Field Properties Property Purpose Description name Field identifier Used to store and retrieve configuration values. title Field label Label displayed in the admin form. type Input type text , textarea , boolean , select , password , etc. default_value Default setting Initial value when first configured. channel_based Multi-store support Different values per sales channel. locale_based Multi-language support Translatable content per language. validation Field validation Rules like required , numeric , email . Step 5: Create Service Provider File: packages/Webkul/CustomExpressShipping/src/Providers/CustomExpressShippingServiceProvider.php mergeConfigFrom ( dirname ( __DIR__ ) . '/Config/carriers.php' , 'carriers' ) ; $this -> mergeConfigFrom ( dirname ( __DIR__ ) . '/Config/system.php' , 'core' ) ; } /** * Bootstrap services. * * @return void */ public function boot ( ) : void { // } } Step 6: Register Your Package Add to composer.json (in Bagisto root directory): { "autoload" : { "psr-4" : { "Webkul\\CustomExpressShipping\\" : "packages/Webkul/CustomExpressShipping/src" } } } Update autoloader: composer dump-autoload Register service provider in bootstrap/providers.php : getConfigData ( 'active' ) ; } /** * Returns shipping method carrier code. * * @return string */ public function getCode ( ) { if ( empty ( $this -> code ) ) { throw new CarrierCodeException ( 'Carrier code should be initialized.' ) ; } return $this -> code ; } /** * Return shipping method code. * * @return string */ public function getMethod ( ) { if ( empty ( $this -> method ) ) { $code = $this -> getCode ( ) ; return $code . '_' . $code ; } return $this -> method ; } /** * Returns shipping method title. * * @return array */ public function getTitle ( ) { return $this -> getConfigData ( 'title' ) ; } /** * Returns shipping method description. * * @return array */ public function getDescription ( ) { return $this -> getConfigData ( 'description' ) ; } /** * Retrieve information from shipping configuration. * * @param string $field * @return mixed */ public function getConfigData ( $field ) { return core ( ) -> getConfigData ( 'sales.carriers.' . $this -> getCode ( ) . '.' . $field ) ; } } CartShippingRate Model Location: packages/Webkul/Checkout/src/Models/CartShippingRate.php isAvailable ( ) ) { return false ; } $cartShippingRate = new CartShippingRate ; $cartShippingRate -> carrier = $this -> getCode ( ) ; $cartShippingRate -> carrier_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> method = $this -> getMethod ( ) ; $cartShippingRate -> method_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> method_description = $this -> getConfigData ( 'description' ) ; $cartShippingRate -> price = 15.99 ; $cartShippingRate -> base_price = 15.99 ; return $cartShippingRate ; } Weight-Based Pricing public function calculate ( ) { if ( ! $this -> isAvailable ( ) ) { return false ; } $cart = Cart :: getCart ( ) ; $baseRate = 5.00 ; $perKg = 2.50 ; $price = $baseRate + ( $cart -> weight * $perKg ) ; $cartShippingRate = new CartShippingRate ; $cartShippingRate -> carrier = $this -> getCode ( ) ; $cartShippingRate -> carrier_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> method = $this -> getMethod ( ) ; $cartShippingRate -> method_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> price = core ( ) -> convertPrice ( $price ) ; $cartShippingRate -> base_price = $price ; return $cartShippingRate ; } Free Shipping Above Threshold public function calculate ( ) { if ( ! $this -> isAvailable ( ) ) { return false ; } $cart = Cart :: getCart ( ) ; $threshold = ( float ) $this -> getConfigData ( 'free_shipping_threshold' ) ; $price = $cart -> sub_total >= $threshold ? 0 : ( float ) $this -> getConfigData ( 'default_rate' ) ; $cartShippingRate = new CartShippingRate ; $cartShippingRate -> carrier = $this -> getCode ( ) ; $cartShippingRate -> carrier_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> method = $this -> getMethod ( ) ; $cartShippingRate -> method_title = $this -> getConfigData ( 'title' ) ; $cartShippingRate -> price = core ( ) -> convertPrice ( $price ) ; $cartShippingRate -> base_price = $price ; return $cartShippingRate ; } Shipping Facade Location: packages/Webkul/Shipping/src/Shipping.php The Shipping facade manages rate collection and processing: class Shipping { public function collectRates ( ) { // Iterates through all carriers and calls calculate() // Returns grouped shipping methods with rates } public function getGroupedAllShippingRates ( ) { // Returns rates grouped by carrier } public function getShippingMethods ( ) { // Returns available shipping methods } } Package Structure packages └── Webkul └── CustomExpressShipping └── src ├── Carriers │ └── CustomExpressShipping.php # Rate calculation logic ├── Config │ ├── carriers.php # Shipping method definition │ └── system.php # Admin configuration └── Providers └── CustomExpressShippingServiceProvider.php # Registration Testing Shipping methods can be tested through the checkout flow. Test: Method appears in checkout when enabled Rate calculation is correct Admin configuration saves properly Method respects enabled/disabled status Key Files Reference File Purpose packages/Webkul/Shipping/src/Carriers/AbstractShipping.php Base abstract class packages/Webkul/Shipping/src/Carriers/FlatRate.php Flat rate shipping example packages/Webkul/Shipping/src/Carriers/Free.php Free shipping example packages/Webkul/Shipping/src/Config/carriers.php Default carriers config packages/Webkul/Shipping/src/Shipping.php Shipping facade packages/Webkul/Checkout/src/Models/CartShippingRate.php Shipping rate model packages/Webkul/Admin/src/Config/system.php Admin config (carrier sections) Common Pitfalls Forgetting to merge config in service provider Not matching $code property with config array key Not registering service provider in bootstrap/providers.php Forgetting to run composer dump-autoload after adding package Not clearing cache after configuration changes Not using core()->convertPrice() for multi-currency support Not checking isStockable() for per-item calculations Not following PHPDoc conventions with proper punctuation ?>