Modify REST API Arguments When Adding Tracking (ast_api_create_item_arg)

Description

The ast_api_create_item_arg filter lets you change the arguments AST is about to save when a shipment tracking item is created through the REST API. It runs after the request has been read and just before the tracking is written to the order, so it’s the right place to fill in a missing value, override one, or apply a rule the sending system can’t.

It only affects tracking added through the REST API. Tracking added by hand, through CSV import, or with the helper functions doesn’t pass through this filter.

Parameters

Parameter	Type	Description
`$args`	`array`	The arguments about to be saved. Keys: `tracking_provider`, `custom_tracking_link`, `tracking_number`, `date_shipped`, `status_shipped` and `source`. Return this array, modified or not.
`$request`	`WP_REST_Request`	The full REST request. Use it to read anything that isn’t in `$args` — the order ID with `$request['order_id']`, or any extra field your integration sends, with `$request->get_param( 'your_field' )`.

The filter must return $args. Returning nothing, or something other than an array, breaks the request.

Example: always mark the order as shipped

Useful when the system posting the tracking doesn’t send status_shipped, but every tracking number it sends means the order has gone out.

add_filter( 'ast_api_create_item_arg', 'custom_ast_api_create_item_arg', 10, 2 );

function custom_ast_api_create_item_arg( $args, $request ) {

	// Mark the order as shipped (Completed).
	$args['status_shipped'] = 1;

	return $args;
}

Example: use the request to decide

Here the second argument does the work: the carrier name is mapped from a code the sending system uses, and the order is only marked shipped when that system says the shipment is complete.

add_filter( 'ast_api_create_item_arg', 'my_ast_api_args', 10, 2 );

function my_ast_api_args( $args, $request ) {

	// Map a carrier code sent by our warehouse to a carrier AST knows.
	$carrier_map = array(
		'UPSN' => 'UPS',
		'USPSP' => 'USPS',
	);

	if ( isset( $carrier_map[ $args['tracking_provider'] ] ) ) {
		$args['tracking_provider'] = $carrier_map[ $args['tracking_provider'] ];
	}

	// Only complete the order when the warehouse says it was a full shipment.
	$args['status_shipped'] = ( 'full' === $request->get_param( 'shipment_type' ) ) ? 1 : 2;

	return $args;
}

For what each argument means and which values status_shipped accepts, see the shipment tracking API reference.