Shipping Method API

WooCommerce has a shipping method API which plugins can use to add their own rates. This article will take you through the steps to creating a new shipping method and interacting with the API.

Create a plugin

↑ Back to top

First, create a regular WordPress/WooCommerce plugin – see Create a plugin You’ll define your shipping method class in this plugin file and maintain it outside of WooCommerce.

Create a function to house your class

↑ Back to top

To ensure the classes you need to extend exist, you should wrap your class in a function which is called after all plugins are loaded:

function your_shipping_method_init() {
    // Your class will go here
}

add_action( 'woocommerce_shipping_init', 'your_shipping_method_init' );

Create your class

↑ Back to top

Create your class and place it inside the function you just created. Make sure it extends the shipping method class so that you have access to the API. You’ll see below we also init our shipping method options.

if ( ! class_exists( 'WC_Your_Shipping_Method' ) ) {
    class WC_Your_Shipping_Method extends WC_Shipping_Method {
        /**
         * Constructor for your shipping class
         *
         * @access public
         * @return void
         */
        public function __construct() {
            $this->id                 = 'your_shipping_method';
            $this->title       = __( 'Your Shipping Method' );
            $this->method_description = __( 'Description of your shipping method' ); // 
            $this->enabled            = "yes"; // This can be added as an setting but for this example its forced enabled
            $this->init();
        }

        /**
         * Init your settings
         *
         * @access public
         * @return void
         */
        function init() {
            // Load the settings API
            $this->init_form_fields(); // This is part of the settings API. Override the method to add your own settings
            $this->init_settings(); // This is part of the settings API. Loads settings you previously init.

            // Save settings in admin if you have any defined
            add_action( 'woocommerce_update_options_shipping_' . $this->id, array( $this, 'process_admin_options' ) );
        }

        /**
         * calculate_shipping function.
         *
         * @access public
         * @param mixed $package
         * @return void
         */
        public function calculate_shipping( $package ) {
            // This is where you'll add your rates
        }
    }
}

As well as declaring your class, you also need to tell WooCommerce it exists with another function:

function add_your_shipping_method( $methods ) {
    $methods['your_shipping_method'] = 'WC_Your_Shipping_Method'; 
    return $methods;
}

add_filter( 'woocommerce_shipping_methods', 'add_your_shipping_method' );

Defining settings/options

↑ Back to top

You can then define your options using the settings API. In the snippets above you’ll notice we init_form_fields and init_settings. These load up the settings API. To see how to add settings, see WooCommerce settings API.

The calculate_shipping() method

↑ Back to top

calculate_shipping() is a method which you use to add your rates – WooCommerce will call this when doing shipping calculations. Do your plugin specific calculations here and then add the rates via the API. How do you do that? Like so:

$rate = array(
    'label'    => "Label for the rate",
    'cost'     => '10.99',
    'calc_tax' => 'per_item'
);

// Register the rate
$this->add_rate( $rate );

Add_rate takes an array of options. The defaults/possible values for the array are as follows:

$defaults = array(
    'label' => '',   // Label for the rate
    'cost'  => '0',  // Amount for shipping or an array of costs (for per item shipping)
    'taxes' => '',   // Pass an array of taxes, or pass nothing to have it calculated for you, or pass 'false' to calculate no tax for this method
    'calc_tax' => 'per_order' // Calc tax per_order or per_item. Per item needs an array of costs passed via 'cost'
);

Your shipping method can pass as many rates as you want – just ensure that the id for each is different. The user will get to choose rate during checkout.

Piecing it all together

↑ Back to top

The skeleton shipping method code all put together looks like this: For further information, please check out the Shipping Method API Wiki.