Metapack Shipping REST API (1.0.0)

Download OpenAPI specification:Download


API overview

The Metapack Shipping REST API is an easy-to-use REST-based API that enables you to manage all of your shipping needs without having to worry about the complexities of different carrier APIs and protocols.

Common use-cases

  • Creating consignments
  • Appending parcels to consignments
  • Allocating, deallocating, and deleting consignments
  • Sending consignments with shipping rules
  • Creating labels and other paperwork for consignments and parcels
  • Creating manifests and paperwork for manifests

Features

  • Integration with the Metapack Shipping Platform (Delivery Manager).
  • Rate shopping enables you to identify the feasible services and rates for a shipment before creating the consignments and labels.
  • Labelling meets a variety of needs, from simple labelling through to complex multi-parcel shipments and customs documentation.
  • Manifesting enables you to send carriers advance notice of expected shipments.
  • Shipping rules to facilitate allocations.

Benefits

  • Simplifies and speeds up integrations with the Metapack Shipping Platform.
  • A highly scalable and powerful API across multiple geographies for the same shipper.
  • A modern API with a modern developer experience.
  • Can be used simultaneously with the Metapack Shipping SOAP API, so you can transition gradually from your integration with the SOAP API.

Getting started

The Shipping REST API can be used by both existing and new Metapack customers.

New customers must complete all of the steps to get started with the API.

Existing Metapack customers can start at step 3.

Step 1: Ensure that you have a Metapack shipper account

Using the Shipping Platform requires having a shipper account, which stores data about your warehouses and carriers.

Step 2: Ensure that you have set up the Shipping Platform correctly

After you have created your shipper account and added your warehouses to it, you need to complete a setup checklist to configure your own Shipping platform.

Step 3: Get an API key

The method that you must use to get an API key depends on whether you are an existing or new Metapack customer.
Customer Contact
Existing Your Metapack Professional Services implementation consultant
New Metapack Sales

Step 4: Base64-encode your API key

The Shipping REST API uses the HTTP basic access authentication method, so you must provide an Authorization request header with the Basic prefix followed by a Base64-encoded <username>:<password> string.

You can use Base64 Encode and Decode to encode your API key.

Step 5: Review the API reference

Browse this documentation to learn about the API resources and operations and how to use the API.

Step 6: Create a consignment

Go to the API and use your API key and cURL to create a consignment.

Tip: You can also use Postman and the Shipping REST Postman collection to familiarise yourself with the API, and to create a consignment.

Authentication

BasicAuth

To authenticate yourself to the Shipping REST API, you need to include an Authorization header in each API request.

The Authorization header comprises the prefix Basic followed by a Base64-encoded <username>:<password> string.

If you don't include the header when making an API request, the API will return a 401 Unauthorized error.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Consignments

Create and manage consignments. A shipment can be a single consignment or multiple consignments. You must create at least one consignment for a shipment before you can get shipping rates or create a label or a manifest for the shipment.

Search for consignments

Retrieve all consignments that meet specific search criteria.

If any consignments have been allocated, the associated carrier and carrier service information is also returned. You can use this information to plan your deliveries and keep your customers updated.

Authorizations:
query Parameters
orderReference
string

Return all consignments associated with a specific order identifier.

consignmentTrackingIdentifier
string

Return all consignments associated with a specific consignment tracking identifier assigned by carrier allocation.

parcelTrackingIdentifier
string

Return all consignments associated with a specific parcel tracking identifier.

parcelCode
string

Return all consignments associated with a specific parcel code.

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  'https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments?orderReference=string&consignmentTrackingIdentifier=string&parcelTrackingIdentifier=string&parcelCode=string'

Response samples

Content type
application/json
[
  • {
    }
]

Create a consignment and optionally use shipping rules to allocate it

Create a consignment without allocating it.

Alternatively, you can create it and use shipping rules to allocate it to the optimal carrier service associated with your Metapack shipper account.

Shipping rules enable you to search for an optimal subscribed carrier service by using acceptable and unacceptable collection and delivery days and date and time slots, carrier services, delivery location, and other filtering options.

Note: If a suitable subscribed carrier service is not found for the consignment, it will still be created but will remain unallocated.

Authorizations:
Request Body schema: application/json
required
object (ConsignmentRequest)

One or more items going from the same origin to the same destination being despatched on the same date using the same carrier service.

object (ShippingRules)

For each consignment, you have the option to define specific allocation parameters for that consignment, or you can reuse a predefined allocation rule that you created previously.

Responses

Request samples

Content type
application/json
{
  • "consignment": {
    },
  • "shippingRules": {
    }
}

Response samples

Content type
application/json
{
  • "consignment": {
    },
  • "links": [
    ]
}

Get a consignment

Retrieve a consignment with a specific consignment code.

If the consignment has been allocated, the associated carrier and carrier service information is also returned. You can use this information to plan your deliveries and keep your customers updated.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments/:consignmentCode

Response samples

Content type
application/json
{
  • "consignment": {
    },
  • "links": [
    ]
}

Update an unallocated consignment

Update an unallocated consignment.

Note: You must resubmit the mandatory information of the consignment in addition to any other consignment data that you have added or modified.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

Request Body schema: application/json
required
object (ConsignmentRequest)

One or more items going from the same origin to the same destination being despatched on the same date using the same carrier service.

object (ShippingRules)

For each consignment, you have the option to define specific allocation parameters for that consignment, or you can reuse a predefined allocation rule that you created previously.

Responses

Request samples

Content type
application/json
{
  • "consignment": {
    },
  • "shippingRules": {
    }
}

Response samples

Content type
application/json
{
  • "consignment": {
    },
  • "links": [
    ]
}

Delete an unallocated consignment

If the consignment is unallocated, using this operation deletes it.

However, if the consignment is allocated, using this operation first deallocates it and then deletes it.

Note: You cannot delete a consignment if its lifecycle status is "manifested" or a later status.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

Responses

Request samples

curl -i -X DELETE \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments/:consignmentCode

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string",
  • "systemMessage": "string",
  • "traceID": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Update selected properties of an unallocated consignment

Update specific numeric and text properties of an unallocated consignment.

Note: Currently, manifestGroupCode is the only property of a consignment that can be modified by this operation.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

Request Body schema: application/json
property name*
string

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "consignment": {
    },
  • "links": [
    ]
}

Get the paperwork of a consignment

Retrieve the labels and customs documents of a consignment.

Tip: To generate the labels or documents from the strings included in a successful response, you must first decode the strings by using a Base64 encoder/decoder and then send them to a network printer.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

query Parameters
type
string

Specify the type of paperwork to be generated. Select label to generate a labels string in the reponse. Select documentation to generate a customs (customs documentation) string in the response. Select all to generate a labels string and a customs string in the response.

Enum: "label" "documentation" "all"
format
string

Specify the paperwork format to be generated. Select pdf to generate the customs string in PDF format. Select zpl to generate the labels string in Zebra Programming Language (ZPL) format. Select png to generate a label as a PNG file.

Enum: "pdf" "zpl" "png"
dimension
string
Default: "6X4"

Specify the dimensions of the document. Enter either a4 or the page dimensions in inches using m×n format, where m and n are either integers or decimal numbers. For example, 6x4.

resolution
integer
Default: 200

Specify the resolution of the label in dots per inch (DPI). Select 200 to generate the label in 200 DPI. Select 300 to generate the label in 300 DPI.

Enum: 200 300

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  'https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments/:consignmentCode/paperwork?type=label&format=pdf&dimension=6X4&resolution=200'

Response samples

Content type
application/json
{
  • "paperwork": {
    },
  • "links": [
    ]
}

Verify whether shipping rules can be applied to a consignment

Verify whether a consignment can be allocated using the specified shipping rules.

Authorizations:
Request Body schema: application/json
required
object (ConsignmentRequest)

One or more items going from the same origin to the same destination being despatched on the same date using the same carrier service.

object (ShippingRules)

For each consignment, you have the option to define specific allocation parameters for that consignment, or you can reuse a predefined allocation rule that you created previously.

Responses

Request samples

Content type
application/json
{
  • "consignment": {
    },
  • "shippingRules": {
    }
}

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string",
  • "systemMessage": "string",
  • "traceID": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Parcels

Manage the parcels in consignments.

Add a parcel to a consignment

Add a parcel to an existing consignment.

If the consignment has already been allocated, the tracking code for the new parcel is generated automatically and returned in the response.

In addition, the weight and value of the new parcel are added to the weight and value of the consignment.

Note: This operation also resets the lifecycle status of a modified consignment from "ready-to-manifest" to "allocated".

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

Request Body schema: application/json
required
object (Parcel)

Responses

Request samples

Content type
application/json
{
  • "parcel": {
    }
}

Response samples

Content type
application/json
{
  • "parcel": {
    },
  • "links": [
    ]
}

Remove a parcel from a consignment

Remove a parcel from a multi-parcel consignment.

The weight of the removed parcel is subtracted automatically from the weight of the consignment.

If the consignment has already been allocated, the charges are recalculated.

Note: You can use this operation if the lifecycle status of the consignment is not later than "ready-to-manifest".

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

parcelCode
required
string

Parcel code.

Responses

Request samples

curl -i -X DELETE \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments/:consignmentCode/parcels/:parcelCode

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string",
  • "systemMessage": "string",
  • "traceID": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get the paperwork of a parcel

Retrieve the labels and customs documents of a specific parcel in an allocated consignment.

Tip: To generate the labels or documents from the strings included in a successful response, you must first decode the strings by using a Base64 encoder/decoder and then send them to a network printer.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

parcelCode
required
string

Parcel code.

query Parameters
type
string

Specify the type of paperwork to be generated. Select label to generate a labels string in the reponse. Select documentation to generate a customs (customs documentation) string in the response. Select all to generate a labels string and a customs string in the response.

Enum: "label" "documentation" "all"
format
string

Specify the paperwork format to be generated. Select pdf to generate the customs string in PDF format. Select zpl to generate the labels string in Zebra Programming Language (ZPL) format. Select png to generate a label as a PNG file.

Enum: "pdf" "zpl" "png"
dimension
string
Default: "6X4"

Specify the dimensions of the document. Enter either a4 or the page dimensions in inches using m×n format, where m and n are either integers or decimal numbers. For example, 6x4.

resolution
integer
Default: 200

Specify the resolution of the label in dots per inch (DPI). Select 200 to generate the label in 200 DPI. Select 300 to generate the label in 300 DPI.

Enum: 200 300

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  'https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments/:consignmentCode/parcels/:parcelCode/paperwork?type=label&format=pdf&dimension=6X4&resolution=200'

Response samples

Content type
application/json
{
  • "paperwork": {
    },
  • "links": [
    ]
}

Allocations

Manage the allocations of consignments to your subscribed carrier services.

Allocate an unallocated consignment to a subscribed carrier service

Use shipping rules to allocate an unallocated consignment to the optimal carrier service associated with your Metapack shipper account.

Shipping rules enable you to search for an optimal subscribed carrier service by using acceptable and unacceptable collection and delivery days and date and time slots, carrier services, delivery location, and other filtering options.

Note: If a suitable subscribed carrier service is not found for the consignment, it will remain unallocated.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

Request Body schema: application/json
object

The collection slots.

object

The delivery slots.

object

The collection days.

object

The delivery days.

carrierServices
Array of strings

Your subscribed carrier services.

code
string

The identifer of a specific allocation rule to be used.

Responses

Request samples

Content type
application/json
{
  • "collectionSlots": {
    },
  • "deliverySlots": {
    },
  • "collectionDays": {
    },
  • "deliveryDays": {
    },
  • "carrierServices": [
    ],
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "consignment": {
    },
  • "links": [
    ]
}

Delete the allocation of a consignment

Delete the allocation of a consignment to a subscribed carrier service and leave it unallocated.

To verify that the consignment is unallocated, use the getConsignment operation.

To reallocate the consignment, use the postConsignmentAllocation operation.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

Responses

Request samples

curl -i -X DELETE \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments/:consignmentCode/service

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string",
  • "systemMessage": "string",
  • "traceID": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Indicate the shipping readiness of a consignment

Flag a "printed" consignment as "ready-to-manifest".

You can then use the postManifestFutureDespatch operation to add the consignment to a post-dated manifest.

Authorizations:
path Parameters
consignmentCode
required
string

Consignment identifier generated by Metapack.

query Parameters
readyToShip
boolean

Flag the consignment as ready to ship.

Responses

Request samples

curl -i -X POST \
  -u <username>:<password> \
  'https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/consignments/:consignmentCode/status?readyToShip=true'

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string",
  • "systemMessage": "string",
  • "traceID": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Create a consignment with paperwork and allocate it

Create a consignment, use shipping rules to allocate it, and generate Base64-encoded labels and customs documents for it.

Shipping rules enable you to search for an optimal subscribed carrier service by using acceptable and unacceptable collection and delivery days and date and time slots, carrier services, delivery location, and other filtering options.

Note: If a suitable subscribed carrier service is not found for the consignment, it will still be created but will remain unallocated.

Tip: To generate the labels or documents from the strings included in a successful response, you must first decode the strings by using a Base64 encoder/decoder and then send them to a network printer.

Authorizations:
Request Body schema: application/json
required
object (ConsignmentRequest)

One or more items going from the same origin to the same destination being despatched on the same date using the same carrier service.

required
object (ShippingRules)

For each consignment, you have the option to define specific allocation parameters for that consignment, or you can reuse a predefined allocation rule that you created previously.

required
object (PaperworkRequest)

Responses

Request samples

Content type
application/json
{
  • "consignment": {
    },
  • "shippingRules": {
    },
  • "paperwork": {
    }
}

Response samples

Content type
application/json
{
  • "consignment": {
    },
  • "paperwork": {
    },
  • "links": [
    ]
}

Manifests

Create manifests and retrieve paperwork for them.

Create a manifest for future despatch

Add “ready-to-manifest” consignments to a post-dated manifest and clear the consignments from your current transactional flow.

You might want to do this because you expect a large number of orders to go out on a particular day in the future, but you want to leave sufficient time to pack and process them beforehand.

Authorizations:
Request Body schema: application/json
carrierCode
required
string

Carrier identifier.

shippingLocationCode
required
string

This is the code of the shipping location (warehouse) for which the manifest is to be created.

manifestGroupCode
string

Manifest group codes are trailer identifiers that can be used across multiple carriers. You can assign a manifest group code to a consignment before manifesting to facilitate tracing it to a specific trailer.

transactionType
string
Default: "delivery"

Specify the transaction type. Select delivery for a consignment where the goods are being despatched from a warehouse to a consumer. Select pick-up for a return consignment where the goods are being picked up from the consumer and sent back to a warehouse.

Enum: "delivery" "pick-up"
despatchDate
string <date-time>

Enter the future despatch date.

specifiedDateOnly
boolean
Default: false

Set to true only if the consignments that are due to be despatched on the specified despatchDate are to be added to the manifest. Otherwise, set it to false.

Responses

Request samples

Content type
application/json
{
  • "carrierCode": "string",
  • "shippingLocationCode": "string",
  • "manifestGroupCode": "string",
  • "transactionType": "delivery",
  • "despatchDate": "2019-08-24T14:15:22Z",
  • "specifiedDateOnly": false
}

Response samples

Content type
application/json
{
  • "links": [
    ]
}

Get the paperwork of a manifest

Generate a manifest in Base64-encoded format.

Tip: To generate the manifest as a PDF file, you must first decode the string inluded in a successful response by using a Base64 encoder/decoder and then send it to a network printer.

Authorizations:
path Parameters
manifestCode
required
string

Manifest identifier.

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/manifests/:manifestCode/paperwork

Response samples

Content type
application/json
{
  • "paperwork": {
    },
  • "links": [
    ]
}

Rates

Get shipping rates for consignments.

Create a set of shipping rates for a consignment

Verify which carrier services associated with your Metapack shipper account can offer the best rates for delivering a consignment.

You also have the option to specify shipping rules, which enable you to search for an optimal subscribed carrier service by using acceptable and unacceptable collection and delivery days and date and time slots, carrier services, delivery location, and other filtering options.

A successful response returns all carrier services that can deliver the consignment in order of shipping cost, with the cheapest first.

Note: Carrier costs must be set up correctly as part of Metapack Shipping Platform setup.

Authorizations:
Request Body schema: application/json
required
object (ConsignmentRequest)

One or more items going from the same origin to the same destination being despatched on the same date using the same carrier service.

object (ShippingRules)

For each consignment, you have the option to define specific allocation parameters for that consignment, or you can reuse a predefined allocation rule that you created previously.

Responses

Request samples

Content type
application/json
{
  • "consignment": {
    },
  • "shippingRules": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Setup

Retrieve information about the warehouses, carriers, and carrier services associated with your Metapack shipper account.

Get a list of carriers associated with your shipper account

Retrieve all carriers associated with your Metapack shipper account.

Note: These carriers are defined as part of your Metapack Shipping Platform setup.

Authorizations:

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/carriers

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of carrier services associated with your shipper account

Retrieve all carrier services associated with your Metapack shipper account.

Note: These carrier services are defined as part of your Metapack Shipping Platform setup.

Authorizations:
path Parameters
carrierCode
required
string

Carrier identifier.

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/carriers/:carrierCode/services

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of warehouses associated with your shipper account

Retrieve all warehouses associated with your Metapack shipper account.

A warehouse is any location used for shipping orders. Example locations include stores, distribution centres, and logistics channels.

Note: These warehouses are defined as part of your Metapack Shipping Platform setup.

Authorizations:

Responses

Request samples

curl -i -X GET \
  -u <username>:<password> \
  https://2343dfd5-62c3-4119-9cac-4e99cbcb5c1d.mock.pstmn.io/shippingLocations

Response samples

Content type
application/json
[
  • {
    }
]