Create a custom-provider tracking item with the REST API

Create a custom-provider tracking item when the carrier is not returned by the Shipment Tracking providers endpoint. Send the request to the same order collection used for predefined providers, but omit tracking_provider and provide the two custom-provider fields instead.

Request body

↑ Back to top

Send this JSON body with an authenticated POST request to /wp-json/wc-shipment-tracking/v3/orders/<order_id>/shipment-trackings.

{
  "custom_tracking_provider": "Example Courier",
  "custom_tracking_link": "https://example.com/track/%1$s",
  "tracking_number": "12345678",
  "date_shipped": "2026-07-10"
}

Custom-provider fields

↑ Back to top

Field	Required	Description
custom_tracking_provider	Yes	The carrier name shown to store staff and customers.
custom_tracking_link	Yes	The full carrier URL used to build the tracking link.
tracking_number	Yes	The carrier tracking number.
date_shipped	No	The shipped date in YYYY-MM-DD format.

Build the tracking URL

↑ Back to top

Use %1$s where the carrier expects the tracking number. Shipment Tracking replaces that placeholder when it formats the link. Provider URL formats can also use %2$s for the normalized destination postcode and %3$s for the destination country code when the carrier requires those values.

Do not send tracking_provider in the same request. That field identifies a predefined provider and can cause the API to ignore the custom-provider intent.

Expected response

↑ Back to top

A successful request returns HTTP 201 Created. The response uses the normal tracking-item fields: the custom carrier name appears as tracking_provider, the expanded URL appears as tracking_link, and the API generates a read-only tracking_id.

Verify a custom integration

↑ Back to top

• Create a test tracking item on a staging order.
• Open the returned tracking_link and confirm the tracking number is in the expected position.
• Check the order editor, customer account, and completed-order email for the custom carrier name.
• Delete the test item with its returned tracking_id when validation is complete.