Metapack logo

Metapack Tracking API (1.0.12)

Download OpenAPI specification:Download

URL: https://www.metapack.com/ License: Apache 2.0

The Tracking API lets you easily integrate delivery tracking data with your apps and services. You can track delivery events from more than 300 carriers through a single API. It also enables you to publish pre-ship and returns events for complete end-to-end order tracking.

For more information about the API, go to https://dev.metapack.com/.

Tracking

Retrieve the parcel journeys for an order or a parcel

A parcel journey contains the full tracking history related to the delivery of a parcel.

It unifies in a normalised format all of the events that have been published for the parcel, both pre-allocation and post-allocation.

These events include deliveries, delivery legs, and carrier tracking events.

SecurityBasicAuth
Request
query Parameters
orderRef
string

Use the order reference to retrieve all parcel journeys for the order.

Note: This parameter is case sensitive.

Example: orderRef=REPLACE-WITH-YOUR-ORDER-REF
trackingIdentifier
string

Use the tracking identifier to retrieve the parcel journey for a specific parcel.

Use this parameter in combination with order reference to ensure that any parcel journeys returned for an order contain at least one delivery leg that matches the specified tracking identifier.

Note: This parameter is case sensitive.

Example: trackingIdentifier=REPLACE-WITH-YOUR-TRACKING-IDENTIFIER
customerRef
string

Unique reference of the customer.

Use this optional parameter to filter parcel journeys for a specific customer when a multi-brand seller can use the same order reference across its brands.

To use this filter, the customer reference must be provided in the delivery and delivery legs for the corresponding order and parcels (order.customer.customerRef).

Note: This parameter is case sensitive.

Example: customerRef=REPLACE-WITH-YOUR-CUSTOMER-REF
postcode
string

The postcode of the parcel recipient.

Use this optional parameter in combination with order reference or tracking identifier to ensure that any parcel journeys returned for an order contain at least one parcel journey that matches the specified parcel recipient postcode (recipient.postCode).

Note: This parameter is case sensitive.

Example: postcode=WC1X 8XZ
header Parameters
User-Agent
string

The name of the client that interacts with the API.

Example: REPLACE-WITH-YOUR-USER-AGENT
Accept-Encoding
string

Enables the compression of the content returned in the response.

Supported content encodings are gzip and deflate.

Example: gzip, deflate
Accept-Language
string

Use this header to retrieve parcel journeys with information localised in the requested language.

The default format used is an ISO 639-1 language code in lowercase hyphenated with a country code in ISO 3166-1 alpha-2 format in UPPERCASE. For example, en-GB will return information localised in UK English whereas en-US will return information localised in US English.

If this header is omitted, the parcel journeys will be returned with information localised in English.

Note: Localised information will be returned only when requesting a supported language.

Enum: "bg-BG" "cs-CZ" "da-DK" "de-DE" "en-GB" "en-US" "es-ES" "fi-FI" "fr-FR" "hr-HR" "hu-HU" "it-IT" "ja-JP" "ko-KR" "nb-NO" "nl-NL" "pl-PL" "pt-PT" "ro-RO" "sv-SE" "tr-TR" "zh-CN"
Example: en-GB
Responses
200

Parcel Journeys have been returned successfully

400

Bad request.

The request failed validation due to missing required information in the parameters or the body of the request.

Error code: PS-0400.

401

Unauthorized.

The request did not provide the credentials required to authorize access to the API.

Error code: PS-0401.

403

Forbidden.

The API user is not authorized to proceed with the processing of the request.

Error code: PS-0403.

500

Internal Server Error.

The processing of the request failed due to an internal problem. The request needs to be retried.

Error code: PS-0500.

get/parcel-journeys
Request samples 
Response samples 
application/json
[
  • {
    }
]
Post-allocation
Create or update a delivery leg for a trackable item
A delivery leg is a stage of the parcel journey defined by a single tracking identifier.


It contains the necessary information for the delivery of a parcel and the information about the carrier delivering the parcel.


A delivery leg can be used to support a tracking experience after the trackable item has been allocated a tracking identifier.


A delivery leg can be linked to a delivery if they share the same delivery reference.


Multiple delivery legs can be linked to one another if they share the same parcel reference.


A delivery leg is identified by its tracking identifier only or its tracking identifier in combination with its parcel reference when both are provided.


Note: Each time you update a delivery leg, you must resubmit the mandatory information of the delivery leg in addition to any other data that you have added or modified.


SecurityBasicAuth 
Request 
header Parameters
User-Agent
string
The name of the client that interacts with the API.


 
 Example:  REPLACE-WITH-YOUR-USER-AGENT
Shipper-Id
string
The unique identifier of a shipper within Metapack shipping platform.


Note: Reserved for Metapack use only.


 
Request Body schema: application/json
trackingIdentifier
required
string
The external identifier used to track the parcel. This can be the tracking identifier used by carriers or any barcode that identifies the parcel.


 
carrierCode
string
The carrier code (Metapack code).


 
carrierDisplayName
string
The name of the carrier.


 
carrierServiceCode
string
The service code (Metapack code).


 
carrierTrackingURL
string <uri> ^https://
The link to the carrier website for tracking the parcel.


 
deliveryRef
string
The unique delivery reference.


 
finalDeliveryLeg
boolean
Indicates that the parcel delivery leg is the final stage in the delivery journey. Default to true.


 
object (Collection) 
Collection information for pickup point or store collection delivery.


 
object (DeliveryInformation) 
Information about the type of delivery.


 
object (Order) 
An order contains information about the seller and the customer. It is used to provide the full overview of the deliveries for all the parcels within this order by using the order reference (orderRef).


 
object (DeliveryLegParcel) 
 
object (Recipient) 
The person receiving the parcel(s) in an order. The recipient is used to provide the destination time zone (Recipient.timeZone), which is used to process tracking events received from carriers when they do not provide time zone information with their events.


 
object (Sender) 
Sender contains the information about the location from where the parcels for a delivery will ship. It contains the source time zone (Sender.timeZone), which is used to process tracking events received from carriers when they do not provide time zone information with their events.


 
Responses 
204
The delivery leg information has been processed successfully


400
Bad request.


The request failed validation due to missing required information in the parameters or the body of the request.


Error code: PS-0400.


401
Unauthorized.


The request did not provide the credentials required to authorize access to the API.


Error code: PS-0401.


403
Forbidden.


The API user is not authorized to proceed with the processing of the request.


Error code: PS-0403.


415
Unsupported media format.


The request failed due to an unsupported media type in the request.


Error code: PS-0415.


500
Internal Server Error.


The processing of the request failed due to an internal problem. The request needs to be retried.


Error code: PS-0500.


post/delivery-legs
Request samples 
application/json
{
  • "trackingIdentifier": "REPLACE-WITH-YOUR-TRACKING-IDENTIFIER",
  • "carrierCode": "DPD_UK",
  • "carrierDisplayName": "DPD UK",
  • "carrierServiceCode": "DPD_UK_CLASSIC",
  • "carrierTrackingURL": "https://track.dpd.co.uk/parcels/REPLACE-WITH-YOUR-TRACKING-IDENTIFIER",
  • "deliveryRef": "REPLACE-WITH-YOUR-DELIVERY-REF",
  • "finalDeliveryLeg": true,
  • "collection": {
    },
  • "delivery": {
    },
  • "order": {
    },
  • "parcel": {
    },
  • "recipient": {
    },
  • "sender": {
    }
}
Response samples 
application/json
{
  • "message": "This is an error message",
  • "errorCode": "PS-XXXX",
  • "systemMessage": "This is a system message related to the error",
  • "traceId": "4d1544c7-1977-4c03-82fa-ecacd1837532",
  • "timestamp": "2019-08-24T14:15:22Z"
}
Delete delivery legs for a given tracking identifier
Delete the delivery legs that have been created with the given tracking identifier.


This method is used to remove delivery legs no longer needed in a parcel journey.


This happens when the tracking identifier in the delivery leg will never be used for tracking a parcel, which means that no tracking events will ever be received for the given tracking identifier.


SecurityBasicAuth 
Request 
query Parameters
trackingIdentifier
required
string
Use the tracking identifier of the delivery legs that need to be deleted. 


Note: This parameter is case sensitive.


 
 Example:  trackingIdentifier=REPLACE-WITH-YOUR-TRACKING-IDENTIFIER
header Parameters
User-Agent
string
The name of the client that interacts with the API.


 
 Example:  REPLACE-WITH-YOUR-USER-AGENT
Responses 
200
All delivery legs for the specified tracking identifier have been deleted


400
Bad request.


The request failed validation due to missing required information in the parameters or the body of the request.


Error code: PS-0400.


401
Unauthorized.


The request did not provide the credentials required to authorize access to the API.


Error code: PS-0401.


403
Forbidden.


The API user is not authorized to proceed with the processing of the request.


Error code: PS-0403.


500
Internal Server Error.


The processing of the request failed due to an internal problem. The request needs to be retried.


Error code: PS-0500.


delete/delivery-legs
Request samples 
Response samples 
application/json
{
  • "message": "Deleted 2 delivery legs"
}
Add tracking events for a delivery leg
A delivery leg event for a trackable item that relates to the status of a parcel post-allocation.


Delivery leg events can be used to update the status of a parcel when ready for collection in a store or at a pickup point.


SecurityBasicAuth 
Request 
header Parameters
User-Agent
string
The name of the client that interacts with the API.


 
 Example:  REPLACE-WITH-YOUR-USER-AGENT
Request Body schema: application/json
trackingIdentifier
required
string
The external identifier used to track the parcel. This can be the tracking identifier used by carriers or any barcode that identifies the parcel.


 
eventCode
required
string
Metapack event code.


 Enum: "AWAITING_DESPATCH" "DESPATCHED" "NOT_YET_RECEIVED_BY_CARRIER" "RECEIVED_BY_CARRIER" "RECD_BY_CARRIER_NO_ELEC_ADVICE" "COLLECTION_REQUESTED" "COLLECTION_MADE" "COLLECTION_FAILED" "ROUTING_ERROR" "CARRIER_DELAYS" "PARCEL_LOST" "DELAYED_NOT_CARRIER" "HELD_BY_CUSTOMS" "PARCEL_DAMAGED" "IN_TRANSIT" "RECEIVED_LOCAL_DELIVERY_DEPOT" "HUB_SCAN_OUT" "CUSTOMS_PROCESSING" "COLLECT_AT_LOCAL_PO" "SUB_CONTRACTOR_EVENT" "OUT_FOR_DELIVERY" "SUB_CONTRACTOR_RECEIVED" "ADDRESS_QUERY" "CUSTOMER_CARDED" "DELIVERED_IN_PART" "CUSTOMER_TO_COLLECT_FROM_CARRIER" "HELD_BY_CARRIER" "CUSTOMER_MOVED" "REFUSED_BY_CUSTOMER" "RETURN_TO_SENDER" "NOT_DELIVERED" "NOT_DELIVERED_ADDRESSEE_DECEASED" "DELIVERED" "DELIVERED_TO_PO_BOX" "DELIVERED_DAMAGED" "INFORMATION" "POST_TRANSIT_STATUS" "PROOF_OF_DELIVERY" "HAZARDOUS_PROHIBITED" "CANCELLED" "ELEC_ADVICE_RECD_BY_CARRIER" "CLOSED_BY_SYSTEM" "MISSORTED" "DELIVERY_ARRANGED_WITH_RECIPIENT" "NO_ACCESS_TO_RECIPIENTS_ADDRESS" "COD_AMOUNT_NOT_PAID" "CUSTOMER_IDENTIFICATION_FAILED" "INVALID_METHOD_OF_PAYMENT" "COD_AMOUNT_PAID" "CUSTOMS_CLEARED" "PARCEL_REPACKED" "PARCEL_DISPOSED" "INCORRECT_DECLARATION" "HELD_BY_IMPORT_CUSTOMS" "HELD_BY_EXPORT_CUSTOMS" "DELIVERED_TO_NEIGHBOUR" "DELIVERED_SPECIFIED_SAFE_PLACE" "PARCEL_COLLECTED_FROM_PICKUP_POINT" "AWAITING_COLLECTION_FROM_PICKUP_POINT" "NOT_COLLECTED_FROM_PICKUP_POINT" "DELIVERED_TO_LOCKER_COLLECTION_POINT" "DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION" "HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING" "PARCEL_OVER_LABELLED" "PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY" "PARCEL_UPDATE_NOTIFICATION_VIA_SMS" "PARCEL_UPDATE_NOTIFICATION_VIA_EMAIL" "ATTEMPTED_DELIVERY" "ATTEMPTED_DELIVERY_2ND" "ATTEMPTED_DELIVERY_3RD" "READY_FOR_PACKING" "CANCELLED_BEFORE_DESPATCH" "RETURN_CREATED" "RETURN_NEEDS_APPROVAL" "RETURN_APPROVED" "RETURN_LABEL_CREATED" "RETURN_CANCELLED" "RETURN_REJECTED" "RETURN_WINDOW_EXPIRED" "RETURN_RECEIVED" "RETURN_COMPLETED" "RETURN_COMPLETED_IN_PART" "RETURN_NOT_COMPLETED"  
eventDate
required
string <date-time> 
Date and time when the event occured.


 
eventSource
string
Source of the event, such as CARRIER or STORE.


 
eventTimeZone
required
string
Time zone at the location of the event.


 
object (EventLocation) 
Location information where the event occured.


 
Responses 
204
Tracking event has been published successfully


400
Bad request.


The request failed validation due to missing required information in the parameters or the body of the request.


Error code: PS-0400.


401
Unauthorized.


The request did not provide the credentials required to authorize access to the API.


Error code: PS-0401.


403
Forbidden.


The API user is not authorized to proceed with the processing of the request.


Error code: PS-0403.


415
Unsupported media format.


The request failed due to an unsupported media type in the request.


Error code: PS-0415.


500
Internal Server Error.


The processing of the request failed due to an internal problem. The request needs to be retried.


Error code: PS-0500.


post/delivery-legs/events
Request samples 
application/json
{
  • "trackingIdentifier": "REPLACE-WITH-YOUR-TRACKING-IDENTIFIER",
  • "eventCode": "AWAITING_COLLECTION_FROM_PICKUP_POINT",
  • "eventDate": "2019-08-24T14:15:22Z",
  • "eventSource": "STORE",
  • "eventTimeZone": "Europe/London",
  • "eventLocation": {
    }
}
Response samples 
application/json
{
  • "message": "This is an error message",
  • "errorCode": "PS-XXXX",
  • "systemMessage": "This is a system message related to the error",
  • "traceId": "4d1544c7-1977-4c03-82fa-ecacd1837532",
  • "timestamp": "2019-08-24T14:15:22Z"
}
Pre-allocation
Create or update a delivery
A delivery is a placeholder entity created by a seller before the order is allocated to a carrier.


A delivery is identified by its unique delivery reference or the combination of its delivery reference and order reference when both are provided.


Before a trackable item exists, a delivery resource can provide a tracking experience.


Note: Each time you update a delivery, you must resubmit the mandatory information of the delivery in addition to any other data that you have added or modified.


SecurityBasicAuth 
Request 
header Parameters
User-Agent
string
The name of the client that interacts with the API.


 
 Example:  REPLACE-WITH-YOUR-USER-AGENT
Shipper-Id
string
The unique identifier of a shipper within Metapack shipping platform.


Note: Reserved for Metapack use only.


 
Request Body schema: application/json
deliveryRef
required
string
The unique delivery reference. This reference is used to link a delivery for an order with the delivery legs for the parcels within this delivery that are part of the order.


 
object (Order) 
An order contains information about the seller and the customer. It is used to provide the full overview of the deliveries for all the parcels within this order by using the order reference (orderRef).


 
object (Collection) 
Collection information for pickup point or store collection delivery.


 
object (DeliveryInformation) 
Information about the type of delivery.


 
object (Recipient) 
The person receiving the parcel(s) in an order. The recipient is used to provide the destination time zone (Recipient.timeZone), which is used to process tracking events received from carriers when they do not provide time zone information with their events.


 
object (Sender) 
Sender contains the information about the location from where the parcels for a delivery will ship. It contains the source time zone (Sender.timeZone), which is used to process tracking events received from carriers when they do not provide time zone information with their events.


 
Responses 
204
Delivery information for the order has been processed successfully


400
Bad request.


The request failed validation due to missing required information in the parameters or the body of the request.


Error code: PS-0400.


401
Unauthorized.


The request did not provide the credentials required to authorize access to the API.


Error code: PS-0401.


403
Forbidden.


The API user is not authorized to proceed with the processing of the request.


Error code: PS-0403.


415
Unsupported media format.


The request failed due to an unsupported media type in the request.


Error code: PS-0415.


500
Internal Server Error.


The processing of the request failed due to an internal problem. The request needs to be retried.


Error code: PS-0500.


post/deliveries
Request samples 
application/json
{
  • "deliveryRef": "REPLACE-WITH-YOUR-DELIVERY-REF",
  • "order": {
    },
  • "collection": {
    },
  • "delivery": {
    },
  • "recipient": {
    },
  • "sender": {
    }
}
Response samples 
application/json
{
  • "message": "This is an error message",
  • "errorCode": "PS-XXXX",
  • "systemMessage": "This is a system message related to the error",
  • "traceId": "4d1544c7-1977-4c03-82fa-ecacd1837532",
  • "timestamp": "2019-08-24T14:15:22Z"
}
Add events for a delivery
A delivery event is an event published by a seller that relates to the status of a delivery pre-allocation, such as an order being processed or awaiting payment.


Delivery events can be defined before a trackable item exists.


SecurityBasicAuth 
Request 
header Parameters
User-Agent
string
The name of the client that interacts with the API.


 
 Example:  REPLACE-WITH-YOUR-USER-AGENT
Request Body schema: application/json
deliveryRef
required
string
The unique delivery reference. This reference is used to link a delivery for an order with the delivery legs for the parcels within this delivery that are part of the order.


 
eventCode
required
string
Metapack event code.


 Enum: "ORDER_ACCEPTED" "PAYMENT_SUCCESSFUL" "PAYMENT_DECLINED" "CANCELLED_BEFORE_DESPATCH" "ORDER_DECLINED" "PERSONALISATION_STARTED" "PERSONALISATION_ISSUE" "AWAITING_FULFILMENT" "PERSONALISATION_COMPLETED" "READY_FOR_PACKING" "DESPATCH_DELAYED" "DESPATCH_DELAYED_IN_PART" "RETURN_CREATED" "RETURN_NEEDS_APPROVAL" "RETURN_APPROVED" "RETURN_CANCELLED" "RETURN_REJECTED" "RETURN_WINDOW_EXPIRED" "RETURN_NOT_COMPLETED" "RETURN_COMPLETED" "RETURN_COMPLETED_IN_PART"  
eventDate
required
string <date-time> 
Date and time when the event occured.


 
eventSource
string
Source of the event, such as CARRIER or STORE.


 
eventTimeZone
required
string
Time zone at the location of the event.


 
object (EventLocation) 
Location information where the event occured.


 
Responses 
204
Delivery event has been published successfully


400
Bad request.


The request failed validation due to missing required information in the parameters or the body of the request.


Error code: PS-0400.


401
Unauthorized.


The request did not provide the credentials required to authorize access to the API.


Error code: PS-0401.


403
Forbidden.


The API user is not authorized to proceed with the processing of the request.


Error code: PS-0403.


415
Unsupported media format.


The request failed due to an unsupported media type in the request.


Error code: PS-0415.


500
Internal Server Error.


The processing of the request failed due to an internal problem. The request needs to be retried.


Error code: PS-0500.


post/deliveries/events
Request samples 
application/json
{
  • "deliveryRef": "REPLACE-WITH-YOUR-DELIVERY-REF",
  • "eventCode": "ORDER_ACCEPTED",
  • "eventDate": "2019-08-24T14:15:22Z",
  • "eventSource": "STORE",
  • "eventTimeZone": "Europe/London",
  • "eventLocation": {
    }
}
Response samples 
application/json
{
  • "message": "This is an error message",
  • "errorCode": "PS-XXXX",
  • "systemMessage": "This is a system message related to the error",
  • "traceId": "4d1544c7-1977-4c03-82fa-ecacd1837532",
  • "timestamp": "2019-08-24T14:15:22Z"
}
Customer Support