WooCommerce Delivery Service Integration

WooCommerce Delivery Service Integration

WooCommerce out of the box offers three shipping methods: flat rate, free shipping, and local pickup. For real logistics this is insufficient — you need rates from specific carriers, cost calculation based on dimensions and weight, and tracking numbers in the customer's account.

How WooCommerce Works with Shipping

Shipping architecture is built on three layers:

• Shipping zones — geographic zones (country, region, postal code)
• Shipping methods — methods within a zone, each implements WC_Shipping_Method
• Shipping rates — rates that the method returns when calculating the cart

A custom shipping method is a class extending WC_Shipping_Method:

class My_Courier_Shipping_Method extends WC_Shipping_Method {

    public function __construct( $instance_id = 0 ) {
        $this->id                 = 'my_courier';
        $this->instance_id        = absint( $instance_id );
        $this->method_title       = 'MyCourier';
        $this->method_description = 'Shipping via MyCourier API';
        $this->supports           = [ 'shipping-zones', 'instance-settings' ];
        $this->init();
    }

    public function init(): void {
        $this->init_form_fields();
        $this->init_settings();
        $this->api_key = $this->get_option( 'api_key' );
        add_action( 'woocommerce_update_options_shipping_' . $this->id, [ $this, 'process_admin_options' ] );
    }

    public function calculate_shipping( $package = [] ): void {
        $rate = $this->get_rate_from_api( $package );
        if ( $rate ) {
            $this->add_rate([
                'id'    => $this->id . '_standard',
                'label' => 'Standard Shipping (' . $rate['days'] . ' days)',
                'cost'  => $rate['price'],
                'meta_data' => [ 'courier_id' => $rate['service_id'] ],
            ]);
        }
    }
}

The method is registered via a filter:

add_filter( 'woocommerce_shipping_methods', function( $methods ) {
    $methods['my_courier'] = My_Courier_Shipping_Method::class;
    return $methods;
});

Calculate Rates via Carrier API

Most Russian and international delivery services have REST APIs for cost calculation. Example request to a hypothetical API:

private function get_rate_from_api( array $package ): ?array {
    $weight = 0;
    $dimensions = [ 'length' => 0, 'width' => 0, 'height' => 0 ];

    foreach ( $package['contents'] as $item ) {
        $product = $item['data'];
        $qty     = $item['quantity'];
        $weight += (float) $product->get_weight() * $qty;
        // For volume — max from product dimensions in the order
    }

    $destination = $package['destination'];

    $response = wp_remote_post( 'https://api.mycourier.ru/v2/calculate', [
        'timeout' => 10,
        'headers' => [
            'Authorization' => 'Bearer ' . $this->api_key,
            'Content-Type'  => 'application/json',
        ],
        'body' => wp_json_encode([
            'from_city'   => get_option( 'woocommerce_store_city' ),
            'to_city'     => $destination['city'],
            'to_postcode' => $destination['postcode'],
            'weight'      => max( 0.1, $weight ),
            'declared_value' => WC()->cart->get_cart_contents_total(),
        ]),
    ]);

    if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
        return null;
    }

    return json_decode( wp_remote_retrieve_body( $response ), true );
}

The result is cached with a transient for 30–60 minutes to avoid generating a request on every cart change:

$cache_key = 'courier_rate_' . md5( serialize( $package ) );
$cached    = get_transient( $cache_key );
if ( $cached !== false ) {
    $this->add_rate( $cached );
    return;
}
// ... API request ...
set_transient( $cache_key, $rate_data, 30 * MINUTE_IN_SECONDS );

Sending Orders to the Delivery Service

After order confirmation, you need to create a shipment in the carrier's system. The woocommerce_order_status_processing hook is triggered when the order transitions to "Processing" status:

add_action( 'woocommerce_order_status_processing', function( int $order_id ) {
    $order = wc_get_order( $order_id );

    // Check that our shipping method is selected
    foreach ( $order->get_shipping_methods() as $shipping_item ) {
        if ( strpos( $shipping_item->get_method_id(), 'my_courier' ) === false ) {
            continue;
        }

        $result = courier_create_shipment( $order );
        if ( $result['tracking_number'] ) {
            $order->update_meta_data( '_courier_tracking_number', $result['tracking_number'] );
            $order->update_meta_data( '_courier_shipment_id', $result['shipment_id'] );
            $order->save();
            // Notify customer
            $order->add_order_note(
                'Shipment created. Tracking: ' . $result['tracking_number'],
                true // notify customer
            );
        }
    }
});

Tracking Number in Customer Account

Standard WooCommerce does not display the tracking number. Add it to the order confirmation email and the order page:

// In emails
add_action( 'woocommerce_email_order_meta', function( $order, $sent_to_admin ) {
    $tracking = $order->get_meta( '_courier_tracking_number' );
    if ( $tracking ) {
        echo '<p><strong>Tracking Number:</strong> ' . esc_html( $tracking ) . '</p>';
        echo '<p><a href="https://mycourier.ru/track/' . esc_attr( $tracking ) . '">Track Package</a></p>';
    }
}, 10, 2 );

// On order page in customer account
add_action( 'woocommerce_view_order', function( int $order_id ) {
    $order    = wc_get_order( $order_id );
    $tracking = $order->get_meta( '_courier_tracking_number' );
    if ( $tracking ) {
        echo '<p class="tracking-info">Tracking Number: <strong>' . esc_html( $tracking ) . '</strong></p>';
    }
});

Map Widget for Pickup Points

Many carriers provide a JavaScript widget for selecting a pickup point. It is embedded on the checkout page:

// Add a field to select a pickup point in the checkout form
add_action( 'woocommerce_after_shipping_rate', function( $method ) {
    if ( strpos( $method->id, 'my_courier_pickup' ) !== false ) {
        echo '<div id="pvz-selector" style="display:none;"></div>';
        echo '<input type="hidden" name="selected_pvz_id" id="selected_pvz_id">';
    }
}, 10, 1 );

// resources/js/courier-pvz.js
jQuery(document).on('change', 'input[name="shipping_method[0]"]', function () {
    if (this.value.includes('pickup')) {
        initPvzWidget({
            container: '#pvz-selector',
            apiKey: window.courierConfig.apiKey,
            city: jQuery('#billing_city').val(),
            onSelect: (pvz) => {
                jQuery('#selected_pvz_id').val(pvz.id);
                jQuery('#pvz-selector').after(
                    `<p class="pvz-address">Pickup Point: ${pvz.address}</p>`
                );
            }
        });
        jQuery('#pvz-selector').show();
    }
});

Automatic Status Updates

A webhook from the carrier or periodic cron polling updates the order status:

// wp-cron every 2 hours
add_action( 'courier_sync_tracking', function() {
    $orders = wc_get_orders([
        'meta_key'     => '_courier_tracking_number',
        'meta_compare' => 'EXISTS',
        'status'       => [ 'wc-processing', 'wc-shipped' ],
        'limit'        => 50,
    ]);

    foreach ( $orders as $order ) {
        $tracking = $order->get_meta( '_courier_tracking_number' );
        $status   = courier_api_get_status( $tracking );

        if ( $status === 'delivered' && $order->get_status() !== 'completed' ) {
            $order->update_status( 'completed', 'Delivered according to carrier data.' );
        }
    }
});

if ( ! wp_next_scheduled( 'courier_sync_tracking' ) ) {
    wp_schedule_event( time(), 'twohourly', 'courier_sync_tracking' );
}

Implementation Timeline

Integration with one carrier via ready-made plugin (SDEK, DHL, Nova Poshta): 1–2 days. Custom method with full cycle — calculation, shipment creation, tracking, webhook: 3–5 days. Adding a pickup point widget + email customization: plus 1–2 days. Integration of multiple carriers with a unified management interface: 1–2 weeks.