Shipping Method API

Create custom shipping methods and integrate with shipping zones in WooCommerce

Shipping Method API

The WooCommerce Shipping Method API enables you to create custom shipping methods that integrate with shipping zones and provide dynamic rate calculations for your store.

Overview

Shipping methods in WooCommerce extend the WC_Shipping_Method class and can provide rates based on:

• Cart contents (weight, dimensions, value)
• Customer location (shipping zones)
• Product shipping classes
• Custom business logic

Since WooCommerce 2.6, shipping methods use shipping zones and instances, allowing merchants to configure different settings for the same shipping method in different regions.

Creating a Shipping Method Plugin

Step 1: Plugin Setup

Create your plugin file:

<?php
/**
 * Plugin Name: Custom Shipping Method
 * Description: A custom shipping method for WooCommerce
 * Version: 1.0.0
 * Author: Your Name
 * Text Domain: custom-shipping-method
 */

defined( 'ABSPATH' ) || exit;

// Check if WooCommerce is active
if ( ! in_array( 'woocommerce/woocommerce.php', apply_filters( 'active_plugins', get_option( 'active_plugins' ) ), true ) ) {
    return;
}

/**
 * Initialize the shipping method.
 */
function init_custom_shipping_method() {
    if ( ! class_exists( 'WC_Shipping_Method' ) ) {
        return;
    }
    
    require_once plugin_dir_path( __FILE__ ) . 'class-wc-shipping-custom.php';
}
add_action( 'woocommerce_shipping_init', 'init_custom_shipping_method' );

/**
 * Add the shipping method to WooCommerce.
 *
 * @param array $methods Existing shipping methods.
 * @return array
 */
function add_custom_shipping_method( $methods ) {
    $methods['custom_shipping'] = 'WC_Shipping_Custom';
    return $methods;
}
add_filter( 'woocommerce_shipping_methods', 'add_custom_shipping_method' );

Step 2: Create the Shipping Method Class

Create class-wc-shipping-custom.php:

<?php

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Custom Shipping Method.
 *
 * @extends WC_Shipping_Method
 */
class WC_Shipping_Custom extends WC_Shipping_Method {
    
    /**
     * Constructor.
     *
     * @param int $instance_id Shipping zone instance ID.
     */
    public function __construct( $instance_id = 0 ) {
        $this->id                 = 'custom_shipping';
        $this->instance_id        = absint( $instance_id );
        $this->method_title       = __( 'Custom Shipping', 'custom-shipping-method' );
        $this->method_description = __( 'Custom shipping method with advanced options', 'custom-shipping-method' );
        
        // Supported features
        $this->supports = array(
            'shipping-zones',
            'instance-settings',
            'instance-settings-modal',
        );
        
        // Initialize
        $this->init();
    }
    
    /**
     * Initialize shipping method.
     */
    public function init() {
        // Load the settings
        $this->init_form_fields();
        $this->init_settings();
        
        // Get settings
        $this->title      = $this->get_option( 'title' );
        $this->tax_status = $this->get_option( 'tax_status' );
        $this->cost       = $this->get_option( 'cost' );
        
        // Save settings
        add_action( 'woocommerce_update_options_shipping_' . $this->id, array( $this, 'process_admin_options' ) );
    }
    
    /**
     * Define settings form fields.
     */
    public function init_form_fields() {
        $this->instance_form_fields = array(
            'title' => array(
                'title'       => __( 'Method Title', 'custom-shipping-method' ),
                'type'        => 'text',
                'description' => __( 'This controls the title customers see during checkout.', 'custom-shipping-method' ),
                'default'     => __( 'Custom Shipping', 'custom-shipping-method' ),
                'desc_tip'    => true,
            ),
            'tax_status' => array(
                'title'   => __( 'Tax Status', 'custom-shipping-method' ),
                'type'    => 'select',
                'class'   => 'wc-enhanced-select',
                'default' => 'taxable',
                'options' => array(
                    'taxable' => __( 'Taxable', 'custom-shipping-method' ),
                    'none'    => __( 'None', 'custom-shipping-method' ),
                ),
            ),
            'cost' => array(
                'title'       => __( 'Cost', 'custom-shipping-method' ),
                'type'        => 'text',
                'placeholder' => '0',
                'description' => __( 'Enter a cost (excluding tax) or leave blank to disable.', 'custom-shipping-method' ),
                'default'     => '0',
                'desc_tip'    => true,
            ),
        );
    }
    
    /**
     * Calculate shipping rates.
     *
     * @param array $package Package information.
     */
    public function calculate_shipping( $package = array() ) {
        $rate = array(
            'id'      => $this->get_rate_id(),
            'label'   => $this->title,
            'cost'    => $this->cost,
            'package' => $package,
        );
        
        $this->add_rate( $rate );
    }
}

Shipping Method Properties

id · string · required

Unique identifier for your shipping method

instance_id · int

Instance ID when used within a shipping zone

method_title · string · required

Title shown in the admin shipping settings

method_description · string

Description shown in the admin

supports · array

Features supported by the method:

• shipping-zones - Works with shipping zones
• instance-settings - Has per-instance settings
• instance-settings-modal - Settings can be edited in a modal
• settings - Has global settings page

enabled · string · default: "yes"

Whether the method is enabled

title · string

Title displayed to customers at checkout

tax_status · string · default: "taxable"

Tax status: taxable or none

Calculating Shipping Rates

The calculate_shipping() method is called when WooCommerce needs shipping rates for a cart.

Basic Rate Calculation

public function calculate_shipping( $package = array() ) {
    $rate = array(
        'id'       => $this->get_rate_id(),
        'label'    => $this->title,
        'cost'     => $this->cost,
        'calc_tax' => 'per_order',
        'package'  => $package,
    );
    
    $this->add_rate( $rate );
}

Weight-Based Calculation

public function calculate_shipping( $package = array() ) {
    $weight = 0;
    
    // Calculate total weight
    foreach ( $package['contents'] as $item_id => $values ) {
        $weight += $values['data']->get_weight() * $values['quantity'];
    }
    
    // Calculate cost based on weight
    $cost = 0;
    if ( $weight > 0 ) {
        $cost = 5 + ( $weight * 0.5 ); // Base cost + per kg rate
    }
    
    $rate = array(
        'id'      => $this->get_rate_id(),
        'label'   => $this->title,
        'cost'    => $cost,
        'package' => $package,
    );
    
    $this->add_rate( $rate );
}

Cart Value-Based Calculation

public function calculate_shipping( $package = array() ) {
    $cart_total = 0;
    
    // Calculate cart total
    foreach ( $package['contents'] as $item_id => $values ) {
        $cart_total += $values['line_total'];
    }
    
    // Free shipping over threshold
    $free_shipping_threshold = 100;
    $cost = $cart_total >= $free_shipping_threshold ? 0 : 10;
    
    $rate = array(
        'id'      => $this->get_rate_id(),
        'label'   => $this->title,
        'cost'    => $cost,
        'package' => $package,
    );
    
    $this->add_rate( $rate );
}

Working with Shipping Classes

Shipping classes allow different products to have different shipping costs.

Adding Shipping Class Support

public function init_form_fields() {
    $this->instance_form_fields = array(
        'title' => array(
            'title'   => __( 'Method Title', 'custom-shipping-method' ),
            'type'    => 'text',
            'default' => __( 'Custom Shipping', 'custom-shipping-method' ),
        ),
        'cost' => array(
            'title'       => __( 'Base Cost', 'custom-shipping-method' ),
            'type'        => 'text',
            'placeholder' => '0',
            'default'     => '0',
        ),
        'type' => array(
            'title'   => __( 'Calculation Type', 'custom-shipping-method' ),
            'type'    => 'select',
            'class'   => 'wc-enhanced-select',
            'default' => 'class',
            'options' => array(
                'class' => __( 'Per Class: Charge shipping for each class individually', 'custom-shipping-method' ),
                'order' => __( 'Per Order: Charge shipping for the most expensive class', 'custom-shipping-method' ),
            ),
        ),
    );
    
    // Add fields for each shipping class
    $shipping_classes = WC()->shipping()->get_shipping_classes();
    
    if ( ! empty( $shipping_classes ) ) {
        foreach ( $shipping_classes as $shipping_class ) {
            if ( ! isset( $shipping_class->term_id ) ) {
                continue;
            }
            
            $this->instance_form_fields[ 'class_cost_' . $shipping_class->term_id ] = array(
                'title'       => sprintf( __( '"%s" Shipping Class Cost', 'custom-shipping-method' ), esc_html( $shipping_class->name ) ),
                'type'        => 'text',
                'placeholder' => __( 'N/A', 'custom-shipping-method' ),
                'description' => __( 'Enter a cost (excluding tax).', 'custom-shipping-method' ),
                'default'     => '',
                'desc_tip'    => true,
            );
        }
        
        $this->instance_form_fields['no_class_cost'] = array(
            'title'       => __( 'No Shipping Class Cost', 'custom-shipping-method' ),
            'type'        => 'text',
            'placeholder' => __( 'N/A', 'custom-shipping-method' ),
            'description' => __( 'Cost for products without a shipping class.', 'custom-shipping-method' ),
            'default'     => '',
            'desc_tip'    => true,
        );
    }
}

Calculate with Shipping Classes

public function calculate_shipping( $package = array() ) {
    $rate = array(
        'id'      => $this->get_rate_id(),
        'label'   => $this->title,
        'cost'    => $this->get_option( 'cost' ),
        'package' => $package,
    );
    
    // Get shipping classes in the package
    $found_shipping_classes = $this->find_shipping_classes( $package );
    $highest_class_cost = 0;
    
    foreach ( $found_shipping_classes as $shipping_class => $products ) {
        $shipping_class_term = get_term_by( 'slug', $shipping_class, 'product_shipping_class' );
        $class_cost = $shipping_class_term && $shipping_class_term->term_id
            ? $this->get_option( 'class_cost_' . $shipping_class_term->term_id, '' )
            : $this->get_option( 'no_class_cost', '' );
        
        if ( '' === $class_cost ) {
            continue;
        }
        
        if ( 'class' === $this->get_option( 'type' ) ) {
            $rate['cost'] += $class_cost;
        } else {
            $highest_class_cost = max( $highest_class_cost, $class_cost );
        }
    }
    
    if ( 'order' === $this->get_option( 'type' ) ) {
        $rate['cost'] += $highest_class_cost;
    }
    
    $this->add_rate( $rate );
}

/**
 * Find shipping classes in package.
 *
 * @param array $package Package information.
 * @return array
 */
public function find_shipping_classes( $package ) {
    $found_shipping_classes = array();
    
    foreach ( $package['contents'] as $item_id => $values ) {
        if ( $values['data']->needs_shipping() ) {
            $found_class = $values['data']->get_shipping_class();
            
            if ( ! isset( $found_shipping_classes[ $found_class ] ) ) {
                $found_shipping_classes[ $found_class ] = array();
            }
            
            $found_shipping_classes[ $found_class ][ $item_id ] = $values;
        }
    }
    
    return $found_shipping_classes;
}

Advanced Features

Multiple Rates

Offer multiple shipping options from one method:

public function calculate_shipping( $package = array() ) {
    // Standard shipping
    $this->add_rate( array(
        'id'      => $this->get_rate_id() . ':standard',
        'label'   => __( 'Standard Shipping (5-7 days)', 'custom-shipping-method' ),
        'cost'    => 5,
        'package' => $package,
    ) );
    
    // Express shipping
    $this->add_rate( array(
        'id'      => $this->get_rate_id() . ':express',
        'label'   => __( 'Express Shipping (2-3 days)', 'custom-shipping-method' ),
        'cost'    => 15,
        'package' => $package,
    ) );
    
    // Overnight shipping
    $this->add_rate( array(
        'id'      => $this->get_rate_id() . ':overnight',
        'label'   => __( 'Overnight Shipping', 'custom-shipping-method' ),
        'cost'    => 30,
        'package' => $package,
    ) );
}

Real-time API Integration

public function calculate_shipping( $package = array() ) {
    // Get customer location
    $destination = array(
        'country'  => $package['destination']['country'],
        'state'    => $package['destination']['state'],
        'postcode' => $package['destination']['postcode'],
        'city'     => $package['destination']['city'],
    );
    
    // Get package details
    $weight = 0;
    foreach ( $package['contents'] as $item ) {
        $weight += $item['data']->get_weight() * $item['quantity'];
    }
    
    try {
        // Call shipping API
        $response = wp_remote_post( 'https://api.shippingprovider.com/rates', array(
            'body' => array(
                'origin'      => $this->get_origin_address(),
                'destination' => $destination,
                'weight'      => $weight,
                'api_key'     => $this->get_option( 'api_key' ),
            ),
        ) );
        
        if ( is_wp_error( $response ) ) {
            return;
        }
        
        $rates = json_decode( wp_remote_retrieve_body( $response ), true );
        
        foreach ( $rates as $api_rate ) {
            $this->add_rate( array(
                'id'      => $this->get_rate_id() . ':' . $api_rate['service_code'],
                'label'   => $api_rate['service_name'],
                'cost'    => $api_rate['price'],
                'package' => $package,
            ) );
        }
    } catch ( Exception $e ) {
        // Log error but don't show rates if API fails
        error_log( 'Shipping API error: ' . $e->getMessage() );
    }
}

Conditional Availability

public function is_available( $package ) {
    // Not available for international orders
    if ( $package['destination']['country'] !== 'US' ) {
        return false;
    }
    
    // Not available for orders over 50kg
    $weight = 0;
    foreach ( $package['contents'] as $item ) {
        $weight += $item['data']->get_weight() * $item['quantity'];
    }
    
    if ( $weight > 50 ) {
        return false;
    }
    
    return parent::is_available( $package );
}

Shipping Zones Integration

1. Navigate to Shipping Zones

   Go to WooCommerce > Settings > Shipping and create or edit a shipping zone.

2. Add Shipping Method

   Click “Add shipping method” and select your custom method from the dropdown.

3. Configure Instance Settings

   Click “Edit” to configure the method’s settings for that specific zone.

4. Set Method Order

   Drag and drop to reorder methods within the zone.

Each instance of your shipping method in a zone can have different settings. For example, different costs for different regions.

Package Information

The $package array passed to calculate_shipping() contains:

array(
    'contents'        => array(), // Cart items
    'contents_cost'   => 0,       // Total cost of items
    'applied_coupons' => array(), // Applied coupon codes
    'user'            => array(
        'ID' => 0,
    ),
    'destination'     => array(
        'country'   => '',
        'state'     => '',
        'postcode'  => '',
        'city'      => '',
        'address'   => '',
        'address_2' => '',
    ),
)

Testing Your Shipping Method

1. Add to Shipping Zone

   Add your method to a test shipping zone.

2. Create Test Orders

   • Add products to cart
   • Enter different shipping addresses
   • Verify rates calculate correctly
3. Test Edge Cases

   • Empty cart
   • Very heavy orders
   • International addresses
   • Free shipping thresholds
4. Debug Output

   Use WooCommerce logging:

   $logger = wc_get_logger();
   $logger->debug( 'Calculated shipping cost: ' . $cost, array( 'source' => 'custom-shipping' ) );
   

Best Practices

• Performance: Cache external API calls to avoid slow checkout
• Validation: Always validate and sanitize settings input
• Error Handling: Gracefully handle API failures
• Backwards Compatibility: Support both instance and global settings if needed
• Logging: Use WooCommerce’s logger for debugging

Related Resources

• WC_Shipping_Method API Reference
• Shipping Zones Documentation
• WooCommerce Settings API