Adding tracking info to orders

This document provides an in-depth guide for developers looking to integrate and utilize Advanced Shipment Tracking (AST) and AST PRO within their shipping services or plugins. It outlines how to programmatically add shipment tracking information to WooCommerce order metadata and how to interact with the shipment tracking endpoint in the WooCommerce API.

Shipment Tracking order meta reference

When adding tracking information, you’ll need to include specific details. Below is the reference for the required and optional attributes:

ATTRIBUTE	TYPE	DESCRIPTION	PERMISSIONS
order_id	string	Unique identifier for order	Required
tracking_provider	string	Tracking provider name	Required
tracking_number	string	Tracking number	Required
date_shipped	date	Date when the package was shipped – default to the date/time that the tracking was added via the API	Optional
status_shipped	int	0 – do not change the order status, 1 – change order status to “Shipped” (completed), 2 – change the order status to custom status “Partially Shipped” (Defaults to 0).	Optional
sku	string	Line item SKU – Add tracking per item	Optional
qty	string	Line item quantity – Add tracking per item	Optional

Adding Shipment Tracking to Orders

To add tracking information to an order, utilize the ast_insert_tracking_number function provided by AST. Here’s how you can implement it:

Add Shipment Tracking for a Single Package

<?php
// Check if the AST PRO plugin is installed
if ( class_exists( 'AST_Pro_Actions' ) ) {

	// Set the order ID
	$order_id = '123';

	// Set the tracking provider name
	$tracking_provider = 'USPS';

	// Set the tracking number
	$tracking_number = '123123';

	// Set the date shipped
	$date_shipped = '2022-04-21';

	// Set the shipped status (1 = shipped)
	$status_shipped = 1;

	// Check if the "ast_insert_tracking_number" function exists
	if ( function_exists( 'ast_insert_tracking_number' ) ) {
		ast_insert_tracking_number( $order_id, $tracking_number, $tracking_provider, $date_shipped, $status_shipped );
	}
}

Add Shipment Tracking Per Item

For orders with multiple items or parcels, you can specify tracking information for each line item or quantity. Here’s an example of adding tracking for two different packages:

Add tracking for Package One:

<?php
// Check if AST PRO plugin is Installed
if ( class_exists( 'AST_Pro_Actions' ) ) {
	
	$order_id = '123';
	$tracking_provider = 'USPS';
	$tracking_number = '123456';
	$date_shipped = '2022-04-21';
	$status_shipped = 1;
	$sku = 't-shirt,blue-jeans';
  	$qty = '1,1';
	
	if ( function_exists( 'ast_insert_tracking_number' ) ) {
		ast_insert_tracking_number( $order_id, $tracking_number, $tracking_provider, $date_shipped, $status_shipped, $sku, $qty );
	}
}

Add tracking for Package Two:

<?php
// Check if AST PRO plugin is Installed
if ( class_exists( 'AST_Pro_Actions' ) ) {
	
	$order_id = '123';
	$tracking_provider = 'USPS';
	$tracking_number = '456789';
	$date_shipped = '2022-04-21';
	$status_shipped = 1;
	$sku = 't-shirt,blue-jeans';
  	$qty = '1,2';
	
	if ( function_exists( 'ast_insert_tracking_number' ) ) {
		ast_insert_tracking_number( $order_id, $tracking_number, $tracking_provider, $date_shipped, $status_shipped, $sku, $qty );
	}
}

Notes and Best Practices

• Check for Dependencies: Always check if AST or AST PRO classes and functions exist before attempting to use them to avoid errors.
• Testing: Thoroughly test any integration in a staging environment before deploying to a live store.
• Data Accuracy: Ensure the accuracy of all tracking details, particularly the tracking number and provider, to maintain customer trust and service integrity.

By following this guide, developers can effectively integrate AST’s robust tracking capabilities into their shipping workflows, enhancing the order fulfillment process and providing customers with timely and accurate tracking information.