logo

First time here

API

API Explorer

Change log

Summary

This documentation is generated from the code of the API itself and will always reference the latest version of that code which is in production. Therefore, it is the most up to date documentation on the subject, and should be considered the sole source of truth.

1. Overview

Shipment vs Consignment

In the context of MetaPack Manager it is important to differentiate between what is termed a Shipment and that of a Consignment. Please see our glossary for standard definitions.

If we look a typical logical flow: a customer places an order on a website, which is in turn created in an order management system. The order management system typically knows where the items ordered are located across a retailer’s warehouse estate. The order management system passes the data to the relevant warehouse management system as a group of Trade Items that need to be shipped. At this stage we may know how these items are to be shipped but the most likely outcome is that we know the service proposition we should ship them on but we have not yet built a consignment - as we do not know exactly how each of our logistics providers build consignments.

We therefore have a Shipment that contains Logistics Units (Parcels, Pallets etc). Each Shipment has attributes (Weight, Dimensions, Cost), flags (POD, heavy etc) and Trade Items that are contained in the Shipment. A shipment is made up of one or more Logistics Units, as well as various Addresses to represent the seller, shipper and recipient. Using the allocator, we consign the Shipment to a Logistics Service; resulting in a Consignment.

1.1. Identifiers

Many entities in the API have identifiers. In some cases, these will be names of things, e.g. a Carrier (Logistics Service Provider) may be named DPD. For entities like Shipments, Consignment and Documentation the ID will be a Universally Unique Identifier (UUID). Usually returned in URL format to the API consumer.

1.2. Versions

To prevent any breaking changes, all APIs are versioned and all requests must include a version specification using a Content Type.

Content-Type: application/vnd.metapack.mm.v0+json
There is no default version, if the version content type is not included a HTTP 415 will be returned. 
HTTP/1.1 415 Unsupported Media Type

Within a major version of our API we will:

  • Add properties to Objects within the JSON response

  • Never remove properties from Objects within the JSON response

  • Never change a properties type with a JSON response

  • Never guarantee the order of properties in the JSON response

1.2.1. Supported Versions

Table 1. Versions (specified by Content-Type header)
Content-type Status

application/vnd.metapack.mm.v0+json

Preferred

application/vnd.metapack.mm.v0.7.5+json

Deprecated

application/vnd.metapack.mm.v0.7.1+json

Deprecated

application/vnd.metapack.mm.v0.7+json

Deprecated

1.3. Uniform resources

In this document, the terminology for uniform resources is always as follows:

  • a URI is defined here

  • a URL represents a resource which can be acted upon by the API

1.4. Requests

Methods

The MetaPack API supports the standard HTTP methods such as GET, POST, PUT, DELETE and these act of the various resources in the MetaPack system.

HTTP Headers

The MetaPack API supports standard HTTP headers for content negotiation. These include:

  • Accepts

  • Content-Type

  • Authorization

Unrecognised headers will be ignored but will not cause an error.

Body

The request body will contain different objects for each method which are outlined below. Request bodies will be created in JSON format.

Remember to replace example.metapack.com in all the examples with the domain name provide to you by MetaPack.

1.5. Responses

Headers

The MetaPack API uses the standard HTTP response codes (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html):

  • 2xx – successful responses

  • 3xx – responses redirecting the client to an alternative resource

  • 4xx – responses in relation to a client error

  • 5xx – responses in relation to a server error

Body

The response body will contain different objects for each endpoint called. Response bodies will be returned in a JSON-LD compatible JSON format.

The following properties are part of our JSON-LD support.

  • @context

  • @id

  • @type

Our JSON-LD support is in early development and will not be fully functional until a post 1.0 release.

1.6. Standard Response Headers

Can we get some examples of these Headers valid responses? And why they might get returned. And why a consumer of the API might be interested.
Table 2. Standard response headers
Header Description

Content-Encoding

The type of encoding used on the data, e.g. gzip

Content-Length

The length of the response body in octets (8-bit bytes)

Content-Type

The MIME type of this content

ETag

An identifier for a specific version of a resource

Host

Hostname of the server that returned the response

1.7. Errors

1.7.1. Error Statuses and Codes

As part of the API flow there is a need to identify where errors may occur and what these might be. When an error occurs it will return a HTTP status code as well as an error response body. The response body contains an error code and a textual representation of the error. See full list of API error codes for more details.

When the request violates one or more of the constraints of the API, the response includes a list of constraint violations which gives details of each unsatisfied constraint. Each constraint has a code associated with it, for more details see full list of constraint violation codes.

Table 3. Error statuses and their associated error code
HTTP Error # Description API Error Code Description

400

Bad request

O-VAL-2000
O-VAL-2002
O-VAL-2003
O-VAL-2004
O-VAL-2006
O-VAL-2008
O-NFO-3001
O-NFO-3005
O-ALE-4000
O-ALE-4001
O-ALE-4002

The request either violates one of the constraints of the api (eg a mandatory field is missing) or is logically invalid. Refer to the request structure section for this resource.

401

Unauthorized

O-INT-1000

A valid bearer token has not been supplied. Refer to API Security section.

403

Forbidden

O-INT-1000

The credentials supplied in the Authorization header via the bearer token are not allowed to perform the HTTP method on the requested resource.

404

Not Found

O-NFO-3000
O-NFO-3001
O-NFO-3002
O-NFO-3003
O-NFO-3004
O-NFO-3005

The resource requested is not found in the system.

405

Method not allowed

O-VAL-2009

The HTTP method used eg. GET, PUT, POST is not allowed for this endpoint.

409

Conflict

O-ALE-4001
O-COL-6001

There is a conflict with the current state of the target resource.

415

Unsupported Media Type

O-VAL-2001

Incorrect version content type supplied. Refer to versions section.

500

Internal Server Error

O-INT-1000

An unexpected error has occurred, which has prevented the request from being completed- eg one of the services that this platform relies on is down or not responding.

503

Service Unavailable

O-INT-1000

An internal error has occurred in the platform. You can retry the call, however if it fails repeatedly you should contact MetaPack Support regarding this.

1.7.2. Error Response Body

Details the cause of the error.

Table 4. Error response content
Path Type Version Description

timestamp

String

The time that the error occurred, in ISO 8601 format.

httpStatus

String

The HTTP status code (e.g. 400).

httpReasonPhrase

String

The HTTP reason phrase (e.g. Bad Request).

constraintViolations

Constraint Violation[]

Only present for constraint violations.

allocationErrors

Allocation Error[]

[0.11.0,)

Only present for allocation errors.

code

String

The code associated with this error. See full list of error codes.

message

String

A textual error message.

path

String

The URL path where the exception was raised.

correlationID

String

Uniquely identifies an entity across multiple systems.
Example "Invalid Content-Type Header" error response
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json;charset=UTF-8
Content-Length: 286

{
  "timestamp" : "2024-11-19T14:26:16.605Z",
  "httpStatus" : "415",
  "httpReasonPhrase" : "Unsupported Media Type",
  "code" : "O-VAL-2001",
  "message" : "The content-type header 'application/vnd.metapack.mm.vxx.yy+json' is not supported",
  "path" : "",
  "correlationID" : "ABC"
}
Example constraint-violation error response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 447

{
  "timestamp" : "2024-11-19T14:26:16.496Z",
  "httpStatus" : "400",
  "httpReasonPhrase" : "Bad Request",
  "constraintViolations" : [ {
    "rejectedValue" : null,
    "message" : "may not be null",
    "code" : "NotNull",
    "objectName" : "shipment",
    "field" : "logisticsUnits",
    "bindingFailure" : false
  } ],
  "code" : "O-VAL-2000",
  "message" : "General validation error",
  "path" : "",
  "correlationID" : "0a485a06037e77b0"
}
Example allocation-error response

An Allocation Error can be returned with code and message only, if no extra information is relevant.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "timestamp" : "2024-11-19T14:26:17.674Z",
  "httpStatus" : "400",
  "httpReasonPhrase" : "Bad Request",
  "allocationErrors" : [ {
    "message" : "No logistics service available for the DeliveryWindow",
    "code" : "DeliveryWindow"
  } ],
  "code" : "O-ALE-4000",
  "message" : "General allocation error",
  "path" : "",
  "correlationID" : "f47eac44ae1a0a1c"
}
Example allocation-error response containing field and object

An Allocation Error can be returned with extra information, field and object, when they are available and relevant for the allocation error code returned.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "timestamp" : "2024-11-19T14:26:17.916Z",
  "httpStatus" : "400",
  "httpReasonPhrase" : "Bad Request",
  "allocationErrors" : [ {
    "message" : "Value is too low",
    "code" : "TooLow",
    "field" : "logisticsUnits.weight.value",
    "object" : "shipment"
  } ],
  "code" : "O-ALE-4000",
  "message" : "General allocation error",
  "path" : "",
  "correlationID" : "42f9d658f2f9b5f3"
}

2. Workflow

2.1. Basic use case

This is a basic outline of the workflow throughout the MetaPack system when using the API.

The most basic use case is to create a consignment which is achieved by allocating a shipment and subsequently generating the documentation. As shown in this workflow the steps in blue will be performed by the integrator. The steps in green can be automatically done by the MetaPack Manager system or a number of these can also be controlled by the integrator eg Manifesting.

Workflow
Figure 1. Workflow
POST /auth (1)
POST /consignments (2)
GET  /documents/<uuid> (3)

MANIFEST (4)
NOTIFICATIONS (5)
TRACKING (6)
1 Generating a bearer token. For more details about how generate a token see API Security
2 Create consignment by allocating a shipment.
3 Retrieve document to generate label.
4 Manifest will be generated automatically.
5 Send notifications.
6 Provide tracking updates.

Unresolved directive in api.adoc - include::../../../../mm-auth-service/src/docs/asciidoc/overview.adoc[]

3. Resources

The MetaPack API uses the HTTP methods to operate on Resources. The key Resources that exist within the API are:

3.1. Shipments

The following HTTP methods work on the Shipment resource:

HTTP Method URL Action Version

GET

/shipments/<uuid>

Retrieve Shipment with the given <uuid>

[0.6.0,)

3.1.1. Retrieve a shipment

A GET request returns the Shipment identified by the <uuid>.

Request structure
Table 5. /shipments/{uuid}
Path Parameter Description

uuid

<uuid> of the shipment resource to retrieve
Example request
$ curl 'https://example.metapack.com/shipments/a21d2d48-9b58-41c1-8061-e8ebc028fec5' -i -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw'
GET /shipments/a21d2d48-9b58-41c1-8061-e8ebc028fec5 HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw
Host: example.metapack.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2062

{
  "@id" : "https://example.metapack.com/shipments/a21d2d48-9b58-41c1-8061-e8ebc028fec5",
  "type" : "DELIVERY",
  "origin" : {
    "uri" : "http://example.metapack.com/locations/ae931e29-5a0c-453e-b15b-de01e73ff742"
  },
  "receiver" : {
    "address" : {
      "country" : "GBR",
      "city" : "London",
      "street" : "Inn Road",
      "postalCode" : "WC1X 8XZ",
      "@id" : "_:c8c6b713-62c9-495c-81cd-c0cbe0dbeb93",
      "@type" : "Address"
    },
    "contact" : {
      "@id" : "_:30693d2f-c2e4-4d59-8d01-8fb2f92b7150",
      "@type" : "Contact",
      "lastname" : "Neal",
      "phone" : "01234 567890",
      "email" : "example@metapack.com"
    },
    "taxAndDuty" : {
      "eoriNumber" : null,
      "taxId" : null,
      "ukimsNumber" : null
    }
  },
  "sender" : {
    "uri" : "http://example.metapack.com/locations/ae932e29-62c8-453e-b15b-ab01e73ff742"
  },
  "destination" : {
    "address" : {
      "@id" : "_:c2b5d7fe-1ae3-419a-ad9e-b0f7fde7e3d6",
      "@type" : "Address"
    },
    "contact" : {
      "@id" : "_:2d9aad97-566d-48c4-98fe-64a218a90a07",
      "@type" : "Contact"
    }
  },
  "logisticsUnits" : [ {
    "@id" : "642d7689-2aaf-488f-8b36-c131b9b8f106",
    "@type" : "LogisticsUnit",
    "tradeItems" : [ ],
    "weight" : {
      "@type" : "Weight",
      "unit" : "KG",
      "value" : 2.0
    },
    "dimension" : {
      "@type" : "Dimension",
      "unit" : "CM",
      "width" : 5.0,
      "height" : 5.0,
      "depth" : 5.0
    },
    "value" : {
      "@type" : "Monetary",
      "value" : null,
      "currencyCode" : null
    }
  } ],
  "shipmentAttributes" : {
    "limitedQuantity" : false,
    "proofOfDeliveryType" : null,
    "insuranceAmount" : null,
    "cashOnDelivery" : {
      "@id" : "_:dedcb7e7-3a5f-4b20-812c-e35b982314cf",
      "@type" : "CashOnDelivery",
      "value" : {
        "@type" : "Monetary",
        "value" : 0.0,
        "currencyCode" : null
      }
    },
    "identity" : null,
    "twoMan" : null,
    "contentType" : null,
    "shippingCost" : null
  },
  "orders" : [ ]
}

3.2. Consignments

The following HTTP methods work on the Consignment resource:

HTTP Method URL Action Version

POST

/consignments

Allocate Shipment

[0.7.0,)

GET

/consignments/**

Retrieve Consignment with the given <uuid>

[0.6.0,)

DELETE

/consignments/**

Deallocate Consignment with the given <uuid> This can not be called post closing/manifesting of the consignment

[0.9.0,)

PATCH

/consignments/**

Update Status of a single Consignment with a given supported status

[0.14.0,)

PATCH

/consignments

Update the Status of a list of Consignments with a given supported status and a list of consignment URIs

[0.14.0,)

3.2.1. Allocate a shipment or create consignment

Creates a Consignment on a Logistics Service. This will either allocate a Shipment to a Logistics Service using MetaPack allocation logic or create a Consignment on a given Logistics Service. When a Shipment is allocated to a logistics service it becomes consigned and thus a consignment.

If creating a consignment from a shipment then this can be done in two ways:

  1. Supply a Shipment resource URI

  2. Supply the Shipment object its-self

Request structure
Parameter Version Description

logisticsServiceCode

[0.7.0]

Specify if you want to influence how a shipment is allocated to a logistics service.

logisticsServiceURI

[0.7.1,)

Specify if you want to influence how a shipment is allocated to a logistics service.

logisticsServiceGroup

[0.7.0,)

Specify if you want to allocate from a sub-set of available logistics service(s) present in the logistics service group.

latestDeliveryDate

[0.7.0,)

Specify if you want to allocate to a logistics service that is able to deliver on or by the specified date/time.

The JSON payload is a Shipment.

Example request
$ curl 'https://example.metapack.com/consignments?logisticsServiceGroup=Domestic&latestDeliveryDate=2024-11-19T14:26:11.261Z' -i -X POST -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw' -d '{
  "shipmentRef" : "109817271RSHIP",
  "type" : "DELIVERY",
  "origin" : {
    "uri" : "https://example.metapack.com/locations/ae931e29-5a0c-453e-b15b-de01e73ff742"
  },
  "receiver" : {
    "address" : {
      "country" : "GBR",
      "city" : "London",
      "building" : "",
      "companyName" : "Metapack Limited",
      "department" : "",
      "district" : "",
      "doorCode" : "",
      "floor" : "4th",
      "houseNo" : "200",
      "street" : "Gray’s Inn Road",
      "block" : "",
      "houseExt" : "",
      "postalCode" : "WC1X 8XZ",
      "province" : "London",
      "details" : ""
    },
    "contact" : {
      "title" : "Mr",
      "firstname" : "Andrew",
      "lastname" : "Neal",
      "phone" : "01234 567890",
      "email" : "example@metapack.com",
      "timeZone" : "GMT",
      "notifications" : [ {
        "notificationType" : "SMS",
        "value" : "0987654321"
      } ],
      "language" : "fr"
    }
  },
  "sender" : {
    "uri" : "https://example.metapack.com/locations/ae932e29-62c8-453e-b15b-ab01e73ff742"
  },
  "destination" : {
    "address" : {
      "country" : "GBR",
      "city" : "London",
      "building" : "",
      "companyName" : "Metapack Limited",
      "department" : "",
      "district" : "",
      "doorCode" : "",
      "floor" : "4th",
      "houseNo" : "200",
      "street" : "Gray’s Inn Road",
      "block" : "",
      "houseExt" : "",
      "postalCode" : "WC1X 8XZ",
      "province" : "London",
      "details" : ""
    },
    "contact" : {
      "title" : "Mr",
      "firstname" : "Andrew",
      "lastname" : "Neal",
      "phone" : "01234 567890",
      "email" : "example@metapack.com",
      "timeZone" : "GMT",
      "notifications" : [ {
        "notificationType" : "SMS",
        "value" : "0987654321"
      } ],
      "language" : "fr"
    }
  },
  "undeliverable" : {
    "address" : {
      "country" : "GBR",
      "city" : "London",
      "houseNo" : "12 - 14",
      "street" : "Laystall Street",
      "postalCode" : "EC1R 4PF"
    },
    "contact" : {
      "firstname" : "Joe",
      "lastname" : "ShippingLocation",
      "phone" : "612341667",
      "email" : "ShippingLocation@example.com"
    }
  },
  "logisticsUnits" : [ {
    "shipperRef" : "d2a7a620-d7d8-4f0e-b5df-75b91c5c2aeb",
    "weight" : {
      "unit" : "KG",
      "value" : 2.0
    },
    "dimension" : {
      "unit" : "CM",
      "width" : 5.0,
      "height" : 5.0,
      "depth" : 5.0
    },
    "value" : {
      "value" : 5.99,
      "currencyCode" : "EUR"
    }
  } ]
}'
POST /consignments?logisticsServiceGroup=Domestic&latestDeliveryDate=2024-11-19T14:26:11.261Z HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw
Host: example.metapack.com
Content-Length: 2541

{
  "shipmentRef" : "109817271RSHIP",
  "type" : "DELIVERY",
  "origin" : {
    "uri" : "https://example.metapack.com/locations/ae931e29-5a0c-453e-b15b-de01e73ff742"
  },
  "receiver" : {
    "address" : {
      "country" : "GBR",
      "city" : "London",
      "building" : "",
      "companyName" : "Metapack Limited",
      "department" : "",
      "district" : "",
      "doorCode" : "",
      "floor" : "4th",
      "houseNo" : "200",
      "street" : "Gray’s Inn Road",
      "block" : "",
      "houseExt" : "",
      "postalCode" : "WC1X 8XZ",
      "province" : "London",
      "details" : ""
    },
    "contact" : {
      "title" : "Mr",
      "firstname" : "Andrew",
      "lastname" : "Neal",
      "phone" : "01234 567890",
      "email" : "example@metapack.com",
      "timeZone" : "GMT",
      "notifications" : [ {
        "notificationType" : "SMS",
        "value" : "0987654321"
      } ],
      "language" : "fr"
    }
  },
  "sender" : {
    "uri" : "https://example.metapack.com/locations/ae932e29-62c8-453e-b15b-ab01e73ff742"
  },
  "destination" : {
    "address" : {
      "country" : "GBR",
      "city" : "London",
      "building" : "",
      "companyName" : "Metapack Limited",
      "department" : "",
      "district" : "",
      "doorCode" : "",
      "floor" : "4th",
      "houseNo" : "200",
      "street" : "Gray’s Inn Road",
      "block" : "",
      "houseExt" : "",
      "postalCode" : "WC1X 8XZ",
      "province" : "London",
      "details" : ""
    },
    "contact" : {
      "title" : "Mr",
      "firstname" : "Andrew",
      "lastname" : "Neal",
      "phone" : "01234 567890",
      "email" : "example@metapack.com",
      "timeZone" : "GMT",
      "notifications" : [ {
        "notificationType" : "SMS",
        "value" : "0987654321"
      } ],
      "language" : "fr"
    }
  },
  "undeliverable" : {
    "address" : {
      "country" : "GBR",
      "city" : "London",
      "houseNo" : "12 - 14",
      "street" : "Laystall Street",
      "postalCode" : "EC1R 4PF"
    },
    "contact" : {
      "firstname" : "Joe",
      "lastname" : "ShippingLocation",
      "phone" : "612341667",
      "email" : "ShippingLocation@example.com"
    }
  },
  "logisticsUnits" : [ {
    "shipperRef" : "d2a7a620-d7d8-4f0e-b5df-75b91c5c2aeb",
    "weight" : {
      "unit" : "KG",
      "value" : 2.0
    },
    "dimension" : {
      "unit" : "CM",
      "width" : 5.0,
      "height" : 5.0,
      "depth" : 5.0
    },
    "value" : {
      "value" : 5.99,
      "currencyCode" : "EUR"
    }
  } ]
}
Example response
HTTP/1.1 201 Created
Location: https://example.metapack.com/consignments/7464dc6a-631d-47dc-8ac8-97726815204c
Content-Type: application/json;charset=UTF-8
Content-Length: 1015

{
  "@id" : "https://example.metapack.com/consignments/7464dc6a-631d-47dc-8ac8-97726815204c",
  "@type" : "Consignment",
  "deliveryPromise" : {
    "earliestCollectionDate" : "2016-11-07T00:00:00Z",
    "latestCollectionDate" : "2016-11-07T23:59:59Z",
    "earliestDeliveryDate" : "2016-11-08T06:31:00Z",
    "latestDeliveryDate" : "2016-11-08T17:00:00Z",
    "logisticsService" : "https://example.metapack.com/shipper-service/23991e90-8352-496c-9041-73a3a8cbd3dd"
  },
  "logisticsUnitDocuments" : [ {
    "@id" : "https://example.metapack.com/shipments/7464dc6a-631d-47dc-8ac8-97726815204c/293ea6b3-af2d-4621-ba98-d7082bfa775f",
    "@type" : "LogisticsUnit",
    "trackingCode" : "TT123456789GB",
    "documents" : [ {
      "type" : "label",
      "url" : "https://example.metapack.com/documents/7464dc6a-631d-47dc-8ac8-97726815204c/293ea6b3-af2d-4621-ba98-d7082bfa775f/label"
    } ]
  } ],
  "documents" : [ ],
  "shipmentUrl" : "https://example.metapack.com/shipments/7464dc6a-631d-47dc-8ac8-97726815204c"
}
Example response (with return label)

  • Return label feature is supported only in Content-Type: application/vnd.metapack.mm.v1.0+json or higher.

  • The response below showcases returnLogisticsUnitDocuments which contains the return label.

HTTP/1.1 201 Created
Location: https://example.metapack.com/consignments/3912de3a-4db2-4745-b854-61e181e4ffba
Content-Type: application/json;charset=UTF-8
Content-Length: 1541

{
  "@id" : "https://example.metapack.com/consignments/3912de3a-4db2-4745-b854-61e181e4ffba",
  "@type" : "Consignment",
  "deliveryPromise" : {
    "earliestCollectionDate" : "2019-07-28T00:00:00Z",
    "latestCollectionDate" : "2019-07-28T23:59:59Z",
    "earliestDeliveryDate" : "2019-07-30T00:00:00Z",
    "latestDeliveryDate" : "2019-07-30T23:59:59Z",
    "logisticsService" : "https://data.metapack.net/shipper-services/dpdrev"
  },
  "logisticsUnitDocuments" : [ {
    "@id" : "https://example.metapack.com/shipments/3912de3a-4db2-4745-b854-61e181e4ffba/86d864d5-8f24-4426-8f1b-29827de0a582",
    "@type" : "LogisticsUnit",
    "shipperRef" : "116d1054-437d-42f6-a725-ffc2a078dd7e",
    "trackingCode" : "%WC1X8XZ15504332501739912826",
    "documents" : [ {
      "type" : "label",
      "url" : "https://example.metapack.com/documents/3912de3a-4db2-4745-b854-61e181e4ffba/86d864d5-8f24-4426-8f1b-29827de0a582/label"
    } ]
  } ],
  "returnLogisticsUnitDocuments" : [ {
    "@id" : "https://example.metapack.com/shipments/3912de3a-4db2-4745-b854-61e181e4ffba/1643518b-0097-455d-9504-45e0d7b81c24",
    "@type" : "LogisticsUnit",
    "shipperRef" : "109817271RSHIP",
    "trackingCode" : "%SW1E5NN15501234005810855826",
    "documents" : [ {
      "type" : "label",
      "url" : "https://example.metapack.com/documents/3912de3a-4db2-4745-b854-61e181e4ffba/1643518b-0097-455d-9504-45e0d7b81c24/label"
    } ]
  } ],
  "documents" : [ ],
  "shipmentUrl" : "https://example.metapack.com/shipments/3912de3a-4db2-4745-b854-61e181e4ffba"
}

3.2.2. Retrieve a consignment

Returns the given Consignment

Request structure
Table 6. /consignments/{uuid}
Path Parameter Description

uuid

<uuid> of the consignment resource to retrieve
Example request
$ curl 'https://example.metapack.com/consignments/7464dc6a-631d-47dc-8ac8-97726815204c' -i -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw'
GET /consignments/7464dc6a-631d-47dc-8ac8-97726815204c HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw
Host: example.metapack.com
Example response
Dates will always be represented in ISO 8601 format 
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1015

{
  "@id" : "https://example.metapack.com/consignments/7464dc6a-631d-47dc-8ac8-97726815204c",
  "@type" : "Consignment",
  "deliveryPromise" : {
    "earliestCollectionDate" : "2016-11-07T00:00:00Z",
    "latestCollectionDate" : "2016-11-07T23:59:59Z",
    "earliestDeliveryDate" : "2016-11-08T06:31:00Z",
    "latestDeliveryDate" : "2016-11-08T17:00:00Z",
    "logisticsService" : "https://example.metapack.com/shipper-service/23991e90-8352-496c-9041-73a3a8cbd3dd"
  },
  "logisticsUnitDocuments" : [ {
    "@id" : "https://example.metapack.com/shipments/7464dc6a-631d-47dc-8ac8-97726815204c/293ea6b3-af2d-4621-ba98-d7082bfa775f",
    "@type" : "LogisticsUnit",
    "trackingCode" : "TT123456789GB",
    "documents" : [ {
      "type" : "label",
      "url" : "https://example.metapack.com/documents/7464dc6a-631d-47dc-8ac8-97726815204c/293ea6b3-af2d-4621-ba98-d7082bfa775f/label"
    } ]
  } ],
  "documents" : [ ],
  "shipmentUrl" : "https://example.metapack.com/shipments/7464dc6a-631d-47dc-8ac8-97726815204c"
}

3.2.3. Deallocate a consignment

Deallocating a Consignment is analogous to deleting a consignment. The operation also deletes the shipment associated with the consignment.

Example request
$ curl 'https://example.metapack.com/consignments/0c2b3761-3b22-41d2-8721-1e51e27d1faf' -i -X DELETE -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw'
DELETE /consignments/0c2b3761-3b22-41d2-8721-1e51e27d1faf HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw
Host: example.metapack.com
Example response
HTTP/1.1 204 No Content

3.2.4. Update status of consignments

There are 2 ways to update the status of consignments:

  1. Update a consignment by ID (single update)

  2. Update a list of consignments (batch update)

The supported statuses that a consignment can be updated to is specified by AcceptableConsignmentStatus

Update the status of a single consignment

The JSON payload is a Consignment Status.

Example request
$ curl 'https://example.metapack.com/consignments/7464dc6a-631d-47dc-8ac8-97726815204c' -i -X PATCH -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw' -d '{
  "status" : "READY_TO_MANIFEST"
}'
PATCH /consignments/7464dc6a-631d-47dc-8ac8-97726815204c HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw
Host: example.metapack.com
Content-Length: 36

{
  "status" : "READY_TO_MANIFEST"
}
Example response
HTTP/1.1 200 OK
Update the status of a list of consignments

The JSON payload is a Consignment Status Batch.

Example request
$ curl 'https://example.metapack.com/consignments' -i -X PATCH -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw' -d '{
  "consignments" : [ "https://example.metapack.com/consignments/5dc46ce0-00f9-4973-b956-661b22b08c83", "https://example.metapack.com/consignments/611d45ab-1c06-4e75-b64e-1dda8c9b72e4" ],
  "status" : "READY_TO_MANIFEST"
}'
PATCH /consignments HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw
Host: example.metapack.com
Content-Length: 223

{
  "consignments" : [ "https://example.metapack.com/consignments/5dc46ce0-00f9-4973-b956-661b22b08c83", "https://example.metapack.com/consignments/611d45ab-1c06-4e75-b64e-1dda8c9b72e4" ],
  "status" : "READY_TO_MANIFEST"
}
Example response full update

When all the consignments in the request were successfully updated the following response is returned

HTTP/1.1 200 OK
Example response partial update

When at least one consignment in the request was successfully updated (but not all of the consignments) then the following response is returned

HTTP/1.1 207 Multi-Status

3.3. Consignment-Lists

Consignment list represents a set of consignments, with a type associated. For example, creating a list with the type "CLOSE_LIST" will close all the consignments in that list.

The following HTTP methods work on the Consignment-lists resource:

HTTP Method URL Action Version

POST

/consignment-lists

Close Consignment List

[0.13.0,)

3.3.1. Close a consignment list

Creates a Consignment List with a type, representing the action to execute on this list of consignments. A Consignment List Reference is returned.

Request structure

The JSON payload is a Consignment List.

Example request
$ curl 'https://example.metapack.com/consignment-lists' -i -X POST -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw' -d '{
  "type" : "CLOSE_LIST",
  "consignments" : [ "https://example.metapack.com/consignments/7464dc6a-631d-47dc-8ac8-97726815204c", "https://example.metapack.com/consignments/7464dc6a-631d-4742-8a42-97726815424a" ],
  "consignmentListId" : "My Reference number"
}'
POST /consignment-lists HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJX.....mPd7_RTPw
Host: example.metapack.com
Content-Length: 261

{
  "type" : "CLOSE_LIST",
  "consignments" : [ "https://example.metapack.com/consignments/7464dc6a-631d-47dc-8ac8-97726815204c", "https://example.metapack.com/consignments/7464dc6a-631d-4742-8a42-97726815424a" ],
  "consignmentListId" : "My Reference number"
}
Example response
HTTP/1.1 201 Created
Location: https://example.metapack.com/consignment-lists/6
Content-Type: application/json;charset=UTF-8
Content-Length: 136

{
  "@id" : "https://example.metapack.com/consignment-lists/6",
  "type" : "CLOSE_LIST",
  "consignmentListId" : "My Reference number"
}

3.4. Documents

Documents represent labels and paperwork that are required by the whole consignment or specifically on a logistics unit.

This could include a label and potentially customs documentation with commercial invoices for international consignments. The customs declaration documentation (CN22 or CN23) will always be in the same format as the label. The commercial invoice will be in PDF format.

The following HTTP methods work on the Document resource:

HTTP Method URL Action Version

GET

/documents/**

Retrieve documentation.

[0.6.0,)

3.4.1. Retrieve documentation

Returns any type of documentation. The exact URL will be provided to you by the LogisticsUnitDocument object in the Consignment object.

Request structure
Parameter Version Description

format

[0.6.0,)

The format of the label from the Acceptable Label Formats. Default: PDF

dpi

[0.6.0,)

DPI required (for ZPL & PNG formats). Acceptable DPI values.
Example request
$ curl 'https://example.metapack.com/documents/23559ad7/d662/4687/a88e/bc446737227c/4efa093a-d77b-4de3-b55a-ba6f2d073c96/label?format=ZPL&dpi=200' -i -H 'Content-Type: application/vnd.metapack.mm.v0+json' -H 'Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw'
GET /documents/23559ad7/d662/4687a88e/bc446737227c/4efa093a-d77b-4de3-b55a-ba6f2d073c96/label?format=ZPL&dpi=200 HTTP/1.1
Content-Type: application/vnd.metapack.mm.v0+json
Authorization: Bearer eyJhbGciOiJI.....mPd7_RTPw
Host: example.metapack.com
Example response
HTTP/1.1 200 OK
Content-Length: 24
Content-Type: text/zpl

ZPL PAYLOAD WILL BE HERE

3.5. Logistics Services

The Logistics Service endpoint is hosted on data.metapack.net. See example-request section below for full URL.

The following HTTP methods apply to the endpoint:

HTTP Method URL Action

GET

/logistics-services/<uuid>

Retrieve Logistics Service with the given <uuid>

3.5.1. Retrieve a logistics service

A GET request returns the Logistics Service identified by the <uuid>.

Request structure
Table 7. /logistics-services/{uuid}
Path Parameter Description

uuid

<uuid> of the logistics service resource to retrieve
Example request
$ curl 'https://data.metapack.net/logistics-services/49ddd5d;SAFE'
GET /logistics-services/49ddd5d;SAFE HTTP/1.1
Host: data.metapack.net
Example response
HTTP/1.1 200 OK
x-amz-id-2: KMZqGDFTc/zdHvefxGpv67x8XxEwEoq8KPJ6OfKxf5Q7YDOPJoCxrF8YRP25d3vMdrZE7OCnGos=
x-amz-request-id: 804ADE21948672C0
Date: Fri, 13 May 2016 10:54:49 GMT
Last-Modified: Thu, 12 May 2016 10:37:36 GMT
ETag: "b87cb1e49071e421522b22c91f7c5c24"
Accept-Ranges: bytes
Content-Type: application/json;charset=UTF-8
Content-Length: 531
Server: AmazonS3

{
    "@id": "https://data.metapack.net/logistics-services/49ddd5d;SAFE",
    "@type": "LogisticsService",
    "baseLogisticsService": "https://data.metapack.net/logistics-services/49ddd5d",
    "complimentaryServices": [
        {
            "code": "SAFE",
            "description": "Left in a safe place",
            "name": "Safe place"
        }
    ],
    "description": "GB trackable 48-hour (High Volume).",
    "logisticsProvider": "https://data.metapack.net/logistics-providers/ca02720",
    "name": "Tracked 48 HV"
}

Appendix A: Object Data Elements

A.1. Address

An addressable location. An address’s format will be validated as described in Appendix Required Address Fields.

Path Type Constraints Accepted values Required for Version Description

country

String

Mandatory. Size must be between 3 and 3 inclusive

ISO 3166 Country codes

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The country code allows us to work out if an address is domestic or international

city

String

Size must be between 0 and 40 inclusive

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The town / city of the address

building

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting

[0.6.0,)

The building name of the address

companyName

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting

[0.6.0,)

The company name of the address

department

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting

[0.6.0,)

The department of the company of the address

district

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting

[0.6.0,)

The district of the address

doorCode

String

Size must be between 0 and 40 inclusive

Tbd

[0.6.0,)

The door code of the address

floor

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting

[0.6.0,)

The floor of the building of the address

houseNo

String

Size must be between 0 and 16 inclusive

Documentation, Manifesting

[0.6.0,)

The house number of the address

street

String

Size must be between 0 and 100 inclusive

Documentation, Manifesting

[0.6.0,)

The street of the address

block

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting

[0.6.0,)

The block of the address

houseExt

String

Size must be between 0 and 16 inclusive

Documentation, Manifesting

[0.6.0,)

The house extension of the address

postalCode

String

Size must be between 0 and 16 inclusive

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The postal code of the address. Only if country supports it.

province

String

Size must be between 0 and 50 inclusive

Documentation, Manifesting

[0.6.0,)

The province of the address. If slashes are present, up to 2 slashes are permitted.

details

String

Size must be between 0 and 100 inclusive

Documentation, Manifesting

[0.6.0,)

Additional information describing the address

A.2. Agent

A Recipient, ShippingLocation or Seller are subclasses of Agent.

Path Type Constraints Accepted values Required for Version Description

ref

String

Size must be between 0 and 20 inclusive

Documentation, Manifesting

[0.6.0,)

Agent’s reference (specified by the Seller or Shipper)

contact

Contact

Mandatory

Documentation, Notifications

[0.6.0,)

Agent’s contact

address

Address

Mandatory

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

Agent’s address

A.3. Agent URI

A URI representing an Agent

Path Type Constraints Accepted values Required for Version Description

uri

String

Size must be between 0 and 2000 inclusive. The URI must be valid

Documentation

[0.7.5,)

URI where the agent’s address and contact details can be retrieved.

A.4. Cash On Delivery

Path Type Constraints Accepted values Required for Version Description

value

Monetary

Mandatory

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The monetary value of the Cash On Delivery payment that should be collected

specialInstruction

String

Size must be between 0 and 250 inclusive

Documentation

[0.6.0,)

Special instructions that pertain to the Cash on Delivery Payment process.

A.5. Complimentary Service

Path Type Description

code

String

The complimentary service’s code.

name

String

The complimentary service’s name.

description

String

The complimentary service’s description.

A.6. Consignment

Path Type Version Description

@id

String

[0.6.0,)

Used to uniquely identify things within the document with URIs or blank node identifiers.

@type

String

[0.6.0,)

Used to set the data type of a node or typed value.

logisticsUnitDocuments

Logistics Unit Document[]

[0.6.0,)

Logistics Unit Document

returnLogisticsUnitDocuments

Logistics Unit Document[]

[1.0,)

Logistics Unit Document

documents

Document[]

[0.6.0,)

Documents required for this Consignment

shipmentUrl

String

[0.6.0,)

Reference to the shipment this consignment contains.

allocatedDate

Date

[0.6.0,)

The date on which the consignment was allocated.

cutOffDate

Date

[0.6.0,)

The cut off date in the shipping location that the consignment needs to be packed by.

deliveryPromise

Delivery Promise

[0.6.0,)

Delivery Promise

shippingCost

Monetary

[0.6.0,)

The cost of shipping the consignment

A.7. Consignment List

Path Type Constraints Accepted values Required for Version Description

type

String

Mandatory

Acceptable Consignment List Type

Manifesting

[0.13.0,)

The type of consignment list. See Acceptable Consignment List Type.

consignments

List of URI

Mandatory. Size must be between 1 and 1000 inclusive

Manifesting

[0.13.0,)

The list of consignment URIs.

consignmentListId

String

Size must be between 0 and 40 inclusive

Manifesting

[0.13.0,)

The consignment list identifier. Supplied by the Shipper.

A.8. Consignment List Reference

Path Type Version Description

type

String

[0.13.0,)

The type of consignment list. See Acceptable Consignment List Type.

@id

String

[0.13.0,)

Used to uniquely identify the consignment list.

consignmentListId

String

[0.13.0,)

The consignment list identifier. Supplied by the Shipper.

A.9. Consignment Status

Path Type Constraints Accepted values Required for Version Description

status

AcceptableConsignmentStatus

Mandatory

Tbd

[0.14.0,)

The status that the consignment will be updated to.

A.10. Consignment Status batch

Path Type Constraints Accepted values Required for Version Description

status

AcceptableConsignmentStatus

Mandatory

Tbd

[0.14.0,)

The status that the consignments will be updated to.

consignments

List of URI

Mandatory. Size must be between 1 and 1000 inclusive

Tbd

[0.14.0,)

The list of consignment URIs.

A.11. Constraint Violation

Table 8. Constraint violation content
Path Type Version Description

field

String

The affected field of the object.

rejectedValue

String

The rejected field value.

bindingFailure

Boolean

Whether this error represents a binding failure (like a type mismatch); else, it is a validation failure.

code

String

The code associated with this constraint violation. See full list of constraint violation codes.

message

String

A textual error message.

objectName

String

The name of the affected object.

A.12. Allocation Error

Table 9. Allocation error content
Path Type Version Description

code

String

[0.11.0,)

The allocation error code.

message

String

[0.11.0,)

A human readable error message.

object

String

[0.11.0,)

The name of the affected object. This information will be present only if relevant for the returned allocation error code.

field

String

[0.11.0,)

The path of the rejected field. This information will be present only if relevant for the returned allocation error code.

A.13. Contact

Path Type Constraints Accepted values Required for Version Description

title

String

Size must be between 0 and 50 inclusive

Documentation, Manifesting, Notifications

[0.6.0,)

The title of the contact.

firstname

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting, Notifications

[0.6.0,)

The first name of the contact, mandatory if the last name field is not provided.

lastname

String

Size must be between 0 and 40 inclusive

Documentation, Manifesting, Notifications

[0.6.0,)

The last name of the contact, mandatory if the first name field is not provided.

phone

String

Size must be between 0 and 30 inclusive

Notifications

[0.6.0,)

The phone number by which the contact can be reached.

email

String

Size must be between 0 and 50 inclusive

Notifications

[0.6.0,)

The email address by which the contact can be reached.

timeZone

String

Must be a valid time-zone ID

See Time Zones for valid zone ids

Notifications

[0.6.0,)

TimeZone in which the contact resides. Used to prevent SMS or emails notifications waking a contact during the night.

language

String

Must be a valid ISO 639-1 language code

Notifications

[0.6.0,)

The language code of the shipment so that communications can be managed in the appropriate language as well as for system translations. ISO 639-1 Code

notifications

Notification[]

Size must be between 0 and 8 inclusive

Notifications

[0.6.0,)

a list of notifications that the contact should receive.

A.14. Delivery Promise

Path Type Version Description

earliestCollectionDate

Date

[0.6.0,)

The earliest collection date/time.

latestCollectionDate

Date

[0.6.0,)

The latest collection date/time.

earliestDeliveryDate

Date

[0.6.0,)

The earliest delivery date/time.

latestDeliveryDate

Date

[0.6.0,)

The time that the delivery is guaranteed to be completed.

logisticsService

LogisticsService

[0.6.0,)

A LogisticsService.

A.15. Destination

A.15.1. Destination (Collection)

The physical location the shipment will be delivered to.

Path Type Constraints Accepted values Required for Version Description

uri

String

Size must be between 0 and 2000 inclusive. The URI must be valid

Allocation, Documentation

[0.7.2,)

URI from which location details can be retrieved. Subject to ValidTypeAndDestinationCombination validation.

collectionPointID

String

Size must be between 0 and 36 inclusive

Allocation, Documentation

[0.7.5,)

Identifier for a store or PUDO location. Subject to ValidTypeAndDestinationCombination validation.

collectionPointProviderID

String

Size must be between 0 and 36 inclusive

Allocation, Documentation

[0.7.5,)

Identifier for a provider of stores and/or PUDO locations. Subject to ValidTypeAndDestinationCombination validation.

contact

Contact

Documentation, Notifications

[0.6.0,)

Destination’s contact. Subject to ValidTypeAndDestinationCombination validation.

address

Address

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

Destination’s address. Subject to ValidTypeAndDestinationCombination validation.

A.15.2. Destination (Delivery)

The logical location the shipment will be delivered to

Path Type Constraints Accepted values Required for Version Description

contact

Contact

Documentation, Notifications

[0.6.0,)

Destination’s contact. Mandatory. Subject to ValidTypeAndDestinationCombination validation.

address

Address

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

Destination’s address. Mandatory. Subject to ValidTypeAndDestinationCombination validation.

A.16. Dimension

Path Type Constraints Accepted values Required for Version Description

width

Number

Mandatory. Must be at least 0. Must have at most 3 integral digits and 0 fractional digits

Tbd

[0.6.0,)

The width of the logistics unit

height

Number

Mandatory. Must be at least 0. Must have at most 3 integral digits and 0 fractional digits

Tbd

[0.6.0,)

The height of the logistics unit

depth

Number

Mandatory. Must be at least 0. Must have at most 3 integral digits and 0 fractional digits

Tbd

[0.6.0,)

The depth of the logistics unit

unit

String

Mandatory

Acceptable Measurement

Tbd

[0.6.0,)

The unit of measurement that the dimensions are passed in, in one of the Acceptable Measurement formats.

A.17. Document

Path Type Version Description

url

String

[0.6.0,)

URL to the document

type

DocumentType

[0.6.0,)

Type of document available e.g. label, customs, cash on delivery form

A.18. Hazardous Trade Item

Path Type Constraints Accepted values Required for Version Description

@type

String

HazardousTradeItem

Documentation, Manifesting

[0.6.0,)

Type of trade item.

countryOfOrigin

String

Mandatory. Size must be between 3 and 3 inclusive

ISO 3166 Country codes

Documentation, Manifesting

[0.6.0,)

ISO-3166 Country code for the country of origin.

fabricContent

String

Mandatory. Size must be between 0 and 250 inclusive

Documentation, Manifesting

[0.6.0,)

Details of the fabric content.

harmonisedCode

String

Mandatory. Size must be between 0 and 50 inclusive

Documentation, Manifesting

[0.6.0,)

The harmonised code.

productCode

String

Mandatory. Size must be between 0 and 50 inclusive

Documentation, Manifesting

[0.6.0,)

The code of the product.

description

String

Mandatory. Size must be between 0 and 250 inclusive

Documentation, Manifesting

[0.6.0,)

The description of the product.

quantity

Number

Mandatory. Must have at most 12 integral digits and 0 fractional digits

Documentation, Manifesting

[0.6.0,)

The quantity of products.

This must be more than zero.

productType

String

Mandatory. Size must be between 0 and 250 inclusive

Documentation, Manifesting

[0.6.0,)

The product type.

unitValue

Monetary

Mandatory

Documentation, Manifesting

[0.6.0,)

The monetary value of an individual product.

unitWeight

Weight

Mandatory

Documentation, Manifesting

[0.6.0,)

The weight of an individual product.

codes

String[]

Element size must not exceed 250 chars.. Mandatory. Size must be between 0 and 10 inclusive

Documentation, Manifesting

[0.6.0,)

Hazardous Materials Codes

materialAttributes

HazardousMaterialAttribute[]

Mandatory. Size must be between 0 and 10 inclusive

LIQUID, AEROSOL

Documentation, Manifesting

[0.6.0,)

What attributes does the material have: liquid, aerosol …​etc

A.19. Identity

Path Type Constraints Accepted values Required for Version Description

typeOfDocument

String

Mandatory. Size must be between 0 and 60 inclusive

Tbd

[0.6.0,)

Type of document provided to verify identity.

photo

Boolean

Tbd

[0.6.0,)

Photo provided or not.

A.20. Logistics Service

Path Type Present Description

@id

String

Always

Used to uniquely identify items within the document with URIs or blank node identifiers.

@type

String

Always

Used to set the data type of a node or typed value.

baseLogisticsService

String

Always

URL of the base logistics-service.

name

String

Always

The name of the logistics-service, e.g. 'Tracked 48 HV'

description

String

Always

Describes the logistics-service.

logisticsProvider

String

Always

Logistics-provider’s identification URL.

complimentaryServices

Complimentary Service[]

Conditionally

One or more Complimentary Services.

A.21. Logistics Unit

Logistics Units are the items that are to be shipped - eg the parcels, pallets, cages etc.

Path Type Constraints Accepted values Required for Version Description

shipperRef

String

Size must be between 0 and 100 inclusive

Tbd

[0.6.0,)

The carton identifier where this logistics Unit should be packed. Supplied by the Shipper.

tradeItems

List of TradeItem

Size must be between 0 and 20 inclusive

Documentation

[0.6.0,)

Information about the trade items (products) in the Shipment Item, eg SKU, Harmonization Code, quantity.

packageType

String

Size must be between 0 and 50 inclusive

Tbd

[0.6.0,)

The packaging type e.g. Parcel, Pallet, Cage.

shipmentProperties

Map

Key size must not exceed 30 chars. Value size must not exceed 100 chars. Size must be between 0 and 10 inclusive

Tbd

[0.6.0,)

Properties of the Logistic Unit defined by the mm/shipper in configuration.

weight

Weight

Mandatory

Allocation, Delivery options, Documentation

[0.6.0,)

The weight of the shipment, if Trade Items are supplied then the aggregated weights from here will be taken.

If both Trade Item Weight and Logistics Unit weight are supplied, then the Logistics Unit weight will be taken.

dimension

Dimension

Mandatory

Allocation, Delivery options

[0.6.0,)

The dimensions of the logistics item.

value

Monetary

Allocation, Delivery options, Documentation

[0.6.0,)

The monetary value of the logistics unit.

A.22. Logistics Unit Document

Path Type Version Description

@id

String

[0.6.0,)

Used to uniquely identify things within the document with URIs or blank node identifiers.

@type

String

[0.6.0,)

Used to set the data type of a node or typed value.

shipperRef

class java.lang.String

[0.6.0,)

The carton identifier where this logistics Unit should be packed. Supplied in the Shipment on the Shipper object by the Shipper.

trackingCode

String

[0.6.0,)

The Logistics Service Specific Tracking identifier. This is the code returned by the Logistics Provider.

trackingUrl

class java.lang.String

[0.6.0,)

The URL for tracking the Logistics Service.

documents

Document[]

[0.6.0,)

Documents required for this Logistics Unit

A.23. Monetary

Path Type Constraints Accepted values Required for Version Description

value

Number

Mandatory. Must have at most 12 integral digits and 2 fractional digits

Tbd

[0.6.0,)

The amount.

currencyCode

String

Mandatory. Size must be between 0 and 3 inclusive

Tbd

[0.6.0,)

The currencyCode in which the amount is specified.

A.24. Notification

Path Type Constraints Accepted values Required for Version Description

notificationType

String

SMS, EMAIL, PHONE

Notifications

[0.6.0,)

The Type of notification that the contact should receive.

value

String

Size must be between 0 and 50 inclusive

Notifications

[0.6.0,)

The phone number for a phone or SMS notification, the email address for email notification.

A.25. Order

Path Type Constraints Accepted values Required for Version Description

number

String

Size must be between 0 and 250 inclusive

Documentation

[0.6.0,)

The order number of the shipment. Typically this is the reference provided to the recipient of the goods during the transaction.

value

Monetary

Tbd

[0.6.0,)

The value of the order - not necessarily the same as the value of the entire shipment.

date

Date

Must be a supported date-time format. Must be in the past

An ISO 8601 date or date-time (see Dates and times).

Notifications

[0.6.0,)

The date that the order was placed.

orderProperties

Map

Key size must not exceed 30 chars. Value size must not exceed 100 chars. Size must be between 0 and 10 inclusive

Documentation, Manifesting, Notifications

[0.6.0,)

Bespoke orderProperties configured by the shipper.

A.26. Receiver

A.26.1. Receiver (Collection)

The logical location the shipment will be delivered to.

Path Type Constraints Accepted values Required for Version Description

uri

String

Size must be between 0 and 2000 inclusive. The URI must be valid

Allocation

[0.7.1]

Either a URI or an address and contact must be provided - see ValidTypeAndReceiverCombination

contact

Contact

Documentation, Notifications

[0.6.0,)

Either a URI or an address and contact must be provided - see ValidTypeAndReceiverCombination

address

Address

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

Either a URI or an address and contact must be provided - see ValidTypeAndReceiverCombination

A.26.2. Receiver (Delivery)

The physical location the shipment will be delivered to.

Path Type Constraints Accepted values Required for Version Description

contact

Contact

Documentation, Notifications

[0.6.0,)

Receiver’s contact. This field is mandatory, a contact must be provided - see ValidTypeAndReceiverCombination

address

Address

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

Receiver’s address. This field is mandatory, an address must be provided - see ValidTypeAndReceiverCombination

A.27. Shipment

A.27.1. Collection Shipment

Path Type Constraints Accepted values Required for Version Description

shipmentRef

String

Size must be between 0 and 40 inclusive

Allocation

[0.6.0,)

Reference to a shipment that seller can provide, using which they can reconcile shipment with their own system.

type

String

Mandatory

COLLECTION

Allocation, Delivery options

[0.6.0,)

The type of shipment from Acceptable Shipment Types.

undeliverable

Agent

Documentation

[0.6.0,)

Undeliverable is an Agent.

The address that the items should be returned to in case they are unable to be delivered. Supplied if the undeliverable details are different from the origin or sender details.

logisticsUnits

LogisticsUnit[]

Mandatory. Size must be between 1 and 10 inclusive

Allocation, Delivery options, Documentation, Manifesting, Notifications

[0.6.0,)

Collection of Logistic Unit. It is mandatory to declare logisticsUnits as they form the item count for the consignment.

shipmentProperties

Map

Key size must not exceed 30 chars. Value size must not exceed 100 chars. Size must be between 0 and 10 inclusive

Documentation, Manifesting, Notifications

[0.6.0,)

Bespoke shipmentProperties configured by the shipper.

shipmentAttributes

ShipmentAttributes

Tbd

[0.6.0,)

These are flags about the shipment, eg Proof of Delivery Required, Cash On Delivery, Identity etc.

orders

Order[]

Size must be between 0 and 1 inclusive

Tbd

[0.6.0,)

Collection of orders that the shipment is associated to.

specialDeliveryInstructions

String

Size must be between 0 and 512 inclusive

Tbd

[0.6.0,)

Instructions that should go to the logistics provider to help with the delivery of the shipment.

incoterms

IncotermsType

EXW, FCA, CPT, CIP, DAT, DAP, DDP, FAS, FOB, CFR, CIF

Tbd

[0.6.0,)

When shipping internationally the incoterms are assumed to be those that are configured against the shipping location. Specification here will overwrite the configuration.

origin

AgentURI

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The physical location the shipment will be sent from. It’s optional because the shipment can be dropped-off at an unspecified PUDO. Often it will be a ShippingLocation.

receiver

Receiver (Collection)

Mandatory

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The logical agent or organisation the shipment will be delivered to.

sender

AgentURI

Mandatory

Documentation, Manifesting

[0.6.0,)

The logical agent or organisation that is sending the shipment. This is often the Seller.

destination

Destination (Collection)

Mandatory

Documentation, Manifesting, Notifications

[0.6.0,)

The physical location that will be receiving the shipment.

A.27.2. Delivery Shipment

Path Type Constraints Accepted values Required for Version Description

shipmentRef

String

Size must be between 0 and 40 inclusive

Allocation

[0.6.0,)

Reference to a shipment that seller can provide, using which they can reconcile shipment with their own system.

type

String

Mandatory

DELIVERY

Allocation, Delivery options

[0.6.0,)

The type of shipment from Acceptable Shipment Types.

undeliverable

Agent

Documentation

[0.6.0,)

Undeliverable is an Agent.

The address that the items should be returned to in case they are unable to be delivered. Supplied if the undeliverable details are different from the origin or sender details.

logisticsUnits

LogisticsUnit[]

Mandatory. Size must be between 1 and 10 inclusive

Allocation, Delivery options, Documentation, Manifesting, Notifications

[0.6.0,)

Collection of Logistic Unit. It is mandatory to declare logisticsUnits as they form the item count for the consignment.

shipmentProperties

Map

Key size must not exceed 30 chars. Value size must not exceed 100 chars. Size must be between 0 and 10 inclusive

Documentation, Manifesting, Notifications

[0.6.0,)

Bespoke shipmentProperties configured by the shipper.

shipmentAttributes

ShipmentAttributes

Tbd

[0.6.0,)

These are flags about the shipment, eg Proof of Delivery Required, Cash On Delivery, Identity etc.

orders

Order[]

Size must be between 0 and 1 inclusive

Tbd

[0.6.0,)

Collection of orders that the shipment is associated to.

specialDeliveryInstructions

String

Size must be between 0 and 512 inclusive

Tbd

[0.6.0,)

Instructions that should go to the logistics provider to help with the delivery of the shipment.

incoterms

IncotermsType

EXW, FCA, CPT, CIP, DAT, DAP, DDP, FAS, FOB, CFR, CIF

Tbd

[0.6.0,)

When shipping internationally the incoterms are assumed to be those that are configured against the shipping location. Specification here will overwrite the configuration.

origin

AgentURI

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The physical location the shipment will be sent from. It’s optional because the shipment can be dropped-off at an unspecified PUDO. Often it will be a ShippingLocation.

receiver

Receiver (Delivery)

Mandatory

Allocation, Delivery options, Documentation, Manifesting

[0.6.0,)

The physical location the shipment will be delivered to.

sender

AgentURI

Mandatory

Documentation, Manifesting

[0.6.0,)

The logical agent or organisation that is sending the shipment. This is often the Seller.

destination

Destination (Delivery)

Mandatory

Documentation, Manifesting, Notifications

[0.6.0,)

The logical agent or organisation that will be receiving the shipment. This is often the Recipient, but may be the Seller for returned shipments.

A.28. ShipmentAttributes

Path Type Constraints Accepted values Required for Version Description

limitedQuantity

Boolean

Tbd

[0.6.0,)

Whether or not the shipment contains limited quantities of hazardous goods.

proofOfDeliveryType

ProofOfDeliveryType

Tbd

[0.6.0,)

Specify the proof-of-delivery type. If this field is not provided, then the service returned will not be filtered by this attribute.

insuranceAmount

Monetary

Tbd

[0.6.0,)

The insurable value of the shipment.

cashOnDelivery

CashOnDelivery

Tbd

[0.6.0,)

If payment is to be made on delivery, the details of that payment are specified here.

identity

Identity

Tbd

[0.6.0,)

The document provided for proof of identity.

twoMan

Boolean

Tbd

[0.7.0,)

Whether or not the shipment needs to be allocated to a logistics service that has a two man delivery option

contentType

Enum

Tbd

[0.6.0,)

Type of parcel content

shippingCost

Monetary

Tbd

[0.6.0,)

Additional price of shipping

A.29. Trade Item

Path Type Constraints Accepted values Required for Version Description

@type

String

TradeItem

Documentation, Manifesting

[0.6.0,)

Type of trade item.

countryOfOrigin

String

Mandatory. Size must be between 3 and 3 inclusive

ISO 3166 Country codes

Documentation, Manifesting

[0.6.0,)

ISO-3166 Country code for the country of origin.

fabricContent

String

Mandatory. Size must be between 0 and 250 inclusive

Documentation, Manifesting

[0.6.0,)

Details of the fabric content.

harmonisedCode

String

Mandatory. Size must be between 0 and 50 inclusive

Documentation, Manifesting

[0.6.0,)

The harmonised code.

productCode

String

Mandatory. Size must be between 0 and 50 inclusive

Documentation, Manifesting

[0.6.0,)

The code of the product.

description

String

Mandatory. Size must be between 0 and 250 inclusive

Documentation, Manifesting

[0.6.0,)

The description of the product.

quantity

Number

Mandatory. Must have at most 12 integral digits and 0 fractional digits

Documentation, Manifesting

[0.6.0,)

The quantity of products.

This must be more than zero.

productType

String

Mandatory. Size must be between 0 and 250 inclusive

Documentation, Manifesting

[0.6.0,)

The product type.

unitValue

Monetary

Mandatory

Documentation, Manifesting

[0.6.0,)

The monetary value of an individual product.

unitWeight

Weight

Mandatory

Documentation, Manifesting

[0.6.0,)

The weight of an individual product.

A.30. Weight

Path Type Constraints Accepted values Required for Version Description

value

Number

Mandatory. Must be at least 0. Must have at most 12 integral digits and 3 fractional digits

Tbd

[0.6.0,)

The weight value

unit

String

Mandatory

Acceptable Weight

Tbd

[0.6.0,)

The weight unit (Kilogram, Gram …​etc. See Acceptable Weight)

Appendix B: Object Data Types

B.1. Dates and times

All requests must and all responses shall specify

  • dates and times in ISO 8601 format.

  • times in UTC.

Type Example

Date

2016-01-14

Combined date and time

2017-01-15T01:50:02+02:00

2018-02-16T13:37:40.123+04:30

2019-03-17T17:31:10Z

B.2. Acceptable DPI

DPI Description Status Version

200

200 DPI

Supported

[0.7.0,)

300

300 DPI

Supported

[0.7.0,)

600

600 DPI

Not supported yet

[0.7.0,)

B.3. Acceptable Label Format

Format Description Status Version

PDF

Portable Document Format

Supported

[0.6.0,)

PNG

Portable Network Graphics

Supported

[0.7.0,)

PCL

Printer Command Language

Not supported yet

ZPL

Zebra Programming Language

Supported

[0.7.0,)

B.4. Acceptable Measurement

Unit Symbol Status Version

Centimetres

CM

Supported

[0.6.0,)

B.5. Acceptable Shipment Type

Shipment Type Description Version

DELIVERY

Represents an outbound shipment

[0.6.0,)

COLLECTION

Represents an outbound shipment, to a PUDO/Store location

[0.7.5,)

B.6. Acceptable Consignment List Type

Shipment Type Description Version

CLOSE_LIST

Represents a close list type

[0.13.0,)

B.7. Acceptable Consignment Status

Status Description Version

READY_TO_MANIFEST

Represents that the consignment is in the ready to manifest state

[0.14.0,)

HOLD_TO_MANIFEST

Represents that the consignment is being held and is not ready to manifest

[0.14.0,)

B.8. Acceptable Weight

Unit Symbol Status Version

Kilogram

KG

Supported

[0.6.0,)

B.9. Proof of Delivery Type

Type Description Version

SIGNATURE

Signature on delivery required.

[0.6.0,)

NON_SIGNATURE

Signature on delivery not required.

[0.6.0,)

B.10. Constraint Violation Codes

Name Description

NotNull

May not be null.

NotNullDependsOn

May not be null if a dependent field is not provided.

ValueDependsOn

May not be null if a dependent field is both provided and equal to a specified value.

DecimalMax

Number must be less than or equal to a specified max.

DecimalMin

Number must be greater than or equal to a specified min.

Digits

Numeric value is not within an acceptable range.

Future

Date must be in the future.

Max

Number must be less than or equal to a specified max.

Min

Number must be greater than or equal to a specified min.

Past

Date must be in the past.

Size

Size must be between a specified min and max.

Email

Must be a well-formed email address.

Enum

Must be an acceptable enumeration value (i.e. a member of a set of acceptable values).

ValidAddressFormat

Must be a valid address-format. The structure of the address must be valid for the given country.

MapStringSize

Size of String for key and value must be less than or equal to a specified max.

ValidTypeAndReceiverCombination

For shipments of type collection, the receiver must have either a ValidURI or valid address and contact.

ValidTypeAndDestinationCombination

For shipments of type COLLECTION, the destination must have either (1) a ValidURI, or (2) a collectionPointID, a collectionPointProviderID, a valid address and, optionally, a valid contact.

For shipments of type DELIVERY, the only acceptable fields are address and contact, both of which are mandatory.

ValidURI

Must be a well-formed URI.

ValidDestinationURI

Must be a valid destination URI.

ValidConsignmentURI

Must be a valid consignment URI.

ISODateTimeFormat

Must be a valid ISO 8601 date or date-time (see Dates and times).

CompatibleType

Must be of compatible type. For example, a field of type Number must hold a numeric value (e.g. 2.0 and not "two").

SupportedValue

Must be a supported value. For example, a shipment’s type must be an Acceptable Shipment Type, so "OFFICE" would not be supported.

B.11. Allocation Error Codes

Name Description

UnknownError

An unknown error occurred

DeliveryWindow

No logistics service available for the DeliveryWindow

DeliveryWindowRejectedForCutOff

No logistics service available for the DeliveryWindow.The consignment cannot be allocated because the cut off time is overdue for the start of the DeliveryWindow

DeliveryWindowRejectedForTransitTimes

No logistics service available for the DeliveryWindow. Transit time exceeds the size of the DeliveryWindow

DeliveryWindowRejectedForWorkingDays

No logistics service available for the DeliveryWindow.Not enough working days in the DeliveryWindow

NoLogisticsServiceAvailable

The shipment could not be allocated to any logistics service

TooHigh

Value is too high

TooLow

Value is too low

B.12. Document Type

Name Description Version

label

The document associated to this type represents a label

[0.6.0,)

paperwork

The document associated to this type represents the any non label documents

[0.6.0,)

B.13. Hazardous Material Attribute

Name Description Version

LIQUID

Is a liquid.

[0.6.0,)

AEROSOL

Is an aerosol.

[0.6.0,)

B.14. Time Zones

Table 10. Time Zones.[1]
Time Zone Zone Id

Greenwich Mean Time

Africa/Abidjan

Ghana Mean Time

Africa/Accra

Eastern African Time

Africa/Addis_Ababa

Central European Time

Africa/Algiers

Eastern African Time

Africa/Asmara

Eastern African Time

Africa/Asmera

Greenwich Mean Time

Africa/Bamako

Western African Time

Africa/Bangui

Greenwich Mean Time

Africa/Banjul

Greenwich Mean Time

Africa/Bissau

Central African Time

Africa/Blantyre

Western African Time

Africa/Brazzaville

Central African Time

Africa/Bujumbura

Eastern European Time

Africa/Cairo

Western European Time

Africa/Casablanca

Central European Time

Africa/Ceuta

Greenwich Mean Time

Africa/Conakry

Greenwich Mean Time

Africa/Dakar

Eastern African Time

Africa/Dar_es_Salaam

Eastern African Time

Africa/Djibouti

Western African Time

Africa/Douala

Western European Time

Africa/El_Aaiun

Greenwich Mean Time

Africa/Freetown

Central African Time

Africa/Gaborone

Central African Time

Africa/Harare

South Africa Standard Time

Africa/Johannesburg

Eastern African Time

Africa/Juba

Eastern African Time

Africa/Kampala

Eastern African Time

Africa/Khartoum

Central African Time

Africa/Kigali

Western African Time

Africa/Kinshasa

Western African Time

Africa/Lagos

Western African Time

Africa/Libreville

Greenwich Mean Time

Africa/Lome

Western African Time

Africa/Luanda

Central African Time

Africa/Lubumbashi

Central African Time

Africa/Lusaka

Western African Time

Africa/Malabo

Central African Time

Africa/Maputo

South Africa Standard Time

Africa/Maseru

South Africa Standard Time

Africa/Mbabane

Eastern African Time

Africa/Mogadishu

Greenwich Mean Time

Africa/Monrovia

Eastern African Time

Africa/Nairobi

Western African Time

Africa/Ndjamena

Western African Time

Africa/Niamey

Greenwich Mean Time

Africa/Nouakchott

Greenwich Mean Time

Africa/Ouagadougou

Western African Time

Africa/Porto-Novo

Greenwich Mean Time

Africa/Sao_Tome

Greenwich Mean Time

Africa/Timbuktu

Eastern European Time

Africa/Tripoli

Central European Time

Africa/Tunis

Western African Time

Africa/Windhoek

Hawaii-Aleutian Standard Time

America/Adak

Alaska Standard Time

America/Anchorage

Atlantic Standard Time

America/Anguilla

Atlantic Standard Time

America/Antigua

Brasilia Time

America/Araguaina

Argentine Time

America/Argentina/Buenos_Aires

Argentine Time

America/Argentina/Catamarca

Argentine Time

America/Argentina/ComodRivadavia

Argentine Time

America/Argentina/Cordoba

Argentine Time

America/Argentina/Jujuy

Argentine Time

America/Argentina/La_Rioja

Argentine Time

America/Argentina/Mendoza

Argentine Time

America/Argentina/Rio_Gallegos

Argentine Time

America/Argentina/Salta

Argentine Time

America/Argentina/San_Juan

Argentine Time

America/Argentina/San_Luis

Argentine Time

America/Argentina/Tucuman

Argentine Time

America/Argentina/Ushuaia

Atlantic Standard Time

America/Aruba

Paraguay Time

America/Asuncion

Eastern Standard Time

America/Atikokan

Hawaii-Aleutian Standard Time

America/Atka

Brasilia Time

America/Bahia

Central Standard Time

America/Bahia_Banderas

Atlantic Standard Time

America/Barbados

Brasilia Time

America/Belem

Central Standard Time

America/Belize

Atlantic Standard Time

America/Blanc-Sablon

Amazon Time

America/Boa_Vista

Colombia Time

America/Bogota

Mountain Standard Time

America/Boise

Argentine Time

America/Buenos_Aires

Mountain Standard Time

America/Cambridge_Bay

Amazon Time

America/Campo_Grande

Central Standard Time

America/Cancun

Venezuela Time

America/Caracas

Argentine Time

America/Catamarca

French Guiana Time

America/Cayenne

Eastern Standard Time

America/Cayman

Central Standard Time

America/Chicago

Mountain Standard Time

America/Chihuahua

Eastern Standard Time

America/Coral_Harbour

Argentine Time

America/Cordoba

Central Standard Time

America/Costa_Rica

Mountain Standard Time

America/Creston

Amazon Time

America/Cuiaba

Atlantic Standard Time

America/Curacao

Greenwich Mean Time

America/Danmarkshavn

Pacific Standard Time

America/Dawson

Mountain Standard Time

America/Dawson_Creek

Mountain Standard Time

America/Denver

Eastern Standard Time

America/Detroit

Atlantic Standard Time

America/Dominica

Mountain Standard Time

America/Edmonton

Acre Time

America/Eirunepe

Central Standard Time

America/El_Salvador

Pacific Standard Time

America/Ensenada

Eastern Standard Time

America/Fort_Wayne

Brasilia Time

America/Fortaleza

Atlantic Standard Time

America/Glace_Bay

Western Greenland Time

America/Godthab

Atlantic Standard Time

America/Goose_Bay

Atlantic Standard Time

America/Grand_Turk

Atlantic Standard Time

America/Grenada

Atlantic Standard Time

America/Guadeloupe

Central Standard Time

America/Guatemala

Ecuador Time

America/Guayaquil

Guyana Time

America/Guyana

Atlantic Standard Time

America/Halifax

Cuba Standard Time

America/Havana

Mountain Standard Time

America/Hermosillo

Eastern Standard Time

America/Indiana/Indianapolis

Central Standard Time

America/Indiana/Knox

Eastern Standard Time

America/Indiana/Marengo

Eastern Standard Time

America/Indiana/Petersburg

Central Standard Time

America/Indiana/Tell_City

Eastern Standard Time

America/Indiana/Vevay

Eastern Standard Time

America/Indiana/Vincennes

Eastern Standard Time

America/Indiana/Winamac

Eastern Standard Time

America/Indianapolis

Mountain Standard Time

America/Inuvik

Eastern Standard Time

America/Iqaluit

Eastern Standard Time

America/Jamaica

Argentine Time

America/Jujuy

Alaska Standard Time

America/Juneau

Eastern Standard Time

America/Kentucky/Louisville

Eastern Standard Time

America/Kentucky/Monticello

Central Standard Time

America/Knox_IN

Atlantic Standard Time

America/Kralendijk

Bolivia Time

America/La_Paz

Peru Time

America/Lima

Pacific Standard Time

America/Los_Angeles

Eastern Standard Time

America/Louisville

Atlantic Standard Time

America/Lower_Princes

Brasilia Time

America/Maceio

Central Standard Time

America/Managua

Amazon Time

America/Manaus

Atlantic Standard Time

America/Marigot

Atlantic Standard Time

America/Martinique

Central Standard Time

America/Matamoros

Mountain Standard Time

America/Mazatlan

Argentine Time

America/Mendoza

Central Standard Time

America/Menominee

Central Standard Time

America/Merida

Pacific Standard Time

America/Metlakatla

Central Standard Time

America/Mexico_City

Pierre & Miquelon Standard Time

America/Miquelon

Atlantic Standard Time

America/Moncton

Central Standard Time

America/Monterrey

Uruguay Time

America/Montevideo

Eastern Standard Time

America/Montreal

Atlantic Standard Time

America/Montserrat

Eastern Standard Time

America/Nassau

Eastern Standard Time

America/New_York

Eastern Standard Time

America/Nipigon

Alaska Standard Time

America/Nome

Fernando de Noronha Time

America/Noronha

Central Standard Time

America/North_Dakota/Beulah

Central Standard Time

America/North_Dakota/Center

Central Standard Time

America/North_Dakota/New_Salem

Mountain Standard Time

America/Ojinaga

Eastern Standard Time

America/Panama

Eastern Standard Time

America/Pangnirtung

Suriname Time

America/Paramaribo

Mountain Standard Time

America/Phoenix

Eastern Standard Time

America/Port-au-Prince

Atlantic Standard Time

America/Port_of_Spain

Acre Time

America/Porto_Acre

Amazon Time

America/Porto_Velho

Atlantic Standard Time

America/Puerto_Rico

Central Standard Time

America/Rainy_River

Central Standard Time

America/Rankin_Inlet

Brasilia Time

America/Recife

Central Standard Time

America/Regina

Central Standard Time

America/Resolute

Acre Time

America/Rio_Branco

Argentine Time

America/Rosario

Pacific Standard Time

America/Santa_Isabel

Brasilia Time

America/Santarem

Chile Time

America/Santiago

Atlantic Standard Time

America/Santo_Domingo

Brasilia Time

America/Sao_Paulo

Eastern Greenland Time

America/Scoresbysund

Mountain Standard Time

America/Shiprock

Alaska Standard Time

America/Sitka

Atlantic Standard Time

America/St_Barthelemy

Newfoundland Standard Time

America/St_Johns

Atlantic Standard Time

America/St_Kitts

Atlantic Standard Time

America/St_Lucia

Atlantic Standard Time

America/St_Thomas

Atlantic Standard Time

America/St_Vincent

Central Standard Time

America/Swift_Current

Central Standard Time

America/Tegucigalpa

Atlantic Standard Time

America/Thule

Eastern Standard Time

America/Thunder_Bay

Pacific Standard Time

America/Tijuana

Eastern Standard Time

America/Toronto

Atlantic Standard Time

America/Tortola

Pacific Standard Time

America/Vancouver

Atlantic Standard Time

America/Virgin

Pacific Standard Time

America/Whitehorse

Central Standard Time

America/Winnipeg

Alaska Standard Time

America/Yakutat

Mountain Standard Time

America/Yellowknife

Australian Western Standard Time

Antarctica/Casey

Davis Time

Antarctica/Davis

Dumont-d’Urville Time

Antarctica/DumontDUrville

Macquarie Island Standard Time

Antarctica/Macquarie

Mawson Time

Antarctica/Mawson

New Zealand Standard Time

Antarctica/McMurdo

Chile Time

Antarctica/Palmer

Rothera Time

Antarctica/Rothera

New Zealand Standard Time

Antarctica/South_Pole

Syowa Time

Antarctica/Syowa

Coordinated Universal Time

Antarctica/Troll

Vostok Time

Antarctica/Vostok

Central European Time

Arctic/Longyearbyen

Arabia Standard Time

Asia/Aden

Alma-Ata Time

Asia/Almaty

Eastern European Time

Asia/Amman

Anadyr Time

Asia/Anadyr

Aqtau Time

Asia/Aqtau

Aqtobe Time

Asia/Aqtobe

Turkmenistan Time

Asia/Ashgabat

Turkmenistan Time

Asia/Ashkhabad

Arabia Standard Time

Asia/Baghdad

Arabia Standard Time

Asia/Bahrain

Azerbaijan Time

Asia/Baku

Indochina Time

Asia/Bangkok

Eastern European Time

Asia/Beirut

Kirgizstan Time

Asia/Bishkek

Brunei Time

Asia/Brunei

India Standard Time

Asia/Calcutta

Irkutsk Time

Asia/Chita

Choibalsan Time

Asia/Choibalsan

China Standard Time

Asia/Chongqing

China Standard Time

Asia/Chungking

India Standard Time

Asia/Colombo

Bangladesh Time

Asia/Dacca

Eastern European Time

Asia/Damascus

Bangladesh Time

Asia/Dhaka

Timor-Leste Time

Asia/Dili

Gulf Standard Time

Asia/Dubai

Tajikistan Time

Asia/Dushanbe

Eastern European Time

Asia/Gaza

China Standard Time

Asia/Harbin

Eastern European Time

Asia/Hebron

Indochina Time

Asia/Ho_Chi_Minh

Hong Kong Time

Asia/Hong_Kong

Hovd Time

Asia/Hovd

Irkutsk Time

Asia/Irkutsk

Eastern European Time

Asia/Istanbul

West Indonesia Time

Asia/Jakarta

East Indonesia Time

Asia/Jayapura

Israel Standard Time

Asia/Jerusalem

Afghanistan Time

Asia/Kabul

Petropavlovsk-Kamchatski Time

Asia/Kamchatka

Pakistan Time

Asia/Karachi

Xinjiang Standard Time

Asia/Kashgar

Nepal Time

Asia/Kathmandu

Nepal Time

Asia/Katmandu

Khandyga Time

Asia/Khandyga

India Standard Time

Asia/Kolkata

Krasnoyarsk Time

Asia/Krasnoyarsk

Malaysia Time

Asia/Kuala_Lumpur

Malaysia Time

Asia/Kuching

Arabia Standard Time

Asia/Kuwait

China Standard Time

Asia/Macao

China Standard Time

Asia/Macau

Magadan Time

Asia/Magadan

Central Indonesia Time

Asia/Makassar

Philippines Time

Asia/Manila

Gulf Standard Time

Asia/Muscat

Eastern European Time

Asia/Nicosia

Krasnoyarsk Time

Asia/Novokuznetsk

Novosibirsk Time

Asia/Novosibirsk

Omsk Time

Asia/Omsk

Oral Time

Asia/Oral

Indochina Time

Asia/Phnom_Penh

West Indonesia Time

Asia/Pontianak

Korea Standard Time

Asia/Pyongyang

Arabia Standard Time

Asia/Qatar

Qyzylorda Time

Asia/Qyzylorda

Myanmar Time

Asia/Rangoon

Arabia Standard Time

Asia/Riyadh

Indochina Time

Asia/Saigon

Sakhalin Time

Asia/Sakhalin

Uzbekistan Time

Asia/Samarkand

Korea Standard Time

Asia/Seoul

China Standard Time

Asia/Shanghai

Singapore Time

Asia/Singapore

Srednekolymsk Time

Asia/Srednekolymsk

China Standard Time

Asia/Taipei

Uzbekistan Time

Asia/Tashkent

Georgia Time

Asia/Tbilisi

Iran Standard Time

Asia/Tehran

Israel Standard Time

Asia/Tel_Aviv

Bhutan Time

Asia/Thimbu

Bhutan Time

Asia/Thimphu

Japan Standard Time

Asia/Tokyo

Central Indonesia Time

Asia/Ujung_Pandang

Ulaanbaatar Time

Asia/Ulaanbaatar

Ulaanbaatar Time

Asia/Ulan_Bator

Xinjiang Standard Time

Asia/Urumqi

Ust-Nera Time

Asia/Ust-Nera

Indochina Time

Asia/Vientiane

Vladivostok Time

Asia/Vladivostok

Yakutsk Time

Asia/Yakutsk

Yekaterinburg Time

Asia/Yekaterinburg

Armenia Time

Asia/Yerevan

Azores Time

Atlantic/Azores

Atlantic Standard Time

Atlantic/Bermuda

Western European Time

Atlantic/Canary

Cape Verde Time

Atlantic/Cape_Verde

Western European Time

Atlantic/Faeroe

Western European Time

Atlantic/Faroe

Central European Time

Atlantic/Jan_Mayen

Western European Time

Atlantic/Madeira

Greenwich Mean Time

Atlantic/Reykjavik

South Georgia Standard Time

Atlantic/South_Georgia

Greenwich Mean Time

Atlantic/St_Helena

Falkland Is. Time

Atlantic/Stanley

Australian Eastern Standard Time (New South Wales)

Australia/ACT

Australian Central Standard Time (South Australia)

Australia/Adelaide

Australian Eastern Standard Time (Queensland)

Australia/Brisbane

Australian Central Standard Time (South Australia/New South Wales)

Australia/Broken_Hill

Australian Eastern Standard Time (New South Wales)

Australia/Canberra

Australian Eastern Standard Time (New South Wales)

Australia/Currie

Australian Central Standard Time (Northern Territory)

Australia/Darwin

Australian Central Western Standard Time

Australia/Eucla

Australian Eastern Standard Time (Tasmania)

Australia/Hobart

Lord Howe Standard Time

Australia/LHI

Australian Eastern Standard Time (Queensland)

Australia/Lindeman

Lord Howe Standard Time

Australia/Lord_Howe

Australian Eastern Standard Time (Victoria)

Australia/Melbourne

Australian Eastern Standard Time (New South Wales)

Australia/NSW

Australian Central Standard Time (Northern Territory)

Australia/North

Australian Western Standard Time

Australia/Perth

Australian Eastern Standard Time (Queensland)

Australia/Queensland

Australian Central Standard Time (South Australia)

Australia/South

Australian Eastern Standard Time (New South Wales)

Australia/Sydney

Australian Eastern Standard Time (Tasmania)

Australia/Tasmania

Australian Eastern Standard Time (Victoria)

Australia/Victoria

Australian Western Standard Time

Australia/West

Australian Central Standard Time (South Australia/New South Wales)

Australia/Yancowinna

Acre Time

Brazil/Acre

Fernando de Noronha Time

Brazil/DeNoronha

Brasilia Time

Brazil/East

Amazon Time

Brazil/West

Central European Time

CET

Central Standard Time

CST6CDT

Atlantic Standard Time

Canada/Atlantic

Central Standard Time

Canada/Central

Central Standard Time

Canada/East-Saskatchewan

Eastern Standard Time

Canada/Eastern

Mountain Standard Time

Canada/Mountain

Newfoundland Standard Time

Canada/Newfoundland

Pacific Standard Time

Canada/Pacific

Central Standard Time

Canada/Saskatchewan

Pacific Standard Time

Canada/Yukon

Chile Time

Chile/Continental

Easter Is. Time

Chile/EasterIsland

Cuba Standard Time

Cuba

Eastern European Time

EET

Eastern Standard Time

EST5EDT

Eastern European Time

Egypt

Greenwich Mean Time

Eire

Greenwich Mean Time

Etc/GMT

Greenwich Mean Time

Etc/GMT+0

GMT-01:00

Etc/GMT+1

GMT-10:00

Etc/GMT+10

GMT-11:00

Etc/GMT+11

GMT-12:00

Etc/GMT+12

GMT-02:00

Etc/GMT+2

GMT-03:00

Etc/GMT+3

GMT-04:00

Etc/GMT+4

GMT-05:00

Etc/GMT+5

GMT-06:00

Etc/GMT+6

GMT-07:00

Etc/GMT+7

GMT-08:00

Etc/GMT+8

GMT-09:00

Etc/GMT+9

Greenwich Mean Time

Etc/GMT-0

GMT+01:00

Etc/GMT-1

GMT+10:00

Etc/GMT-10

GMT+11:00

Etc/GMT-11

GMT+12:00

Etc/GMT-12

GMT+13:00

Etc/GMT-13

GMT+14:00

Etc/GMT-14

GMT+02:00

Etc/GMT-2

GMT+03:00

Etc/GMT-3

GMT+04:00

Etc/GMT-4

GMT+05:00

Etc/GMT-5

GMT+06:00

Etc/GMT-6

GMT+07:00

Etc/GMT-7

GMT+08:00

Etc/GMT-8

GMT+09:00

Etc/GMT-9

Greenwich Mean Time

Etc/GMT0

Greenwich Mean Time

Etc/Greenwich

Coordinated Universal Time

Etc/UCT

Coordinated Universal Time

Etc/UTC

Coordinated Universal Time

Etc/Universal

Coordinated Universal Time

Etc/Zulu

Central European Time

Europe/Amsterdam

Central European Time

Europe/Andorra

Eastern European Time

Europe/Athens

Greenwich Mean Time

Europe/Belfast

Central European Time

Europe/Belgrade

Central European Time

Europe/Berlin

Central European Time

Europe/Bratislava

Central European Time

Europe/Brussels

Eastern European Time

Europe/Bucharest

Central European Time

Europe/Budapest

Central European Time

Europe/Busingen

Eastern European Time

Europe/Chisinau

Central European Time

Europe/Copenhagen

Greenwich Mean Time

Europe/Dublin

Central European Time

Europe/Gibraltar

Greenwich Mean Time

Europe/Guernsey

Eastern European Time

Europe/Helsinki

Greenwich Mean Time

Europe/Isle_of_Man

Eastern European Time

Europe/Istanbul

Greenwich Mean Time

Europe/Jersey

Eastern European Time

Europe/Kaliningrad

Eastern European Time

Europe/Kiev

Western European Time

Europe/Lisbon

Central European Time

Europe/Ljubljana

Greenwich Mean Time

Europe/London

Central European Time

Europe/Luxembourg

Central European Time

Europe/Madrid

Central European Time

Europe/Malta

Eastern European Time

Europe/Mariehamn

Moscow Standard Time

Europe/Minsk

Central European Time

Europe/Monaco

Moscow Standard Time

Europe/Moscow

Eastern European Time

Europe/Nicosia

Central European Time

Europe/Oslo

Central European Time

Europe/Paris

Central European Time

Europe/Podgorica

Central European Time

Europe/Prague

Eastern European Time

Europe/Riga

Central European Time

Europe/Rome

Samara Time

Europe/Samara

Central European Time

Europe/San_Marino

Central European Time

Europe/Sarajevo

Moscow Standard Time

Europe/Simferopol

Central European Time

Europe/Skopje

Eastern European Time

Europe/Sofia

Central European Time

Europe/Stockholm

Eastern European Time

Europe/Tallinn

Central European Time

Europe/Tirane

Eastern European Time

Europe/Tiraspol

Eastern European Time

Europe/Uzhgorod

Central European Time

Europe/Vaduz

Central European Time

Europe/Vatican

Central European Time

Europe/Vienna

Eastern European Time

Europe/Vilnius

Moscow Standard Time

Europe/Volgograd

Central European Time

Europe/Warsaw

Central European Time

Europe/Zagreb

Eastern European Time

Europe/Zaporozhye

Central European Time

Europe/Zurich

Greenwich Mean Time

GB

Greenwich Mean Time

GB-Eire

Greenwich Mean Time

GMT

Greenwich Mean Time

GMT0

Greenwich Mean Time

Greenwich

Hong Kong Time

Hongkong

Greenwich Mean Time

Iceland

Eastern African Time

Indian/Antananarivo

Indian Ocean Territory Time

Indian/Chagos

Christmas Island Time

Indian/Christmas

Cocos Islands Time

Indian/Cocos

Eastern African Time

Indian/Comoro

French Southern & Antarctic Lands Time

Indian/Kerguelen

Seychelles Time

Indian/Mahe

Maldives Time

Indian/Maldives

Mauritius Time

Indian/Mauritius

Eastern African Time

Indian/Mayotte

Reunion Time

Indian/Reunion

Iran Standard Time

Iran

Israel Standard Time

Israel

Eastern Standard Time

Jamaica

Japan Standard Time

Japan

Marshall Islands Time

Kwajalein

Eastern European Time

Libya

Middle Europe Time

MET

Mountain Standard Time

MST7MDT

Pacific Standard Time

Mexico/BajaNorte

Mountain Standard Time

Mexico/BajaSur

Central Standard Time

Mexico/General

New Zealand Standard Time

NZ

Chatham Standard Time

NZ-CHAT

Mountain Standard Time

Navajo

China Standard Time

PRC

Pacific Standard Time

PST8PDT

West Samoa Standard Time

Pacific/Apia

New Zealand Standard Time

Pacific/Auckland

Bougainville Standard Time

Pacific/Bougainville

Chatham Standard Time

Pacific/Chatham

Chuuk Time

Pacific/Chuuk

Easter Is. Time

Pacific/Easter

Vanuatu Time

Pacific/Efate

Phoenix Is. Time

Pacific/Enderbury

Tokelau Time

Pacific/Fakaofo

Fiji Time

Pacific/Fiji

Tuvalu Time

Pacific/Funafuti

Galapagos Time

Pacific/Galapagos

Gambier Time

Pacific/Gambier

Solomon Is. Time

Pacific/Guadalcanal

Chamorro Standard Time

Pacific/Guam

Hawaii Standard Time

Pacific/Honolulu

Hawaii Standard Time

Pacific/Johnston

Line Is. Time

Pacific/Kiritimati

Kosrae Time

Pacific/Kosrae

Marshall Islands Time

Pacific/Kwajalein

Marshall Islands Time

Pacific/Majuro

Marquesas Time

Pacific/Marquesas

Samoa Standard Time

Pacific/Midway

Nauru Time

Pacific/Nauru

Niue Time

Pacific/Niue

Norfolk Time

Pacific/Norfolk

New Caledonia Time

Pacific/Noumea

Samoa Standard Time

Pacific/Pago_Pago

Palau Time

Pacific/Palau

Pitcairn Standard Time

Pacific/Pitcairn

Pohnpei Time

Pacific/Pohnpei

Pohnpei Time

Pacific/Ponape

Papua New Guinea Time

Pacific/Port_Moresby

Cook Is. Time

Pacific/Rarotonga

Chamorro Standard Time

Pacific/Saipan

Samoa Standard Time

Pacific/Samoa

Tahiti Time

Pacific/Tahiti

Gilbert Is. Time

Pacific/Tarawa

Tonga Time

Pacific/Tongatapu

Chuuk Time

Pacific/Truk

Wake Time

Pacific/Wake

Wallis & Futuna Time

Pacific/Wallis

Chuuk Time

Pacific/Yap

Central European Time

Poland

Western European Time

Portugal

Korea Standard Time

ROK

Singapore Time

Singapore

Atlantic Standard Time

SystemV/AST4

Atlantic Standard Time

SystemV/AST4ADT

Central Standard Time

SystemV/CST6

Central Standard Time

SystemV/CST6CDT

Eastern Standard Time

SystemV/EST5

Eastern Standard Time

SystemV/EST5EDT

Hawaii Standard Time

SystemV/HST10

Mountain Standard Time

SystemV/MST7

Mountain Standard Time

SystemV/MST7MDT

Pacific Standard Time

SystemV/PST8

Pacific Standard Time

SystemV/PST8PDT

Alaska Standard Time

SystemV/YST9

Alaska Standard Time

SystemV/YST9YDT

Eastern European Time

Turkey

Coordinated Universal Time

UCT

Alaska Standard Time

US/Alaska

Hawaii-Aleutian Standard Time

US/Aleutian

Mountain Standard Time

US/Arizona

Central Standard Time

US/Central

Eastern Standard Time

US/East-Indiana

Eastern Standard Time

US/Eastern

Hawaii Standard Time

US/Hawaii

Central Standard Time

US/Indiana-Starke

Eastern Standard Time

US/Michigan

Mountain Standard Time

US/Mountain

Pacific Standard Time

US/Pacific

Pacific Standard Time

US/Pacific-New

Samoa Standard Time

US/Samoa

Coordinated Universal Time

UTC

Coordinated Universal Time

Universal

Moscow Standard Time

W-SU

Western European Time

WET

Coordinated Universal Time

Zulu

Eastern Standard Time

EST

Hawaii Standard Time

HST

Mountain Standard Time

MST

Australian Central Standard Time (Northern Territory)

ACT

Australian Eastern Standard Time (New South Wales)

AET

Argentine Time

AGT

Eastern European Time

ART

Alaska Standard Time

AST

Brasilia Time

BET

Bangladesh Time

BST

Central African Time

CAT

Newfoundland Standard Time

CNT

Central Standard Time

CST

China Standard Time

CTT

Eastern African Time

EAT

Central European Time

ECT

Eastern Standard Time

IET

India Standard Time

IST

Japan Standard Time

JST

West Samoa Standard Time

MIT

Armenia Time

NET

New Zealand Standard Time

NST

Pakistan Time

PLT

Mountain Standard Time

PNT

Atlantic Standard Time

PRT

Pacific Standard Time

PST

Solomon Is. Time

SST

Indochina Time

VST

B.15. Country Codes

The following is a complete list of the current officially assigned ISO 3166-1 alpha-3 codes, using the English short country names officially defined by the ISO 3166 Maintenance Agency (ISO 3166/MA)

Table 11. ISO 3166-1 Country Codes.[2]
Alpha-3 code English short name

ABW

Aruba

AFG

Afghanistan

AGO

Angola

AIA

Anguilla

ALA

Åland Islands

ALB

Albania

AND

Andorra

ARE

United Arab Emirates

ARG

Argentina

ARM

Armenia

ASM

American Samoa

ATA

Antarctica

ATF

French Southern Territories

ATG

Antigua and Barbuda

AUS

Australia

AUT

Austria

AZE

Azerbaijan

BDI

Burundi

BEL

Belgium

BEN

Benin

BES

Bonaire, Sint Eustatius and Saba

BFA

Burkina Faso

BGD

Bangladesh

BGR

Bulgaria

BHR

Bahrain

BHS

Bahamas

BIH

Bosnia and Herzegovina

BLM

Saint Barthélemy

BLR

Belarus

BLZ

Belize

BMU

Bermuda

BOL

Bolivia, Plurinational State of

BRA

Brazil

BRB

Barbados

BRN

Brunei Darussalam

BTN

Bhutan

BVT

Bouvet Island

BWA

Botswana

CAF

Central African Republic

CAN

Canada

CCK

Cocos (Keeling) Islands

CHE

Switzerland

CHL

Chile

CHN

China

CIV

Côte d’Ivoire

CMR

Cameroon

COD

Congo, the Democratic Republic of the

COG

Congo

COK

Cook Islands

COL

Colombia

COM

Comoros

CPV

Cabo Verde

CRI

Costa Rica

CUB

Cuba

CUW

Curaçao

CXR

Christmas Island

CYM

Cayman Islands

CYP

Cyprus

CZE

Czech Republic

DEU

Germany

DJI

Djibouti

DMA

Dominica

DNK

Denmark

DOM

Dominican Republic

DZA

Algeria

ECU

Ecuador

EGY

Egypt

ERI

Eritrea

ESH

Western Sahara

ESP

Spain

EST

Estonia

ETH

Ethiopia

FIN

Finland

FJI

Fiji

FLK

Falkland Islands (Malvinas)

FRA

France

FRO

Faroe Islands

FSM

Micronesia, Federated States of

GAB

Gabon

GBR

United Kingdom

GEO

Georgia

GGY

Guernsey

GHA

Ghana

GIB

Gibraltar

GIN

Guinea

GLP

Guadeloupe

GMB

Gambia

GNB

Guinea-Bissau

GNQ

Equatorial Guinea

GRC

Greece

GRD

Grenada

GRL

Greenland

GTM

Guatemala

GUF

French Guiana

GUM

Guam

GUY

Guyana

HKG

Hong Kong

HMD

Heard Island and McDonald Islands

HND

Honduras

HRV

Croatia

HTI

Haiti

HUN

Hungary

IDN

Indonesia

IMN

Isle of Man

IND

India

IOT

British Indian Ocean Territory

IRL

Ireland

IRN

Iran, Islamic Republic of

IRQ

Iraq

ISL

Iceland

ISR

Israel

ITA

Italy

JAM

Jamaica

JEY

Jersey

JOR

Jordan

JPN

Japan

KAZ

Kazakhstan

KEN

Kenya

KGZ

Kyrgyzstan

KHM

Cambodia

KIR

Kiribati

KNA

Saint Kitts and Nevis

KOR

Korea, Republic of

KWT

Kuwait

LAO

Lao People’s Democratic Republic

LBN

Lebanon

LBR

Liberia

LBY

Libya

LCA

Saint Lucia

LIE

Liechtenstein

LKA

Sri Lanka

LSO

Lesotho

LTU

Lithuania

LUX

Luxembourg

LVA

Latvia

MAC

Macao

MAF

Saint Martin (French part)

MAR

Morocco

MCO

Monaco

MDA

Moldova, Republic of

MDG

Madagascar

MDV

Maldives

MEX

Mexico

MHL

Marshall Islands

MKD

Macedonia, the former Yugoslav Republic of

MLI

Mali

MLT

Malta

MMR

Myanmar

MNE

Montenegro

MNG

Mongolia

MNP

Northern Mariana Islands

MOZ

Mozambique

MRT

Mauritania

MSR

Montserrat

MTQ

Martinique

MUS

Mauritius

MWI

Malawi

MYS

Malaysia

MYT

Mayotte

NAM

Namibia

NCL

New Caledonia

NER

Niger

NFK

Norfolk Island

NGA

Nigeria

NIC

Nicaragua

NIU

Niue

NLD

Netherlands

NOR

Norway

NPL

Nepal

NRU

Nauru

NZL

New Zealand

OMN

Oman

PAK

Pakistan

PAN

Panama

PCN

Pitcairn

PER

Peru

PHL

Philippines

PLW

Palau

PNG

Papua New Guinea

POL

Poland

PRI

Puerto Rico

PRK

Korea, Democratic People’s Republic of

PRT

Portugal

PRY

Paraguay

PSE

Palestine, State of

PYF

French Polynesia

QAT

Qatar

REU

Réunion

ROU

Romania

RUS

Russian Federation

RWA

Rwanda

SAU

Saudi Arabia

SDN

Sudan

SEN

Senegal

SGP

Singapore

SGS

South Georgia and the South Sandwich Islands

SHN

Saint Helena, Ascension and Tristan da Cunha

SJM

Svalbard and Jan Mayen

SLB

Solomon Islands

SLE

Sierra Leone

SLV

El Salvador

SMR

San Marino

SOM

Somalia

SPM

Saint Pierre and Miquelon

SRB

Serbia

SSD

South Sudan

STP

Sao Tome and Principe

SUR

Suriname

SVK

Slovakia

SVN

Slovenia

SWE

Sweden

SWZ

Swaziland

SXM

Sint Maarten (Dutch part)

SYC

Seychelles

SYR

Syrian Arab Republic

TCA

Turks and Caicos Islands

TCD

Chad

TGO

Togo

THA

Thailand

TJK

Tajikistan

TKL

Tokelau

TKM

Turkmenistan

TLS

Timor-Leste

TON

Tonga

TTO

Trinidad and Tobago

TUN

Tunisia

TUR

Turkey

TUV

Tuvalu

TWN

Taiwan, Province of China

TZA

Tanzania, United Republic of

UGA

Uganda

UKR

Ukraine

UMI

United States Minor Outlying Islands

URY

Uruguay

USA

United States of America

UZB

Uzbekistan

VAT

Holy See (Vatican City State)

VCT

Saint Vincent and the Grenadines

VEN

Venezuela, Bolivarian Republic of

VGB

Virgin Islands, British

VIR

Virgin Islands, U.S.

VNM

Viet Nam

VUT

Vanuatu

WLF

Wallis and Futuna

WSM

Samoa

YEM

Yemen

ZAF

South Africa

ZMB

Zambia

ZWE

Zimbabwe

Appendix C: API Error Codes

Error Code Description Resolution

O-INT-1000

Internal Server Error.

Re-try the request. If it still fails, contact MetaPack support.

O-VAL-2000

The request does not satisfy at least 1 of the data constraints for this API.

O-VAL-2001

The content-type header is not supported.

Make sure the content-type has the following format: application/vnd.metapack.mm.v<valid api version number>+json

O-VAL-2002

Missing request parameter.

The request requires a parameter to be supplied. Review the error message to determine which parameter name needs to be provided.

O-VAL-2003

Invalid request parameter value.

The request parameter supplied does not have a valid value. Review the error message to determine which parameter value needs to be corrected.

O-VAL-2004

Logistics service is not active.

O-VAL-2006

Specified logistics provider contract could not be recognised.

O-VAL-2008

Specified shipment(s) is already cancelled.

O-VAL-2009

Method not supported for this endpoint.

O-NFO-3000 - 3999

Not Found errors.

O-NFO-3000

Resource does not exist.

O-NFO-3001

Shipment does not exist.

O-NFO-3002

Manifest does not exist.

O-NFO-3003

Consignment does not exist.

O-NFO-3004

Document does not exist.

O-NFO-3006

None of the consignments provided is eligible for changing the status.

O-ALE-4000 - 4999

Allocation errors. Specific errors yet to be defined.

Correct the shipment or delivery preferences and try again.

O-ALE-4000

General allocation error.

O-ALE-4001

Consignment cannot be deallocated as it has already been manifested.

O-ALE-4002

Consignment cannot be deallocated as it is already deallocated.

O-COL-6000 - 6999

Consignment List errors. Specific errors yet to be defined.

O-COL-6001

The list type is incompatible with the status of the consignments in the request.

Appendix D: Required Address Fields

The API validates the structure of addresses but does not verify that the address physically exists.

The table below defines required and optional fields for each country. For any country not present in the table, all of its fields are optional except city and street.

Postcode structures are validated against provided countries but no checks are made to verify that postcodes represent real locations.

Country name Code Province City District Postal code Street

AMERICAN SAMOA

ASM

Required

Required

Optional

Required

Required

ANTIGUA AND BARBUDA

ATG

Optional

Optional

Optional

Optional

Required

AUSTRALIA

AUS

Required

Required

Optional

Required

Required

AUSTRIA

AUT

Optional

Required

Optional

Required

Required

BELGIUM

BEL

Optional

Required

Optional

Required

Required

BRAZIL

BRA

Required

Required

Optional

Required

Required

BRITISH INDIAN OCEAN TERRITORY

IOT

Optional

Required

Optional

Required

Required

CANADA

CAN

Required

Required

Optional

Required

Required

CAYMAN ISLANDS

CYM

Required

Optional

Optional

Optional

Required

CHANNEL ISLANDS

GGY

Optional

Required

Optional

Required

Required

CHANNEL ISLANDS

JEY

Optional

Required

Optional

Required

Required

CHINA

CHN

Required

Required

Optional

Required

Required

COLOMBIA

COL

Required

Optional

Optional

Optional

Required

COSTA RICA

CRI

Required

Required

Optional

Optional

Required

DENMARK

DNK

Optional

Required

Optional

Required

Required

EL SALVADOR

SLV

Required

Required

Optional

Optional

Required

FALKLAND ISLANDS (MALVINAS)

FLK

Optional

Required

Optional

Required

Required

FINLAND

ALA

Optional

Required

Optional

Required

Required

FINLAND

FIN

Optional

Required

Optional

Required

Required

FRANCE

FRA

Optional

Required

Optional

Required

Required

FRENCH GUIANA

GUF

Optional

Required

Optional

Required

Required

FRENCH POLYNESIA

PYF

Required

Required

Optional

Required

Required

GERMANY

DEU

Optional

Required

Optional

Required

Required

GIBRALTAR

GIB

Optional

Optional

Optional

Optional

Required

GREECE

GRC

Optional

Required

Optional

Required

Required

GREENLAND

GRL

Optional

Required

Optional

Required

Required

GUADELOUPE

GLP

Optional

Required

Optional

Required

Required

GUAM

GUM

Required

Required

Optional

Required

Required

HONDURAS

HND

Required

Required

Optional

Optional

Required

HONG KONG

HKG

Required

Optional

Optional

Optional

Required

HUNGARY (Rep.)

HUN

Optional

Required

Optional

Required

Required

INDIA

IND

Required

Required

Optional

Required

Required

INDONESIA

IDN

Required

Optional

Optional

Optional

Required

IRAQ

IRQ

Required

Required

Optional

Optional

Required

ISLE OF MAN

IMN

Optional

Required

Optional

Required

Required

ITALY

ITA

Required

Required

Optional

Required

Required

JAMAICA

JAM

Required

Required

Optional

Optional

Required

JAPAN

JPN

Required

Required

Optional

Required

Required

LIECHTENSTEIN

LIE

Optional

Required

Optional

Required

Required

LUXEMBOURG

LUX

Optional

Required

Optional

Required

Required

MACAO

MAC

Optional

Optional

Optional

Optional

Required

MALAYSIA

MYS

Optional

Required

Optional

Required

Required

MARSHALL ISLANDS

MHL

Required

Required

Optional

Required

Required

MARTINIQUE

MTQ

Optional

Required

Optional

Required

Required

MAYOTTE

MYT

Optional

Required

Optional

Required

Required

MEXICO

MEX

Optional

Required

Optional

Required

Required

MICRONESIA (Federated State of)

FSM

Required

Required

Optional

Required

Required

NAURU CENTRAL PACIFIC

NRU

Required

Optional

Optional

Optional

Required

NETHERLANDS

NLD

Optional

Required

Optional

Required

Required

NEW CALEDONIA

NCL

Optional

Required

Optional

Required

Required

NEW ZEALAND

NZL

Optional

Required

Optional

Required

Required

NORTHERN MARIANA ISLANDS

MNP

Required

Required

Optional

Required

Required

NORWAY

NOR

Optional

Required

Optional

Required

Required

PALAU

PLW

Required

Required

Optional

Required

Required

PAPUA NEW GUINEA

PNG

Required

Required

Optional

Optional

Required

PITCAIRN

PCN

Optional

Required

Optional

Required

Required

POLAND

POL

Optional

Required

Optional

Required

Required

PORTUGAL

PRT

Optional

Required

Optional

Required

Required

PUERTO RICO

PRI

Optional

Required

Optional

Required

Required

REP. OF SINGAPORE

SGP

Optional

Optional

Optional

Required

Required

REUNION

REU

Optional

Required

Optional

Required

Required

RUSSIAN FEDERATION

RUS

Required

Required

Optional

Required

Required

SAINT BARTHELEMY

BLM

Optional

Required

Optional

Required

Required

SAINT HELENA

SHN

Optional

Required

Optional

Required

Required

SAINT KITTS AND NEVIS

KNA

Required

Required

Optional

Optional

Required

SAINT MARTIN

MAF

Optional

Required

Optional

Required

Required

SAN MARINO

SMR

Optional

Optional

Optional

Required

Required

SOMALIA

SOM

Required

Required

Optional

Optional

Required

SOUTH AFRICA

ZAF

Optional

Required

Optional

Required

Required

SOUTH GEORGIA

SGS

Optional

Required

Optional

Required

Required

SOUTH KOREA

KOR

Required

Required

Optional

Required

Required

SPAIN

ESP

Required

Required

Optional

Required

Required

ST. PIERRE AND MIQUELON

SPM

Optional

Required

Optional

Required

Required

SVALBARD AND JAN MAYEN ISLANDS

SJM

Optional

Required

Optional

Required

Required

SWEDEN

SWE

Optional

Required

Optional

Required

Required

SWITZERLAND

CHE

Optional

Required

Optional

Required

Required

TAIWAN

TWN

Required

Required

Optional

Required

Required

TURKEY

TUR

Optional

Required

Optional

Required

Required

TURKS AND CAICOS ISLANDS

TCA

Optional

Required

Optional

Required

Required

UKRAINE

UKR

Required

Required

Optional

Required

Required

UNITED ARAB EMIRATES

ARE

Required

Optional

Optional

Optional

Required

UNITED KINGDOM

GBR

Optional

Required

Optional

Required

Required

UNITED STATES

USA

Required

Required

Optional

Required

Required

UNITED STATES MINOR OUTLYING ISLANDS

UMI

Required

Required

Optional

Optional

Required

VENEZUELA

VEN

Required

Required

Optional

Optional

Required

VIRGIN ISLANDS (BRITISH)

VGB

Optional

Optional

Optional

Optional

Required

VIRGIN ISLANDS (U.S.)

VIR

Required

Required

Optional

Required

Required

WALLIS AND FUTUNA ISLANDS

WLF

Optional

Required

Optional

Required

Required

Appendix E: Version Specification

Using the Maven Version Range Specification [3]
Version Content Type Specification Description

[1.0,)

application/vnd.metapack.mm.v1.0+json

x >= 1.0

x is available since version 1.0 (inclusive)

[0.7.5,)

application/vnd.metapack.mm.v0.7+json

x >= 0.7.5

x is available since version 0.7.5 (inclusive)

[0.7.0,)

application/vnd.metapack.mm.v0.7+json

x >= 0.7.0

x is available since version 0.7.0 (inclusive)

(,0.7.0]

application/vnd.metapack.mm.v0.7+json

x < = 0.7.0

x is available up to version 0.7.0 (inclusive)

[0.7.0]

application/vnd.metapack.mm.v0.7+json

x == 0.7.0

x is available only in version 0.7.0

[0.6.0,)

application/vnd.metapack.mm.v0.6+json

x >= 0.6.0

x is available since version 0.6.0 (inclusive)

(,0.6.0]

application/vnd.metapack.mm.v0.6+json

x < = 0.6.0

x is available up to version 0.6.0 (inclusive)

[0.6.0]

application/vnd.metapack.mm.v0.6+json

x == 0.6.0

x is available only in version 0.6.0

[0.6.0,0.7.0]

application/vnd.metapack.mm.v0.6+json
application/vnd.metapack.mm.v0.7+json

0.6.0 < = x < = 0.7.0

x is available in versions 0.6.0 and 0.7.0

[0.7.1,)

application/vnd.metapack.mm.v0.7.1+json

x >= 0.7.1

x is available since version 0.7.1

[0.7.1]

application/vnd.metapack.mm.v0.7.1+json

x == 0.7.1

x is available only in version 0.7.1

[0.7.2,)

application/vnd.metapack.mm.v0.7.1+json

x >= 0.7.2

x is available since version 0.7.2

Appendix F: Glossary

Definition of terms used within this documentation.

Shipment

A Shipment is a Shipment Instruction derived from an Order (via an order management system) or from a consignment (logistics management system) to ship a Trade Item or Logistics Unit from one location to another via one or more Transport movements. It is expected that shipments will be fulfilled by one or more consignments (with descendants or ascendants) and one or more shipments.

Consignment

One or more logistics units that are consigned to transportation by a third party for the purposes of a physical transaction.

Logistics Service Group

A logical name given to a group of logistic services (such as "Standard", "Next day", "Evening” etc).

Logistics Services Provider

Somebody that provides Logistics Services e.g a carrier. Not necessarily the seller.

Logistics Service

A product or service that a logistics service provider provides to shippers or sellers.

Logistics Unit

When a trade item or good becomes transportable, it is said to be a Logistics Unit - something that is in a transportable state through a logistics network. Logistics units contain trade items or other logistics units. They are contained in some kind of transport equipment. Any number of logistics unit can be referenced by a shipment or consignment.

Parcel

Parcels are a type of Logistics Unit.

To Consign

Coming soon.

To Allocate

Coming soon.

Trade Item

Some kind of good or trade able item. Distinct from an product in that it could be a component or part of the product and may required assembly with a number of other trade items e.g a table (which is part of the product called 'table and chairs').

Version Number

A version number (eg 0.7.1) is composed of a major number, a minor number and (optionally) a patch number: major.minor.patch. [4]

URI

A constrained Uniform Resource Identifier, which must have the following components

  • scheme (HTTP or HTTPS)

  • host

  • path

Allocation

Coming soon.

Delivery Options

Coming soon.

Documentation

Coming soon.

Manifesting

Coming soon.

Tracking

Coming soon.

Notifications

Coming soon.

Appendix G: Timeouts

The table below shows the API maximum timeouts based on the shipment type of the request sent.

The timeouts displayed are approximate and could change in the future.
Request type approximate timeout (ms)

Shipment type Delivery

6,000

Shipment type Collection by URI

11,000

Shipment type Collection by collection points id

6,000
1. Java 8 - java.util.TimeZone::getAvailableIDs()
2. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements
3. https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html
4. http://semver.org/
©2017 MetaPack Official | eCommerce Delivery Management Software