Register shipments with Track
Track can only work with the shipments you have registered. This page explains how to register shipment details by API, SFTP, and email, and how to get the most out of Track by registering additional shipment information.
Register shipments by API
You can give Track details of the shipments you want to register using the Register Shipments endpoint. Like all Track APIs, you'll need to generate an API key before you can use the API package.
Generate an API key
To generate a new API key:
Log into your Track dashboard and select Settings > API Keys > Create New.
Enter an identifying name for the key, then click Create.
Copy your API key and save it somewhere safe.
Caution
It's really important that you make a note of your API key, as you can't come back and view it later.
You can use your key by adding an x-api-key
header to any requests you make. This lets Track know who you are, and makes sure only authorised people and applications can get at your data. The next section gives an example of a request header with an API key in place.
The Register Shipments API endpoint allows you to send shipment details to Track. A new shipment record is then recorded on the system.
Send the request
To register a shipment, send a POST
request to https://react-api.sorted.com/react/shipments
. There are lots of properties you can send when you register, but only the (carrier) tracking_references
array is mandatory. Track treats the value of the tracking_references
array as the shipment's primary reference.
Currently, you can only provide one tracking reference in the tracking_references
array, although multiple references may be supported in a future enhancement to Track. If you add additional references, Track returns an error. You can add additional references for the shipment - including your own internal reference numbers - in the custom_references
array.
Note
As with other Track APIs, you'll need to include JSON Content-Type
and Accept
headers and a valid API key in order to use the Register Shipments endpoint. You can get an API key from the Settings > API Keys page of the Track UI.
For more information on obtaining an API key, see the Getting an API Key section of the Quick Start guide.
Examples
This example shows the body of a simple Register Shipments request, in which the user has not provided any information other than a carrier tracking reference:
{
"shipments": [{
"tracking_references": ["TRACKING-DEMO-REFERENCE"]
}]
}
The following example shows two simple shipments registered in a single API call:
{
"shipments": [{
"tracking_references": ["MULTI-SHIPMENT-1"]
},
{
"tracking_references": ["MULTI-SHIPMENT-2"]
}]
}
Register shipments response
When Track receives the request, it creates a new shipment record and returns a 201 Created response. The body of this response contains the shipment's id
- a Track-generated identifier for the shipment that can be used to recall data throughout Track's APIs.
{
"id": "sp_TRACKING-DEMO-ID",
"message": "Shipment record 'sp_TRACKING-DEMO-ID' with tracking reference ["TRACKING-DEMO-REFERENCE"] registered successfully.",
"tracking_references": [
"TRACKING-DEMO-REFERENCE"
],
"_links": [
{
"href": "https://react-api.sorted.com/react/shipments/sp_TRACKING-DEMO-ID",
"rel": "self"
}
]
}
And that's it! Track will look out for the tracking reference you provided in the carrier data it receives from its carrier connectors, and will update the shipment's information as new events come in. You can use the carrier tracking reference or {id}
to get updates on the shipment using Track's APIs. The newly-registered shipment can also trigger any webhooks you have configured.
Track assigns an initial shipment state of Registered to all newly-registered shipments. For a full list of Track shipment states, see the Shipment States page.
Register shipments by SFTP
The Register Shipments API is ideal if you need to register shipments individually or in small groups. However, if you have a large number of shipments to register you might find it more practical to use Track's SFTP upload facility.
Prerequisites
In order to upload to the Track SFTP service, you will need a Track SFTP account and private key. For more information on obtaining these details, see Setting up SFTP Accounts.
Note
Track private keys are provided in PPK format. If your SFTP client does not support PPK keys then you will need to convert the key provided into the appropriate format. Consult your SFTP client's documentation for further information.
The shipment data you want to upload should be stored in either a JSON or CSV file. The shipment data in this file should be structured in the same way as the data accepted by the Register Shipments endpoint, with one exception: when uploading a CSV file, the property that accepts tracking references should be called tracking_reference
, rather than tracking_references
(plural) as is the case when uploading a JSON file or making a direct request to the Register Shipments endpoint.
Note
- For more information on representing shipment data in CSV format, see the CSV File Structure section.
- For more information on the data structure of the Register Shipments requests, see the API Reference.
This example shows the body of a simple CSV upload, in which the user has registered the carrier tracking references of five shipments, along with the carriers and carrier services used for those shipments:
"tracking_reference","carrier","carrier_service"
"TRACKING-DEMO-REFERENCE1","A Carrier","A Carrier Service"
"TRACKING-DEMO-REFERENCE2","Another Carrier","Another Carrier Service"
"TRACKING-DEMO-REFERENCE3","A Carrier","A Carrier Service"
"TRACKING-DEMO-REFERENCE4","Another Carrier","Another Carrier Service"
"TRACKING-DEMO-REFERENCE5","A Carrier","A Carrier Service"
Uploading
To upload shipments to Track via SFTP:
- Save the private key to the machine you will be uploading the files from.
- From that machine, open an SFTP client and start a new SFTP session. You'll need the following login details:
- File Protocol: SFTP
- Host Name: sftp://react-sftp.sorted.com
- Port Number: 22
- Your Track SFTP username and passphrase.
- Upload the shipment file as per your SFTP client's instructions.
SFTP upload results
Once you have uploaded the file, Track processes the shipment data sent. The system takes each individual shipment object in the file and attempts to register is using the data supplied. As the shipments are processed, Track writes the result of each registration attempt to a JSON file.
Once Track has attempted to register every shipment in the file, the original file is deleted and the results file is uploaded to your SFTP directory. The completed file gives a full breakdown of how many shipments were successfully registered, how many could not be registered, and any errors that were returned.
The results file has two arrays of errors:
validation_errors
: Generated if the shipment could not be registered due to its data failing Track's validation checks.registration_errors
: Generated if the shipment passed Track's validation but still could not be registered. (i.e. Track's response to the shipment had a status code of something other than 201 Created or 400 Bad Request.)
Example SFTP result files
- The file contained a single shipment, which was successfully uploaded.
{
"result_message":"Results for processing file shipments-1-valid.json",
"original_filename":"shipments-1-valid.json",
"total_lines":1,
"successful_shipment_registrations":1,
"unsucessful_shipment_registrations":0,
"validation_errors":[
],
"registration_errors":[
],
"error_message":null,
"process_start":"2018-11-13T10:49:40.7613486+00:00",
"process_end":"2018-11-13T10:49:41.0246588+00:00"
}
- The file contained four shipments. One was registered successfully, one failed due to a validation error (in this case, duplicate
tracking_reference
values), and two failed due to errors during the registration process.
{
"result_message":"Results for processing file EXAMPLE-FILENAME",
"original_filename":"EXAMPLE-FILENAME",
"total_lines":4,
"successful_shipment_registrations":1,
"unsucessful_shipment_registrations":3,
"validation_errors":
[
{
"tracking_reference":"trackRef2",
"message":"1 or more validation error(s) occurred",
"error_messages":
[
{
"property":"shipments._tracking_reference",
"message":"Only one Tracking Reference should be provided"
}
]
}
],
"registration_errors":
[
{
"tracking_reference":"trackRef3",
"error_message":"We were unable to register this shipment status was Ambiguous"
},
{
"tracking_reference":"trackRef4",
"error_message":"We could not register this shipment as an error occured"
}
],
"error_message":null,
"process_start":"2018-11-08T11:01:41.989049+00:00",
"process_end":"2018-11-08T11:01:42.0460531+00:00"
}
- The file could not be parsed at all, most likely due to an invalid structure:
{
"result_message":"There was a problem processing the file shipments-1-valid.csv",
"original_filename":"shipments-1-valid.csv",
"total_lines":0,
"successful_shipment_registrations":0,
"unsucessful_shipment_registrations":0,
"validation_errors":[
],
"registration_errors":[
],
"error_message":"Error parsing header from location cu-17583829045847028000-sorted-copy/shipments-1-valid-636777032692975629.csv for customer cu_17583829045847028000",
"process_start":"2018-11-13T10:54:30.7505662+00:00",
"process_end":"2018-11-13T10:54:34.2508169+00:00"
}
You can upload multiple shipment files at the same time as long as the files have different names. If you attempt to upload two shipment files with the same name at the same time, or upload a file before another file of the same name has finished processing, then Track will only process one file.
However, Track will process files that have the same name as a file that has been previously uploaded, as long as it has already finished processing the first file.
Register shipments by email
Track's Register by email functionality enables you to register shipments without having to make any API call or uploads via SFTP. Registering shipments by email allows less-technical users, and those who are unable to make API calls or use SFTP, to register their shipments for tracking.
Note
This is an on-demand feature and not openly available through the Track user interface. If you are interested in registering your shipments by email, please contact your Track account manager and we'll guide you through the process.
Assign a carrier on registration
You can specify a shipment's carrier at the point of registration using the carrier_reference
property. carrier_reference
is not a mandatory property, but Sorted recommends that you provide carrier details where possible. If you provide a carrier_reference
, then Track can instantly link your shipment to the correct carrier and begin receiving tracking information sooner than it would otherwise be able to.
Where provided, the carrier_reference
property must contain a carrier's unique Track ID. If you provide any other value in a carrier_reference
property, then Track returns a 400 - Bad Request
validation error.
Carrier reference list
Each Track carrier has its own identifier within the system. The table below shows the unique IDs for some common Track carriers:
Name | Reference |
---|---|
Evri | 26432E9D-73CB-44EF-ABB5-164088A93ABE |
ArrowXL | E2B36840-4032-49A9-981F-44A7097AFDFE |
DHL Express | 532D2CE2-79DC-4E24-840C-C75A37CF02DC |
Asda toyou | F1535C2B-10C8-4D43-9976-11848DEA013D |
P2P TRAKPAK | 19E6AEA5-278D-476A-8576-D4DBC3C2DD94 |
Yodel | 77B7A461-E3B3-4B2C-9B90-2F42FE4BFC25 |
Royal Mail | B5096289-91F4-49E2-9B8E-018964877C5E |
DHL Parcel UK | FFC0644D-B570-413F-A6B8-CC4F20B491A0 |
DPD UK | D1FB3EA4-7AA4-4D50-B1F3-9AF69A582038 |
Parcelforce | 57E2A30D-368B-4F42-9E20-5F6B3A5115BC |
Lineten | 00e32b3c-87d6-4fe3-ad79-d21133469eae |
TNT | 385a136e-8a1a-405f-b6a8-35bd7e2c7bd8 |
FedEx | 5FE878CB-32BF-4221-B2BF-45C89739825D |
DPD Germany | 0b664aa8-da77-4f97-ab44-0749acbe8ccb |
DHL Paket | 6A7657AE-EB7E-459F-B3A8-1A6C10D8B205 |
UPS | 121DB19E-8356-428A-BB6C-4A53DA8C0389 |
Jersey Post | 911a07c3-3e48-4875-bd07-cf1b37465c33 |
DX Freight | e48028d6-35b7-48a8-a542-4c7edb4dbee1 |
Panther | e75a59d7-205e-b1a8-b8ad-e1786de37e21 |
APG | 50d10273-d750-4cdc-8db9-c70bd9099b69 |
Asendia | 0F7FD87E-3F95-4203-A397-11F81DC2C4DA |
Fastway | 2539E909-6C0B-4D70-8C3E-2CE4CD16CA4C |
Landmark Global | e9d32156-bac3-4f15-b658-ae6e460212d0 |
Collectplus | B3109373-EF07-4A2E-B5FA-89283BE33691 |
Track is continually being updated with new carriers, and as such the table above should not be considered an exhaustive list. You can look up a carrier reference in the Track UI via the Carrier Connectors page. To do so:
Log in to the Track UI and select the Settings > Carrier Connectors page.
Click the Edit button on the tile of the carrier you want to look up to display the Edit Configuration page for that carrier.
Scroll to the bottom of the page. The carrier's reference is displayed in the Carrier Reference field.
Register extra shipment information
Registering shipments with a carrier tracking reference alone is enough to get started with Track's tracking features, but Track works best when you give it more shipment data to use.
Note
This section gives an overview of the extra information you can provide when registering a shipment. For full details of all the properties accepted by the Register Shipments endpoint, and the structure you should use when making the request, see the API Reference.
The Register Shipments endpoint enables you to register:
References - As well as the mandatory carrier tracking reference array, you can also register additional
custom_references
for the shipment. Custom references do not need to be unique (i.e. you can register the same custom reference for multiple shipments if required), but we would recommend that you use unique custom references where possible to help you retrieve shipment data easily.Tags - Tags enable you to associate related shipments (such as all shipments of a particular product, or all shipments of products on special offer) with each other. You can also use tags to select the shipments that go into your shipment filters.
Note
You can add up to 20 tags to a shipment, and each tag must be between three and 30 characters long. If you attempt to add more than 20 tags then only the first 20 are stored. Tags are not case-sensitive, and you cannot add duplicate tags within the same shipment.
Dates - The
order_date
,shipped_date
andpromised_date
properties enable you to record when a shipment was ordered and shipped, and when the customer was told that it would be delivered.Addresses - The
addresses
array enables you to record multiple addresses against a single shipment. You can record origin, destination, return, billing, delivery hub, and alternative delivery addresses.Consumer Info - The
consumer
array enables you to record your customer's contact details.Shipment Types - The
shipment_type
property enables you to record whether a shipment is a delivery, return, pick up, drop off, combined drop off / pick up, or return drop off.Custom Metadata - You can specify custom metadata properties using the
metadata
array. Each property requires akey
,value
, and datatype
.Note
Adding metadata enables you to group shipments together so that they can be tracked from the same page, and to use custom properties to enrich the notifications that you send to your customers.
- For more information on grouping shipments, see the Grouping Shipments page.
- For more information on configuring notifications, see the Configuring Notifications page.
Simulated Tracking - Simulated tracking is a means of generating dummy tracking events for testing or demonstration purposes. For a user guide on working with simulated tracking, see the Using Simulated Tracking.
Why register additional information?
If you only provide a carrier reference when registering then Track is limited to reporting back on what the carrier says about that particular shipment. Providing additional information enables Track to do the following:
Offer flexible retrieval options - Some of Track's API endpoints enable you to retrieve shipments, events or tracking events based on criteria other than Track
{id}
numbers or carrier references. For example, you can use the Get Shipments endpoint to retrieve shipment details based on custom references, such as your own internal order number for the shipment in question. However, Track can only return a shipment via custom reference if you've previously supplied a custom reference for that shipment.Also, adding
tags
to your shipments enables you to fine-tune the list of shipments that you receive webhooks for. For example, you might have a "Special-Offer" tag that you would apply to shipments of products in a particular sale. You could then set up a shipment filter including only those shipments with your "Special-Offer" tag. This shipment filter could in turn be used to power a webhook sending branded offer-specific delivery communications to customers who have purchased products in the sale.Provide rich webhook and API results - Adding additional shipment data enables Track's webhooks and APIs to return richer results. When triggered, webhooks send a
ShipmentEvents
object to you. As well as event details, this object contains aShipmentSummary
- an overview of the data Track holds on the shipment in question. The more information Track holds on the shipment, the more useful thisShipmentSummary
will be.Offer enhanced UI functionality - You will need to provide additional shipment information in order to use the Dashboard's data filters. You can filter Dashboard data by carrier, state, country of origin, destination country, important dates, and shipment type, but only for those shipments that have the relevant information recorded. In addition, shipments will only show up on the States dashboard map if they have an address with an
address_type
of Origin.Use Calculated Properties - If you add a
promised_date
to your shipments then Track can automatically mark shipments as late where required. Likewise, adding acountry_iso_code
for both destination and origin addresses enables Track to performmay_be_missing
calculations, in which it marks a shipment as potentially missing if that shipment is not updated for a set period of time.
Example detailed JSON request
The following example shows a shipment registered with additional detail on tags, dates, consumer information, and custom tracking references. For full details of all the properties accepted by the Register Shipments endpoint, see the API Reference.
{
"shipments": [
{
"tags": [
"Special_Offer",
"BRAND_X",
"DTWD"
],
"tracking_references": [
"TRK098JKH54ADD"
],
"custom_references": [
"fb60aa0f3e2d4247b8e01c659d621b8e",
"HB-003"
],
"carrier_reference": "F1535C2B-10C8-4D43-9976-11848DEA013D",
"shipped_date": "2018-11-12T00:00:00+00:00",
"order_date": "2018-11-12T00:00:00+00:00",
"promised_date": {
"start": "2018-11-19T09:00:00+00:00",
"end": "2018-11-19T12:00:00+00:00"
},
"addresses": [
{
"address_type": "origin",
"reference": "555d66aa24864fbdae58d8c13afb51e0"
},
{
"address_type": "destination",
"postal_code": "N2 3FD",
"country_iso_code": "GB"
}
],
"consumer": {
"reference": "JYvkxEdlxE2Xeiv2W5W8TA",
"email": "frankie_smith100@outlook.com",
"phone": "+44161559844",
"mobile_phone": "+447395654853",
"first_name": "Francesca",
"last_name": "Smith",
"middle_name": "Helena",
"title": "Ms"
},
"metadata": [
{
"key": "warehouse_identifier",
"value": "WHF-0099282323A6",
"type": "String"
},
{
"key": "refundable",
"value": "false",
"type": "Boolean"
},
{
"key": "expiration_date",
"value": "2025-10-03T00:00",
"type": "DateTime"
}
],
"retailer": "Smith & Gold GmbH",
"shipment_type": "delivery"
}
]
}
This example has values specified in the custom_references
array. These could be internal order numbers, customer references, or anything else you choose. Now that Track has been given this data, you could use these references to retrieve information via the Get Shipment Events and Get Shipments endpoints.
In this case, the metadata array has been used to add a warehouse SKU, indicate whether the shipment is refundable, and provide an expiration data for the shipment contents.
Track validates all Register Shipment requests in line with the rules set out in the API reference. Where an uploaded shipment does not meet this validation, Track returns an error.
CSV file structure
Adding additional information when registering shipments via SFTP may require you to represent complex objects in your CSV. CSV objects are represented as [object name]/[property name]
. Objects can be nested within objects using the syntax [Parent object name]/[Child object name]/[property name]
.
Where an object can take multiple records (such as the addresses
object, which can be used to record multiple addresses against a single shipment), a record number is added directly after each instance of the object in question. Record numbers should start from 0.
For example, multiple addresses
could be represented as:
""addresses/0/address_type","addresses/0/postal_code","addresses/0/lat_long/latitude","addresses/0/lat_long/longitude","addresses/1/address_type","addresses/1/postal_code","addresses/1/lat_long/latitude","addresses/1/lat_long/longitude"
"origin","ST4 4EG","123","456","destination","M33 5EW","789","012"
Examples
The following examples represent the same data structure:
{
"shipments": [
{
"tracking_references": [
"TRK098JKH54ADD"
],
"custom_references": [
"29ab72c406a94efb8e0797deb309ee4d",
"HB-003"
],
"carrier_reference": "F1535C2B-10C8-4D43-9976-11848DEA013D",
"addresses": [
{
"address_type": "origin",
"postal_code": "ST4 4EG",
"lat_long": {
"latitude": "80",
"longitude": "179"
},
},
{
"address_type": "destination",
"postal_code": "N2 3FD",
"country_iso_code": "GB"
}
],
}
]
}
Note
By default, shipments are archived 35 days after registration. Archived shipments are no longer available on the Track application.