bagisto/shipping-method-development

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

<?php

return [
    'custom_express_shipping' => [
        '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

<?php

namespace Webkul\CustomExpressShipping\Carriers;

use Webkul\Shipping\Carriers\AbstractShipping;
use Webkul\Checkout\Models\CartShippingRate;
use Webkul\Checkout\Facades\Cart;

class CustomExpressShipping extends AbstractShipping
{
    /**
     * Shipping method code - must match carriers.php key.
     *
     * @var string
     */
    protected $code = 'custom_express_shipping';

    /**
     * Shipping method code.
     *
     * @var string
     */
    protected $method = 'custom_express_shipping_custom_express_shipping';

    /**
     * Calculate shipping rate for the current cart.
     *
     * @return \Webkul\Checkout\Models\CartShippingRate|false
     */
    public function calculate()
    {
        if (! $this->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

<?php

return [
    [
        'key'    => '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

<?php

namespace Webkul\CustomExpressShipping\Providers;

use Illuminate\Support\ServiceProvider;

class CustomExpressShippingServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     *
     * @return void
     */
    public function register(): void
    {
        $this->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

1. Add to composer.json (in Bagisto root directory):

{
    "autoload": {
        "psr-4": {
            "Webkul\\CustomExpressShipping\\": "packages/Webkul/CustomExpressShipping/src"
        }
    }
}

2. Update autoloader:

composer dump-autoload

3. Register service provider in bootstrap/providers.php:

<?php

return [
    App\Providers\AppServiceProvider::class,

    // ... other providers ...

    Webkul\CustomExpressShipping\Providers\CustomExpressShippingServiceProvider::class,
];

4. Clear caches:

php artisan optimize:clear

Base Carrier Class Reference

Location: packages/Webkul/Shipping/src/Carriers/AbstractShipping.php

All shipping methods extend Webkul\Shipping\Carriers\AbstractShipping:

<?php

namespace Webkul\Shipping\Carriers;

use Webkul\Shipping\Exceptions\CarrierCodeException;

abstract class AbstractShipping
{
    /**
     * Shipping method carrier code.
     *
     * @var string
     */
    protected $code;

    /**
     * Shipping method code.
     *
     * @var string
     */
    protected $method;

    abstract public function calculate();

    /**
     * Checks if shipping method is available.
     *
     * @return array
     */
    public function isAvailable()
    {
        return $this->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

<?php

namespace Webkul\Checkout\Models;

use Illuminate\Database\Eloquent\Model;
use Webkul\Checkout\Contracts\CartShippingRate as CartShippingRateContract;

class CartShippingRate extends Model implements CartShippingRateContract
{
    protected $fillable = [
        'carrier',
        'carrier_title',
        'method',
        'method_title',
        'method_description',
        'price',
        'base_price',
        'discount_amount',
        'base_discount_amount',
        'tax_percent',
        'tax_amount',
        'base_tax_amount',
        'price_incl_tax',
        'base_price_incl_tax',
        'applied_tax_rate',
    ];
}

Key Methods to Implement

| Method | Purpose | Required | |--------|---------|----------| | calculate() | Calculate and return shipping rate | Yes (abstract) | | getRate() | Build CartShippingRate object | No (can be inline) | | isAvailable() | Override for custom availability | No (uses default) |

Built-in Shipping Methods

• FlatRate: packages/Webkul/Shipping/src/Carriers/FlatRate.php
• Free: packages/Webkul/Shipping/src/Carriers/Free.php

Pricing Examples

Fixed Rate Shipping

public function calculate()
{
    if (! $this->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