Group shipments
Track shipment groups help you to track orders that will take more than one shipment to fulfil. This page explains how to use metadata to group shipments together, how to view shipment groups in the Track UI, and how to present grouped shipments to your customers using Track's tracking pages.
Shipment groups overview
In Track, a shipment is a singly-tracked consignment of goods that are being shipped together from a single origin location to a single destination location. Shipment groups enable you to link related shipments together so that they can be tracked through the same page.
For example, suppose that a clothing retailer has received an order for a coat and a hat. At the time of order, the two items are physically located in two different warehouses. This means that they will need to be sent as two separate shipments, as all items on a shipment must share an origin location.
However, both items are still a single order from the customer's perspective. As such, it would be a better user experience to provide the customer with a single link that they could use to track both shipments, rather than two separate links.
By using shipment groups, you can link these two shipments together via a shared metadata property, enabling you to send tracking details for both as a single link. The page displayed by the link displays tracking information for all shipments tagged with that property, with a drop-down menu enabling customers to switch between all shipments in the group without navigating to a separate page.
Register grouped shipments
Shipment groups are based on metadata. If two shipments share an identical metadata property (that is, one that has both the same key and value), then Track considers them to be grouped together.
When grouping Track shipments, the metadata key is the grouping (that is, the category by which shipments are grouped together) and the metadata value is effectively the name of the group itself. For example, an organisation grouping shipments by order number might use orderID (or similar) as a metadata key and their own order number as the value.
The following example shows a request to register four simple shipments at once. The shipments all have a metadata key named group_name denoting the group they are in. The first two shipments belong to example_group1, and the second two below to example_group2.
{
"shipments": [
{
"tracking_references": [
"shipment1"
],
"metadata": [
{
"key": "group_id",
"value": "example_group1",
"type": "String"
}
]
},
{
"tracking_references": [
"shipment2"
],
"metadata": [
{
"key": "group_id",
"value": "example_group1",
"type": "String"
}
]
},
{
"tracking_references": [
"shipment3"
],
"metadata": [
{
"key": "group_id",
"value": "example_group2",
"type": "String"
}
]
},
{
"tracking_references": [
"shipment4"
],
"metadata": [
{
"key": "group_id",
"value": "example_group2",
"type": "String"
}
]
}
]
}
To add a pre-existing shipment to a group, use the Update Shipment endpoint to add the relevant metadata property to the shipment. Note that Track's Update Shipment endpoint requires you to pass an entire new shipment object, which overwrites the existing shipment resource. As such, you would need to pass all of the shipment's current details as well as the metadata property when adding a shipment to a group.
Note
- For more information on registering Track shipments, see the Registering Shipments page.
- For more information on updating Track shipments, see the Updating Shipments page.
Track grouped shipments
Your customers can view tracking information for any shipment group by visiting https://react.sorted.com/tracking/[page_title]?customer_id=[customer_id_here]&metadata_key=[metadata_key_here]&metadata_value=[metadata_value_here], where [page_title] is the title of your tracking page, [customer_id_here] is your Track customer ID, [metadata_key_here] is the relevant grouping key and [metadata_value_here] is the value that you grouped the shipments together on.
As an example, suppose that a customer with a customer_id of cs_1234567890 created a tracking page called examplePage and wanted to use it to let a customer view the first two shipments from the code sample given in the previous section. To do so, they would share the following link: https://react.sorted.com/tracking/examplePage?customer_id=cs_1234567890&metadata_key=group_id&metadata_value=example_group1
Shipment group tracking pages have a drop-down picker on the tracking page that enables the customer to select which shipment's tracking information they want to view.
For non-autoloading shipment groupings Track only displays the drop-down shipment picker and grouping information if you access the shipment via the shipment group link (that is, you use the shared metadata key and value to identify the shipments to be displayed). You can still use other valid tracking page link formats to view a shipment that is in a non-autoloading grouping (such as shipment_id or tracking_reference), but Track does not display links to other shipments in the group in this case.
However, for shipments in an auto-loading shipment grouping, Track always displays links to other shipments in the grouping, even if you track the individual shipments by their shipment_id or tracking_reference.
Note
- For more information on using auto-loading groupings, see the Auto-Loading Shipments section.
- For more information on creating and distributing Track tracking pages, see the Tracking Pages page.
Create shipment groupings
The Configure Shipment Groupings UI page enables you to specify a name for up to three of the metadata keys that you use for your shipment groupings.
For example, you might group shipments by a key called orderID. The Configure Shipment Groupings page enables you to specify a name such as Order Reference (or similar) for that grouping, which Track would then display on the group tracking page instead of the orderID key name.
To name a shipment group:
Select Settings > Shipment groupings.
Enter the Metakey of the group you want to name.
Enter the Name you want to give to the group.
Use the AutoLoad toggle to select whether you want Track to automatically search for grouped shipments. For more information on auto-loading shipments, see the Auto-Loading Shipments section.
Note
You can only specify one of your group keys as an autoload key. If you select the AutoLoad toggle for a particular key, then PRO deselectes it for any other keys.
Add up to two more keys and names, if required.
Click Save to save your changes.
To edit your existing group names, click the Edit button.
Auto-load shipments
If you set a key to auto-load, then Track automatically performs a lookup to obtain further shipments that have the same key and value when it receives a shipment that contains the specified key.
To put it another way, Track actively groups shipments with an auto-loading metadata key together. This means that when you track an individual shipment with an auto-load key through Track's tracking pages (for example, by shipment_id, tracking_reference, or custom_reference), the system is able to see that the shipment has related shipments and can display a link to their details on the tracking page.
This is different to regular "passive" shipment groupings, in which Track does not actively search for additional shipments and does not display grouped shipment details on the tracking page if you track an individual shipment. For non-autoloading groupings, the only way to see grouped shipments on the Track tracking page is by searching for them using shared metadata key / value parameters, as explained in the Tracking Grouped Shipments section.
Auto-loading shipments example
As an example, you might specify an auto-load key for multi-package shipments originating from PRO. When Track receives shipments from PRO, it registers one shipment per PRO package. By using an auto-loading key, Track can automatically obtain, register, and group all of the packages in a PRO shipment as soon as it receives the first package.
One way to do this would be to append PRO's shipment_id property to each shipment as a metadata key/value at the point of registration in Track, as all packages from a PRO shipment would share a common PRO shipment_id.
The code sample below shows two simplified Register Shipment requests with a PRO shipment_id appended as metadata via a key called PRO_Shipment_Id. Note that these shipments have the same metadata key but individual tracking references.
{
"shipments": [
{
"tracking_references": [
"AutoLoadExamples1"
],
"metadata": [
{
"key": "PRO_Shipment_Id",
"value": "sp_01114749695851729329506736537600",
"type": "string"
}
]
}
]
}
You would then need to set that metadata key as an auto-loading grouping in the Track UI.
Now, if you track one of the shipments by its tracking_reference in a Track tracking page, then Track automatically recognises that the shipment has a related shipment and offers a drop-down picker at the top of the page to enable you to switch between shipments.
Search for grouped shipments
You can search for grouped shipments using your named shipment groupings (that is, those shipments that are grouped using the metadata keys configured on the Configure Shipment Groupings UI page) via the search bar in the Track UI. To do so:
- From any page of the Track UI, click the drop-down menu on the search bar and select the name of the grouping (i.e. the metadata key) you want to search by
- Enter the group name (i.e. the metadata value) and press Enter to display tabbed details of all the shipments in the group.
Track only displays tabs if you search for shipments by their grouping. If you were to search for the shipment in the example above by its tracking reference, for example, then Track would only display that shipment's details.
Next steps
Read on for more info: