Tracking API quick start

Before you begin

Before you can use the Tracking API, you must:

  • Have a commercial contract with Metapack for the API.
  • Have access to a shipping platform.

Although the Tracking API requires order and delivery data from a shipping platform, it does not fetch that data directly. Therefore, if you are using a shipping platform other than the Metapack Platform, you will use the data ingest operations of the Tracking API to push data from your shipping platform to the API.

Getting an API key

You must request an API key from your Metapack Professional Services implementation consultant.

An API key is sent by encrypted email to the email address specified in an API key request. The messsage includes your username, password, key, and secret.

You can request a single API key for all Tracking API requests. Alternatively, you can request two API keys so that you can use one API key for all data ingest requests (deliveries and delivery legs) and another key for all data retrieval requests (parcel journeys). Using two API keys with the Tracking API is recommended because API key-level quotas apply to data retrieval requests.

By default, your API key(s) provide(s) access to our sandbox environment.

Making API requests

Authentication

The Tracking API uses TLS authentication and the HTTP basic access authentication method.

To authenticate yourself to the API, you must include an Authorization header in each API request, which comprises the Basic prefix followed by a Base64-encoded <username>:<password> string .

Copy
Copied
curl --request HTTP_VERB \ 
--url "https://API_BASE_ADDRESS_AND_ENDPOINT" \ 
--header "Authorization: Basic Base64-encoded <username>:<password>" \

The Tracking API uses Hypertext Transfer Protocol Secure (HTTPS) to provide secure connections. Therefore, you must use HTTPS for all direct communication between your systems or apps and the API.

Sandbox environment

The Tracking API is available in the following sandbox environment:

https://api.sbx.metapack.com/tracking/v1

You can use the sandbox environment until you are ready to move to our production environment. To get your API key to access our production environment, you must contact your Metapack Professional Services implementation consultant.

Versions

The base URLs of all Tracking API resources are versioned. The API uses URI versioning as follows:

MAJOR.MINOR.PATCH

These versions are as follows.

Version Description
Major The version number used in the URI. It denotes breaking changes to the API. Any previously existing URIs should continue to operate as before, returning resources that conform to their original schemas.
Minor, Patch These are communicated in the API changelog to inform clients about new features, deprecated features, or bug fixes.

Quotas

The Tracking API is implemented with API key-level quotas for data retrieval requests. The quota is defined in your commercial contract and specifies the maximum number of retrieval requests that you can make each month. Where possible, you will need to ensure that you remain within this limit.

When a quota is reached, the API returns status code 429 (Too Many Requests).

Rate limits

The Tracking API supports API key-level rate limiting, so it enforces a limit on the number of requests that clients can make.

The standard rate limit of the Tracking API is 10 requests per second per API key.

When a rate limit is reached, the API returns status code 429 (Too Many Requests).

Make your first API request

Your first Tracking API request will depend on the shipping platform being used:

  • If you are using the Metapack Platform, go to the API and use an API key and cURL and an order reference and/or a tracking identifier to retrieve a parcel journey .
  • Alternatively, if you are using another shipping platform, go to the API and use an API key and cURL to create a delivery or a delivery leg .

If you are more comfortable using an API developer platform like Postman, check out our guide how to configure Postman to interact with the API.

Next steps

Now that you’re successfully making authenticated requests to the Tracking API with your API key(s), there are different paths that you can take to become more familiar with the API.

If you want to… See…
Understand how the API works Tracking orders and parcels, Supported tracking events, and Supported carriers
Learn how to use the API Guides
Download the OpenAPI specification Tracking API v1.0.1 (YAML)
Review the API endpoints Reference