Register shipments

You must register your shipments so they can be displayed on your Track account. This page explains how to register your shipment details using API, SFTP or email.

Visit guide sections below if you want to know how to register your shipments by:

• Register by API
• Register by SFTP
• Register by email

Additionally, it’s important to consider what data you want to include in your shipment registration.

Find out below how including additional data properties in your shipment registration can enhance your delivery Tracking performance.

Why you should register as much shipment data as you can link

If you only provide the mandatory carrier tracking_reference when registering your shipments, then Track is limited to reporting on what the carrier provides on that particular shipment. This can limit tracking visibility as Track is relying on the carrier to provide the updates.

Track will provide you much more information if you include additional data fields when registering your shipments. Doing so allows Track to provide more enhanced shipment tracking through calculations and visibility.

When registering a shipment, you must include the basic data that makes up the shipment. This information can include, but is not limited to:

• Tracking reference - this is a mandatory field
• Address details - optional
• Consumer details - optional
• Carrier - optional; and
• Carrier service - optional

For full details of all the properties accepted by the Register Shipments endpoint, see our API Reference.

To view an example of what a shipment registration can look like, scroll down to view an example JSON POST request.

Below are a list of fields that you can include in your shipment registrations to enhance your Track platform:

Tags link

You can tag your shipments to associate related shipments together.

You may want to tag your shipment(s) for a variety of reasons, such as:

• To differentiate shipments if your company has more than one brand.
• To highlight a set of shipments of a particular product.
• If you want products on special offer to be highlighted.

You can also use tags in your shipment filters to trigger webhooks and email notifications to your customers. For more information view our shipment filters guide.

The example below uses multiple tags in the shipment registration.

  "tags": [
  "Brand_B",
  "Alcohol",
  "Summer_Discount"
]
  

You can add up to 20 tags to a shipment, and each tag must be between 3 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 link

The order_date, shipped_date and promised_date properties are useful to record when a shipment was ordered and shipped, and when the customer was told that it would be delivered.

Enhance your shipment monitoring by including a promised_date in your registered shipments. Track can then automatically mark shipments as late if the time exceeds the particular date. This can be viewed in the calculated events dashboard.

Example json date properties below:

  "shipped_date": "2023-05-25T00:00:00+00:00",
"order_date": "2023-05-25T00:00:00+00:00",
"promised_date": {
  "start": "2023-06-01T09:00:00+00:00",
  "end": "2023-06-01T12:00:00+00:00"
}
  

Addresses link

The addresses array records multiple addresses against a single shipment.

If you include an address the address_type is a mandatory field here.

You can record the address_type as:

• origin
• destination
• return
• billing
• delivery hub; and
• alternative (delivery addresses)

Your shipments will only show up on the states dashboard overview if they have an address with an address_type of origin.

Country ISO code link

Adding a country_iso_code for both origin and destination addresses allows Track to perform may_be_missing calculations, in which it marks a shipment as potentially missing if that shipment is not updated for a set period of time. This can monitored in the calculated events dashboard.

If you include this field, your shipments will also be viewable from the map overview on the shipments dashboard.

Track supports the use of the ‘alpha 2 codes’ when defining country ISO codes. For a list of all country ISO codes, please visit the wikipedia article or the IBAN country codes list.

  "addresses": [
  {
    "address_type": "origin",
    "reference": "eeb6e486c17a45ba81374d6075bec24a"
    "country_iso_code": "IM",
    "postal_code": "IM1 1AE"
  },
  {
    "address_type": "destination",
    "postal_code": "DN5 9BB",
    "country_iso_code": "GB"
  }
]
  

Carrier link

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:

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 user interface in the Carrier Connectors page.

To do so:

1. Log in to Track and select Settings > Carrier Connectors page.

2. Select the Edit button on the tile of the carrier you want to look up to display the Edit Configuration page for that carrier.

   

3. Scroll to the bottom of the page. The carrier’s reference is displayed in the Carrier Reference field.

   

References link

As well as the mandatory carrier tracking_references array, you can also register additional custom_references for your shipment(s).

Custom references do not need to be unique , you can register the same custom reference for multiple shipments if you wish, but we recommend that you use unique custom references where possible to help you retrieve shipment data easily. These custom references can be searched and queried on, if you wish to locate your shipments that way.

Additional fields to include link

Furthermore, there are many additional properties you should think about including in your shipment registrations which can provide even more information for Track to work with.

View the list below, however, to view all properties see our register shipments API reference.

Consumer Info
The consumer array allows you to record your customer’s contact details.

Shipment Type
The shipment_type property allows 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 a key, value, and data type.

Including metadata allows you to group shipments together so that they can be tracked from the same page and can also be used to send notifications to customers who have a particular metadata key included in their shipment.

• For more information on grouping shipments, see our guide on how to group shipments.
• For more information on configuring notifications, see our set up notifications page.

Simulated Tracking
Simulated tracking is a means of generating dummy tracking events for testing or demonstration purposes. See the using simulated tracking. guide for more information.

Register shipment methods link

With an idea on what data you want to send with your shipment registrations, you can choose the the method of how you want to send that data into Track, whether it’s using API, SFTP or email.

Register shipments by API link

You can give Track the 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.

For more information, visit the Track API user guide.

Generate an API key link

To generate a new API key:

1. Log into Track and select Settings > API Keys > Create New.

   

2. Enter an identifying name for the key, then hit Create.

   

3. Copy your API key and save it somewhere safe.

   

The register shipments API endpoint allows you to send shipment details to Track. A new shipment record is then recorded on the system. View the example below for how this can be structured in a JSON body.

Example register shipments request link

The following JSON 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 <a href=../../../../track-api-reference/#tag/Shipments/paths/1react1shipments/post" target="_blank">API reference.

Detailed Register Shipment Request link

  {
  "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. If you send this data with your requests, you could use these references to retrieve information via the Get Shipment Events and Get Shipments endpoints.

In this sample, the metadata array has been used to add a warehouse SKU, state if 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.

Send the request link

To register a shipment, send a POST request to https://react-api.sorted.com/react/shipments. There are many properties you can send when you register, but only the carrier tracking_references array is a mandatory field. Track uses the value of the tracking_references array as the shipment’s primary reference.

Examples

This example shows the body of a simple register shipments request with the absolute minimal data of tracking_references provided, in which the user has not applied any additional data in the registration:

Register single shipment link

  {
  "shipments": [{
    "tracking_references": ["TRACKING-DEMO-REFERENCE"]
  }]
}
  

The following example shows two simple shipments registered in a single API request:

Register multiple shipments link

  {
  "shipments": [{
    "tracking_references": ["MULTI-SHIPMENT-1"]
  },
  {
    "tracking_references": ["MULTI-SHIPMENT-2"]
  }]
}
  

Register shipments response link

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.

Successful register shipment response link

  {
  "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"
    }
  ]
}
  

Following a successful shipment registration, 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 set up.

Track assigns an initial shipment state of Dispatched to all newly-registered shipments. For a full list of Track shipment states, see the shipment states page.

Register shipments by SFTP link

If you cannot register your shipments using our API, you may find it more suitable to use Track’s SFTP functionality to bulk register your shipments through a file upload instead.

Doing so means you will register your shipment data in a CSV or JSON file and use an SFTP client to transfer the files to your Track platform.

Follow the steps below to kick start this process.

Get your SFTP details link

To upload to the Track SFTP server, you will first need to create a Track SFTP account and download a private key.

To get these details, see our guide on setting up SFTP accounts.

Once done, make a note of your username, password and the location of the private key (PPK file) you downloaded, these will be used to connect to the Track server later.

You can now create the files that will register your shipment data. See the section below on types of files you can upload.

File format link

Track SFTP requires your shipment data in either a CSV or JSON file to be uploaded.

JSON link

JSON files can be uploaded using the same structure as the Register Shipments API endpoint. A sample of this data is provided above in the example register shipments request.

You can use all properties stated in the Register Shipment API reference.

This data must be saved in a .json file. Once your data is ready, you can upload your file(s), covered in the section below.

CSV link

You can also register your shipment(s) by uploading them in a CSV file. The same shipment registration properties can be used that are stated in the register shipment API reference however, the data properties need to be separated with a forward slash (/) in the header row of the CSV and the shipment data to be specified in the rows below.

CSV objects are represented in the header as the [object name]. Objects can be nested within objects using the syntax [Parent object name]/[Child object name] for example consumer/email, promised_date/start and promised_date/end. The value of the property must then be placed in the cell directly below the header of the CSV.

When an object can use multiple records, such as the addresses object, which can nest multiple addresses in a single shipment, an index number must be added after each instance. These index numbers start counting from 0, this is explained in the example below.

Here is a sample of how the shipment data can be structured.

CSV link

  "tracking_reference","custom_references/0","custom_references/1","carrier_reference","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/country_iso_code"
"TRK098JKH54ADD","29ab72c406a94efb8e0797deb309ee4d","HB-003","F1535C2B-10C8-4D43-9976-11848DEA013D","origin","ST4 4EG","123","456","destination","N2 3FD","GB"
  

Sample CSV template download link

For a sample data template of a CSV file with shipment data, download the file here to see how it looks.

Upload your file(s) link

To upload your shipment files, the following steps are carried out externally to Track using an SFTP client application.

An SFTP client is used to connect to the Track server and manually upload your files through the application to register your shipments.

If you don’t already have an SFTP client installed on your computer, you can download and install one of the following applications:

• FileZilla
• WinSCP
• Cyberduck

Once you have an SFTP application installed:

1. Have the private key (PPK file) ready on the PC you will be uploading the files from. You download this when you set up your SFTP account.
2. Open an SFTP client and start a new SFTP connection. This set up may vary depending on the application you’re using.
   
   You’ll need the following details to connect successfully:
   • File Protocol: SFTP - SSH File Transfer Protocol.
   • Host Name: react-sftp.sorted.com - if you receive an error, try sftp://react-sftp.sorted.com instead.
   • Your Track SFTP username and passphrase.
   • The Private key file location that you downloaded.
3. Enter these details into your SFTP application and connect to the server.
4. Upload the .csv or .json file with your shipment data.

SFTP file upload results link

Once you have uploaded the file, Track processes the shipment data you’ve sent. As the shipments are processed, Track writes the result of each registration attempt to a JSON file on the server.

The completed JSON 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.)

Below are some example results that you may receive following a file upload.

1. The file contained a single shipment, which was successfully uploaded.

SFTP Result File 1 link

  {
  "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"
}
  

2. 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.

SFTP Result File 2 link

  {
  "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"
}
  

3. The file could not be parsed at all, most likely due to an invalid structure:

SFTP Result File 3 link

  {
  "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.

Register shipments by email link

Track’s register by email functionality allows you to register shipments without having to make any API request or uploads via SFTP.

Next steps link

• Go back to getting started
• Grouping shipments
• Shipment filters