Add shipment tracking to an order programmatically

Use wc_st_add_tracking_number() when a custom integration needs to attach shipment details after an order is fulfilled. The helper uses Shipment Tracking’s normal storage and formatting logic, so the result appears in the order editor, customer account, and supported order emails just like a tracking item entered by hand.

Example

↑ Back to top

The example checks that the helper is available, then adds a USPS tracking number to the order identified by $order_id. Because the fourth argument uses time(), the current Unix timestamp becomes the shipped date.

<?php
if ( function_exists( 'wc_st_add_tracking_number' ) ) {
    wc_st_add_tracking_number(
        $order_id,
        $tracking_number,
        'USPS',
        time()
    );
}

Function parameters

↑ Back to top

Parameter	Type	Purpose
$order_id	integer	The WooCommerce order ID that receives the tracking item.
$tracking_number	string	The carrier tracking number.
$provider	string	A provider label from Shipment Tracking, or the name of a custom provider.
$date_shipped	integer or null	An optional Unix timestamp. The current time is used when it is omitted.
$custom_url	string or false	An optional tracking URL for a provider that is not in the predefined list.

How provider matching works

↑ Back to top

Shipment Tracking normalizes the provider name and compares it with the current provider list. If it finds a match, it stores the predefined provider and builds the customer-facing tracking link from that provider’s URL. If it does not find a match, it treats the value as a custom provider and uses the optional fifth argument as the tracking URL.

For a custom carrier, pass the provider name as the third argument and a URL such as https://example.com/track/%1$s as the fifth argument. Shipment Tracking replaces %1$s with the tracking number when it formats the link.

Storage and verification

↑ Back to top

The helper writes through Shipment Tracking’s order APIs and is compatible with WooCommerce High-Performance Order Storage. Do not update the _wc_shipment_tracking_items meta key directly; doing so bypasses validation, identifier generation, and provider formatting.

• Open the order in WooCommerce > Orders and confirm the tracking item appears in the Shipment Tracking panel.
• Open the generated tracking link and confirm the carrier receives the expected tracking number.
• Trigger the customer email used by your workflow and confirm the provider, shipped date, and tracking link are present.

The helper does not return the created tracking item. Use the order editor or the Shipment Tracking REST API to read the saved result when your integration needs confirmation.