Register shipments

  • 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 in Track without having to make an API call or SFTP upload. Registering shipments by email enables less-technical users, and those users who do not have access to make API calls or upload via SFTP, to set shipments up for tracking.

Each authorised Register by Email account has its own destination email address. Simply blind carbon copy (BCC) this address in to an email containing shipment details to register a new shipment.

Authorise your email address

In order to register shipments by email, you will first need to authorise your email address as a sender.

To authorise your email address:

  1. Click Settings > Shipments by Email to display the Email Shipment Registration page.

    sbe1

  2. Click Edit on the Authorised Emails tile to display the Authorised Emails page.

    sbe2

  3. Click Add Email to display the Add Authorised Email page.

    sbe3

  4. Enter an Authorised Email Address and click the Make This Active check box.

  5. Click Add to register the address. Track displays a dialog containing an auto-generated unique registration email address.

    sbe4

  6. Make a note of the registration email address. This is the address you should send shipment data to from the email address that you registered.

  7. Click Accept to close the dialog and return to the Authorised Emails page. The newly-authorised email address is displayed as a tile on this page.

Note

The process of authorising your email address to register shipments is entirely separate from the account creation process. You will need to perform the process detailed above for every email address that you want to use to register shipments.

Manage authorised email addresses

You can edit your existing authorised email addresses from the Settings > Shipments by Email > Authorised Emails page.

sbe5

Edit existing addresses

To edit an existing address, click its Edit button. Track displays the Editing Authorised Email page for that address. Make the required edits and click Update to save your changes.

Deactivate existing addresses

To deactivate an existing address, click the Active toggle on the address tile. The toggle switches to the Inactive position, confirming that the address has been deactivated.

Deactivating an address means that you can no longer use it to register shipments. However, its configuration is saved, and you can reactivate the address by clicking the toggle again.

Delete existing addresses

To permanently delete an address, click its Delete button.

Track displays a confirmation dialog. Click Yes to delete the address.

Deleting an address permanently removes all of its configuration. To reinstate a deleted address you would need to set it up again.

Send a registration email

In order to register a shipment, blind carbon copy (BCC) your registration recipient email address in to an email containing an XML shipment object.

Include the details of the shipment in the body of your email. Unlike the JSON objects used in Track API calls, a shipment sent by email must be represented as an XML object. For security reasons, the properties of the XML object must be empty, with the shipment values you want to register expressed as XML value attributes within each tag.

Note

You can only register shipments by blind-copying your recipient email address into a shipment. The registration will not work if you send the email to the recipient directly.

This process enables you to register shipments using, for example, the delivery dispatch notifications you send to your customers. In order to do so, you would send the email to the end customer but BCC the registration recipient into the same email, as well as adding the relevant XML shipment details to the body of the notification.

The example below shows a blank shipment record in valid Register by Email format.

<react_shipments>
  <react_shipment>
    <react_tracking_reference value="x" />
    <react_tracking_reference value="y" />
    <react_package_tracking_reference value="x" />
    <react_custom_reference value="x" />
    <react_custom_reference value="y" />
    <react_tags value="x" />
    <react_tags value="y" />
    <react_carrier value="x" />
    <react_carrier_reference value="x" />
    <react_carrier_service value="x" />
    <react_shipped_date value="x" />
    <react_order_date value="x" />
    <react_promised_date_start value="x" />
    <react_promised_date_end value="x" />
    <react_expected_delivery_date_start value="x" />
    <react_expected_delivery_date_end value="x" />
    <react_addresses_0_address_type value="x" />
    <react_addresses_0_address_reference value="x" />
    <react_addresses_0_property_number value="x" />
    <react_addresses_0_property_name value="x" />
    <react_addresses_0_address_line1 value="x" />
    <react_addresses_0_address_line2 value="x" />
    <react_addresses_0_address_line3 value="x" />
    <react_addresses_0_locality value="x" />
    <react_addresses_0_region value="x" />
    <react_addresses_0_postal_code value="x" />
    <react_addresses_0_country_iso_code value="x" />
    <react_addresses_0_lat_long_latitude value="x" />
    <react_addresses_0_lat_long_longitude value="x" />
    <react_addresses_1_address_type value="x" />
    <react_addresses_1_address_reference value="x" />
    <react_addresses_1_property_number value="x" />
    <react_addresses_1_property_name value="x" />
    <react_addresses_1_address_line1 value="x" />
    <react_addresses_1_address_line2 value="x" />
    <react_addresses_1_address_line3 value="x" />
    <react_addresses_1_locality value="x" />
    <react_addresses_1_region value="x" />
    <react_addresses_1_postal_code value="x" />
    <react_addresses_1_country_iso_code value="x" />
    <react_addresses_1_lat_long_latitude value="x" />
    <react_addresses_1_lat_long_longitude value="x" />
    <react_consumer_reference value="x" />
    <react_consumer_email value="x" />
    <react_consumer_phone value="x" />
    <react_consumer_mobile_phone value="x" />
    <react_consumer_first_name value="x" />
    <react_consumer_last_name value="x" />
    <react_consumer_middle_name value="x" />
    <react_consumer_title value="x" />
    <react_retailer value="x" />
    <react_metadata value="x" key="k" type="t" />
    <react_metadata value="y" key="l" type="s" />
    <react_shipment_type value="x" />
    <react_shipping_location_reference value="x" />
    <react_tenant_reference value="x" />
    <react_channel_reference value="x" />
  </react_shipment>
</react_shipments>

The available properties are the same as a standard shipment request, as detailed in the REACT API Reference. Only the format of the request is different.

As with other methods of registration, only the tracking_references property is mandatory when registering shipments by email. All other properties are optional.

If required, you can add additional content to the email before or after the shipment object.

You can register multiple shipments in the same email using the format below:

<react_shipments>
  <react_shipment>
    x
  </react_shipment>
  <react_shipment>
    y
  </react_shipment>
</react_shipments>

Register by email - worked example

The example below shows the same shipment represented in both JSON (as per a Register Shipments API call) and XML (as per a Register by Email request).

{
  "shipments": [
    {
      "tags": [
        "BRAND_X",
        "Dewsbury_Hub"
      ],
      "tracking_references": [
        "TRK098JKH54ADD"
      ],
      "custom_references": [
        "af6fd78ce0754de5887924e0f16e8e94",
        "HB-003"
      ],
      "carrier": "Carrier X",
      "carrier_service": "Next Day Priority",
      "shipped_date": "2021-05-28T00:00:00+00:00",
      "order_date": "2021-05-28T00:00:00+00:00",
      "promised_date": {
        "start": "2021-06-04T09:00:00+00:00",
        "end": "2021-06-04T12:00:00+00:00"
      },
      "addresses": [
        {
          "address_type": "origin",
          "reference": "bf4a06df5e0e4ad7a14f3f0c512bd19a"
        },
        {
          "address_type": "destination",
          "postal_code": "N2 3FD",
          "country_iso_code": "GB"
        }
      ],
      "consumer": {
        "reference": "Kxa57jtLbUWVoLnz5QpVEg",
        "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"
    }
  ]
}

View invalid register shipment files

If you send a file to the Register by Email service that does not pass validation, then Track creates an Invalid Register Shipment record detailing the issue. To see a list of your Invalid Register Shipment files, select Settings > Shipments by Email > Invalid Register Shipment Files.

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