Show / Hide Table of Contents

    Register shipments with Track

    • track
    • api
    • shipments
    • registration

    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.

    For more information, check out our why register additional shipment data section below to find out how including particular field properties in your shipment registration can enhance your Track platform.


    Why register additional shipment data?

    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.

    For example, a carrier may not be able to provide an update on a shipment right away if it's delayed or stuck in customs. This update may not be provided for some time.

    If the correct delivery date is registered with the shipment, Track can anticipate a potential delay meaning you can respond and inform customers before even being notified by the carrier.

    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

    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

    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

    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

    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.

    Note

    Some areas of the United Kingdom, do not fall under the generic GB ISO code. Jersey (JE), Guernsey (GG) and Isle of Man (IM) have their own unique codes.

    Example addresses json array with country ISO codes:

    "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

    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
    Amazon A0CC924D-1596-44EA-BD21-32A53F5919CD
    AnPost C21F286D-D83B-45B7-8224-01B2016A1A03
    APG 50D10273-D750-4CDC-8DB9-C70BD9099B69
    ArrowXL E2B36840-4032-49A9-981F-44A7097AFDFE
    Asda toyou F1535C2B-10C8-4D43-9976-11848DEA013D
    Asendia 0F7FD87E-3F95-4203-A397-11F81DC2C4DA
    Australia Post E562155F-3DA4-48A1-979A-AC4E26069701
    Collectplus B3109373-EF07-4A2E-B5FA-89283BE33691
    Deutsche Post 3C350D96-8E8E-492E-85EA-D00BE05A2FB8
    DHL eCommerce 9183ACD0-10F0-411C-9F29-C53CD1414D98
    DHL Express 532D2CE2-79DC-4E24-840C-C75A37CF02DC
    DHL Paket 6A7657AE-EB7E-459F-B3A8-1A6C10D8B205
    DHL Parcel UK FFC0644D-B570-413F-A6B8-CC4F20B491A0
    DPD Germany 0B664AA8-DA77-4F97-AB44-0749ACBE8CCB
    DPD Italy B3F17999-F874-40A4-A8D1-21F8A446889F
    DPD Local UK F8714833-FB20-45DE-8563-CDE2D8EFA985
    DPD UK D1FB3EA4-7AA4-4D50-B1F3-9AF69A582038
    DX Express DC20313A-3635-4FD8-B4C5-9BCB0DF3D391
    DX Freight E48028D6-35B7-48A8-A542-4C7EDB4DBEE1
    Evri 26432E9D-73CB-44EF-ABB5-164088A93ABE
    Fastway 2539E909-6C0B-4D70-8C3E-2CE4CD16CA4C
    FedEx 5FE878CB-32BF-4221-B2BF-45C89739825D
    GLS US 54104321-604D-474E-B559-DD254E2D22C7
    InPost 52514FE7-BD63-4EE0-B810-EECFC84C1819
    Jersey Post 911A07C3-3E48-4875-BD07-CF1B37465C33
    Landmark Global E9D32156-BAC3-4F15-B658-AE6E460212D0
    Lineten 00E32B3C-87D6-4FE3-AD79-D21133469EAE
    Naqel Express B7859650-7FF2-4EF3-8D9B-FC8F78E3C2EE
    OCS Worldwide F927FF86-9772-411C-B855-8702398DB45C
    P2P TRAKPAK 19E6AEA5-278D-476A-8576-D4DBC3C2DD94
    Panther E75A59D7-205E-B1A8-B8AD-E1786DE37E21
    Parcelforce 57E2A30D-368B-4F42-9E20-5F6B3A5115BC
    Postnord E49162D2-EE6C-49D9-9BAF-A02320E2378A
    Royal Mail B5096289-91F4-49E2-9B8E-018964877C5E
    Seur 29CB239B-94E3-4D48-B8EC-2E99C283B395
    Spring Global 6C1542BF-81CD-4A9F-88F0-DD4BB0E252AE
    Stuart ACC878D6-931E-4C9F-B68E-A3BBC6D03574
    TNT 385A136E-8A1A-405F-B6A8-35BD7E2C7BD8
    UPS 121DB19E-8356-428A-BB6C-4A53DA8C0389
    USPS EA57B37D-5C28-4A66-9402-16D0F4CAEE6C
    Whistl C6A9DA28-BB4C-482F-9F4A-1E8AEBDA71C6
    Yodel 77B7A461-E3B3-4B2C-9B90-2F42FE4BFC25

    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.

      assign-carrier1

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

      assign-carrier2

    References

    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

    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.

    Note

    By default, shipments are archived 35 days after registration. Shipments are no longer viewable on the Track platform after this time.

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

    Register shipment methods

    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.

    Note

    You are not restricted to only one registration method and can use more than one if you wish.

    View the sections below for more information on our registration methods.

    Register shipments by API

    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

    To generate a new API key:

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

      api-key-tile

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

      api-key-result

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

      api-key-copied2

    Caution

    It's 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 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

    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 API reference.

    • Detailed Register Shipment Request
    {
      "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

    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
    {
      "shipments": [{
        "tracking_references": ["TRACKING-DEMO-REFERENCE"]
      }]
    }
    

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

    • Register multiple shipments
    {
      "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.

    • Successful register shipment response
    {
      "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

    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

    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

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

    Note

    You are not restricted to one file type, you can upload data in both file types if you wish.

    JSON

    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

    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.

    For example, the header for the origin address postcode of a shipment would be recorded as addresses/0/postal_code and the header for the destination postcode would be defined under the header addresses/1/postal_code.

    The same applies for properties like metadata, custom_references and tags where multiple records can be registered with the shipment.

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

    • CSV
    "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

    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)

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

    Below is an example SFTP connection screen using Filezilla and the required fields that must be populated. Filezilla set up

    SFTP file upload results

    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
    {
      "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"
    }
    
    1. 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
    {
      "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"
    }
    
    1. The file could not be parsed at all, most likely due to an invalid structure:
    • SFTP Result File 3
    {
      "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

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

    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.

    Next steps

    • Go back to Getting Started
    • Update shipments
    • Error codes
    Back to top Copyright © Sorted Group 2023. Generated by DocFX