Register shipments with Track

  • track
  • api
  • shipments
  • registration

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:

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

    api-key-tile

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

    api-key-result

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

    api-key-copied2

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:

  1. Save the private key to the machine you will be uploading the files from.
  2. 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.
  3. 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:

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

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

    assign-carrier1

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

    assign-carrier2

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 and promised_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 a key, value, and data type.

    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.

  • 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 a ShipmentSummary - an overview of the data Track holds on the shipment in question. The more information Track holds on the shipment, the more useful this ShipmentSummary 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 a country_iso_code for both destination and origin addresses enables 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.

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.

Next steps