Shipping and Tracking APIs

Welcome to Australia Post's Shipping and Tracking APIs!

Use your own systems to lodge your parcels, print labels, despatch your parcels, estimate the price of a shipment, and track the progress of the parcels from source to destination in a flexible and customisable way.

Getting started

Getting started is quick and easy, and there are multiple ways you can integrate based on your needs. You will have the chance to test your integration after signing up for an account. We will provide you access to a test environment, allowing you to freely explore the Shipping and Tracking APIs for as long as you’d like before starting with a live account.

Whatever your role is, this section is designed to help you understand:

What the Shipping and Tracking APIs can do
What I need to start using the Shipping and Tracking APIs
Which type of integration is best for my business
What customer workflows are supported

What do the Shipping and Tracking APIs do?

The Shipping and Tracking API suite integrates your systems with Australia Post, letting you:

Lodge parcels
Create a manifest, including all the shipments and articles, and lodge the parcels with Australia Post
Print labels
Print our most up-to-date labels to improve your operational efficiency
Validate suburb, state, and postcode
Makes sure your suburb, state, and postcode combination is valid
Estimate the shipment price
Get an indicative shipment price so that you can choose the service that best suits your needs, and accurately predict costs
Track your parcels
Easily surface tracking information on your website for your staff or customers

What do I need to start?

A few things:

A MyPost account
Make sure you have a MyPost account and use it to log in to Developer Portal or create a MyPost account.
A parcel contract
The Shipping and Tracking APIs are only available to contract customers, so you’ll need a parcel contract with Australia Post or be working with a customer that has one.
A preferred integration method
Before you start, decide whether you’ll be building a solution in-house, or using a platform partner. If you’re not sure, check out our integration methods in the section below.

How do I integrate with Australia Post?

Integrate directly with in-house developers

If your business has developers in-house, you can integrate directly with us.

Integrating directly can work well for your business if you:

are able to do your own IT development when integrating with our APIs, and
need full control over how you interact with Australia Post in your own systems.

What you’ll need

Your Australia Post account number
Your Australia Post merchant location ID (MLID)
Contact details for your developers

How to directly integrate with in-house developers

Step	Description
1	Make sure you have a MyPost account and use it to log in to Developer Portal or create a MyPost account.
2	Register for access to our testbed/demo environment. You’ll need your Australia Post account number and the contact details of your developer. We'll send you the URL and credentials you'll need to access the developer testbed/demo. These credentials consist of your testbed/demo client id, client secret and account number, and they generally take one day to receive. Note: The person who requests access must be an official representative of the company (account holder), and already known to Australia Post.
3	Integrate with the developer testbed/demo. For more information, refer to the documents in the left-hand navigation.
4	To validate your integration and get production access, you will need to download the Technical Validation Form, where you will need to provide information related to your implementation. This includes your sample payloads and PDF assets (such as your labels)
5	When you’re ready to go-live, submit a request through the support form. Documents can’t be attached to this form, so tick 'I want to provide an attachment to my request' and we’ll send you an email asking for your completed Technical Validation Form.
6	Our Lodgement Support team will validate your account and send you an invitation to generate a production credentials. This usually takes around 5 business days. Once you've accessed the production environment, you'll be creating manifests that will be submitted for payment. Test manifests must not be generated within the production environment.

What customer workflows are supported

Our systems are designed to accept one manifest per pickup from each Merchant Account.

This means you'll need to create multiple shipments throughout the day and combine them into one manifest prior to pick up. For the most efficient experience, you'll need to design your integration with the Shipping and Tracking APIs with this in mind.

Once the manifest has been created, you'll need to create a Manifest Summary Report. The physical document must be signed and submitted to the driver when you lodge your parcels.

Creating Australia Post labels before manifesting

When using our Shipping and Tracking APIs with the Australia Post label, you will need to print the labels before you create your manifest for pick up. This can be done at a time that best suits your business processes.

Creating your own labels

With this workflow, you print your own labels and create shipments throughout the day as you receive the parcel details. Prior to pick up, you create a manifest including all your shipments.

API reference

Authentication

The Shipping and Tracking APIs use the OAuth 2.0 authorization framework. During your onboarding as an integrated merchant, you will be provided with client credentials consisting of a client_id and a client_secret.

You will use these client credentials to request an access_token from the authorization server. You then need to send the access_token as part of the authorization header in every API call to the resource that you want to access.

OAuth 2.0

The Shipping and Tracking APIs version 2 implements the open authorisation framework known as Oauth 2.0 https://oauth.net/2/. This is an open standard supported by many companies and development frameworks. It improves on the previous version of the Shipping and Tracking APIs by not having the credentials sent in every API call, but only having the credentials exchanged in the call to retrieve the access token. Note: to retrieve the access token the caller uses the client credentials grant (flow) from the OAuth 2.0 specification. The access token is a short-lived token that has an expiry timestamp and therefore minimises the impact in case the access token is compromised.

The access token is returned in the JSON Web Token JWT format, reference: https://datatracker.ietf.org/doc/html/rfc7519. This also allows the access token to be inspected for properties (known as claims). A useful online tool for this is: https://jwt.io. Note: the access token expiry is stored in the exp claim.

As the access token can expire during the day, it is important for the caller to handle the token expiry. If an API call returns a HTTP 401 Unauthorized error then the caller should request a new access token from the token endpoint. As there is an access token cache in place within the token retrieval flow, it is not possible to request a new access token ahead of the expiry timestamp.

Get access token

This endpoint generates an access_token that you will use when calling any of the Shipping and Tracking APIs.

An access_token granted as part of this API is valid for 12 hours. A new access_token will only be generated 11 hours after the first one was requested.

For example, if you request an access_token at 9:00am, you can only generate a new one after 8:00pm.

For efficiency reasons please don't retrieve a new access_token for every API call.

Sample request

curl --location --request POST \
'https://welcome.api1.auspost.com.au/oauth/token' \
--header 'content-type: application/json' \
--data-raw '{
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "audience": "https://digitalapi.auspost.com.au/shipping/v2",
    "grant_type": "client_credentials"
}'

Authentication URL

Environment	URL
Live / Testbed / Demo	https://welcome.api1.auspost.com.au/oauth/token

Scopes

Environment	Scope in the access token
Testbed / Demo	https://scopes.auspost.com.au/auth/lodgement/v2/demo
Live	https://scopes.auspost.com.au/auth/lodgement/v2/lodge

Header parameters

Parameter	Required	Description
Content-Type	Yes	This should be set to `application/json`

Request body

Parameter	Type	Required	Description
client_id	String	Yes	The `client_id` provided to you by Australia Post when you were onboarded
client_secret	String	Yes	The `client_secret` provided to you by Australia Post when you were onboarded
audience	String	Yes	This must be set to `https://digitalapi.auspost.com.au/shipping/v2`
grant_type	String	Yes	This must be set to `client_credentials`

Sample response

{
    "access_token": "{{access_token}}",
    "scope": "https://scopes.auspost.com.au/auth/lodgement/v2/lodge",
    "expires_in": 14400,
    "token_type": "Bearer"
}

Response

Name	Type	Description
access_token	String	The access token string as issued by the authorization server
scope	String	The scopes (space separated) determine what entitlements your access token will be granted when interacting with our suite of APIs: • `https://scopes.auspost.com.au/auth/lodgement/v2/lodge` allows you to transact in a live environment • `https://scopes.auspost.com.au/auth/lodgement/v2/demo` allows you to transact in a demo environment
expires_in	Integer	The duration of time in seconds the `access_token` is granted for. The `access_token` will be valid for 43200 seconds (12 hours)
token_type	String	Type of token is always `Bearer`

Shipments

Create shipments

This endpoint creates a shipment with articles and returns a summary of the pricing. A shipment is a set of articles associated to a charge account’s location to be delivered to a single physical address.

Sample request

POST https://digitalapi.auspost.com.au/shipping/v2/shipments

curl --location --request POST 'https://digitalapi.auspost.com.au/shipping/v2/shipments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "shipments": [
        {
            "charge_account": "6543210",
            "addresses": {
                "from": {
                    "name": "John Citizen",
                    "business_name": "Citizen Pty Ltd",
                    "phone": "0401234567",
                    "email": "john.citizen@citizen.com",
                    "lines": [
                        "1 Main Street"
                    ],
                    "suburb": "Melbourne",
                    "state": "VIC",
                    "postcode": "3000"
                },
                "to": {
                    "name": "Jane Smith",
                    "business_name": "Smith Pty Ltd",
                    "phone": "0412345678",
                    "email": "jane.smith@smith.com",
                    "lines": [
                        "123 Centre Road"
                    ],
                    "suburb": "Sydney",
                    "state": "NSW",
                    "postcode": "2000"
                }
            },
            "shipment_contents":{
                "type": "DANGEROUS_GOODS",
                "attributes": {
                    "transportable_by_air": false
                }
            },
            "sender_references": [
                "XYZ-001-01"
            ],
            "service": {
                "speed": "STANDARD",
                "features": [
                    {
                        "type": "SIGNATURE_ON_DELIVERY",
                        "attributes": {
                            "delivery_option": "CARD_IF_NOT_HOME"
                        }
                    }
                ]
            },
            "articles": [
                {
                    "packaging_type": "CTN",
                    "weight": 1,
                    "length": 10,
                    "height": 10,
                    "width": 10,
                    "features": [
                        {
                            "type": "TRANSIT_COVER",
                            "attributes": {
                                "cover_amount": 100
                            }
                        }
                    ],
                    "label_references": [
                        "Order #001 - 12345"
                    ],
                    "article_references": [
                        "SKU-12345"
                    ]
                }
            ]
        }
    ]
}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token
Content-Type	Yes	Should be set to `application/json`

Request body

Parameter	Type	Required	Description
shipments	Array	Yes	Shipment information is to be supplied for each delivery of items to a physical address
charge_account	String (10)	Yes	Your Australia Post account number (for production these are up to 7-digits) which is used to price the shipment
addresses	-	Yes	Refer to Addresses block for more details
service	-	Yes	Refer to Service block for more details
shipment_contents	-	Yes	Refer to Shipment contents block for more details
sender_references	Array (3x50)	No	Merchant specified references for the shipment. Displayed on the label if article_references and label_references are not provided
delivery_instructions	String (256)	No	Merchant specified instructions to aid in prompt delivery of the parcel
articles	-	Yes	Refer to Articles block for more details
consignment_tracking_id	String (10 or 12)	No	The consignment id assigned to the shipment which can be used for tracking. This is normally generated by Australia Post during shipment creation. Refer to Tracking details for more details
movement_type	String (enum)	No	Indicates whether it is an outbound/normal shipment or a returns shipment. Valid values: • `DESPATCH` (default) • `RETURN`

Addresses block

Parameter	Type	Required	Description
addresses	-	Yes	The block containing the sender, recipient and return to sender address details
from	-	Yes	The address where the parcels will be sent from
name	String (40)	Yes	The name of the sender
business_name	String (40)	No	The name of the sending business
phone	String (24)	No	The sender's phone number
email	String (100)	No	The sender's email address
lines	Array (3x40)	Yes	The address lines for the address. At least one address line must be provided
suburb	String (40)	Yes	The suburb for the address
state	String (enum)	Yes	The state code for the address. Valid values: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`
postcode	String (4)	Yes	The postcode for the address
country	String (2)	No	The country code for the address. Default is `AU`
to	-	Yes	The address where the parcels will be delivered
name	String (40)	Yes	The name of the recipient
business_name	String (40)	No	The name of the receiving business
phone	String (24)	No	The recipient's phone number
email	String (100)	No	The recipient's email address
lines	Array (3x40)	Yes	The address lines for the address. At least one address line must be provided
suburb	String (40)	Yes	The suburb for the address
state	String (enum)	Yes	The state code for the address. Valid values: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`
postcode	String (4)	Yes	The postcode for the address
country	String (2)	No	The country code for the address. Default is `AU`
return_to_sender	-	No	The address where the parcels will be returned if not delivered. Defaults to the sender address if not provided in the request. If present, some attributes will be required. Only applies to outbound shipments and ignored for returns
name	String (40)	Yes	The name of the return contact
business_name	String (40)	No	The name of the business for the return
phone	String (24)	No	The return contact's phone number
email	String (100)	No	The return contact's email address
lines	Array (3x40)	Yes	The address lines for the address. At least one address line must be provided
suburb	String (40)	Yes	The suburb for the address
state	String (enum)	Yes	The state code for the address. Valid values: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`
postcode	String (4)	Yes	The postcode for the address
country	String (2)	No	The country code for the address. Default is `AU`

Service block

Parameter	Type	Required	Description
service	-	Yes	The block containing the desired speed and shipment features
speed	String (enum)	Yes	The chosen delivery speed. Valid values: • `STANDARD` • `PREMIUM_EXPRESS`
partial_delivery	Boolean	No	Indicates whether articles can be delivered to their final destination as they become available or whether all articles in the resulting shipment must be delivered together. The default is `true`.
features	-	No	The block containing the features to be applied at shipment-level
type	String (enum)	No	The specific type of feature to be applied at shipment-level. Valid values: • `LEAVE_IN_A_SAFE_PLACE` (default) • `SIGNATURE_ON_DELIVERY` • `CAPTURE_ID`
attributes	-	See below	Depending on the feature type selected, attributes maybe required
delivery_option	String (enum)	Yes, when type is `SIGNATURE_ON_DELIVERY`	See Features
id_capture_option	String (enum)	Yes, when type is `CAPTURE_ID`	See Features

Shipment contents block

Parameter	Type	Required	Description
shipment_contents	-	Yes	The block describing the contents of the shipment
type	String (enum)	Yes	The contents must be classified according to the acceptable types. Valid values: • `NEUTRAL` • `DANGEROUS_GOODS` (see Dangerous goods)
attributes	-	-	Depending on the shipment contents type selected, attributes maybe required.
transportable_by_air	Boolean	Yes, when type is `DANGEROUS_GOODS`	See Dangerous goods

Articles block

Parameter	Type	Required	Description
articles	-	Yes	An article element is to be supplied for each parcel
description	String (50)	No	Merchant specified description of the article
packaging_type	String (enum)	No	The packaging type for the parcel. Valid values: • `CTN` for carton • `SAT` for satchel
weight	Decimal (2.3)	Yes	The weight of the parcel in kilograms. Maximum value: `32`. Optional for `RETURN`
length	Decimal (3.1)	See description	The length of the parcel in centimetres. Maximum value: `113`. If volumetric pricing applies, then this is mandatory. Optional for `RETURN`
height	Decimal (3.1)	See description	The height of the parcel in centimetres. Maximum value: `113`. If volumetric pricing applies, then this is mandatory. Optional for `RETURN`
width	Decimal (3.1)	See description	The width of the parcel in centimetres. Maximum value: `113`. If volumetric pricing applies, then this is mandatory. Optional for `RETURN`
dangerous_goods_declaration	String (enum)	See description	See Dangerous goods
article_references	Array (3x50)	No	Merchant specified references for the article. Displayed on the label if label_references is not provided
label_references	Array (3x50)	No	Merchant specified references for the article specifically for the purposes of displaying on the label. If not provided, article_references or sender_references will be displayed on the label
features	-	No	The block containing the features to be applied at article level
type	String (enum)	No	The specific type of feature to be applied at article level. Valid values: • `TRANSIT_COVER`
attributes	-	See Features	Depending on the feature type selected, attributes maybe required
article_tracking_id	String (21 or 23, 20 if SSCC)	No	The article id assigned to the article which can be used for tracking. This is normally generated by Australia Post during shipment creation. Refer to Tracking details for more details
article_barcode_data	String (100)	No	The barcode id assigned to the article. This is normally generated by Australia Post during shipment creation. Refer to Tracking details for more details

Sample response

{
    "shipments": [
        {
            "shipment_id": "e28434257ecc4385b7587b1b64c9189c",
            "consignment_tracking_id": "ABC0000001",
            "shipment_creation_date": "2020-08-25T09:17:36+10:00",
            "articles": [
                {
                    "article_id": "a53c04c048484268bcb49b5e99f6de3e",
                    "article_tracking_id": "ABC000000101002001404"
                }
            ],
            "currency": "AUD",
            "total_price_exc_gst": 7.38,
            "total_gst": 0.74,
            "total_price_inc_gst": 8.12
        }
    ]
}

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the identifiers and the estimated shipment price.

Name	Type	Description
shipments	Array	Shipment information for each shipment and articles created
shipment_id	String	The Australia Post generated identifier for the shipment
consignment_tracking_id	String	The consignment id assigned to the shipment which can be used for tracking
shipment_creation_date	Date & Time	The date and time the shipment was created
articles	Array	An article element is to be supplied for each parcel
article_id	String	The Australia Post generated identifier for the article
article_tracking_id	String	The article id assigned to the shipment which can be used for tracking
currency	String	The currency at which the shipment was priced
total_price_exc_gst	Decimal (N.2)	The total estimated price of the shipment excluding GST
total_gst	Decimal (N.2)	The total estimated GST of the shipment
total_price_inc_gst	Decimal (N.2)	The total estimated price of the shipment including GST

Sample error response

{
    "id": "c12850a61b8635c9",
    "errors": [
        {
            "code": "AUTHORISATION_ERROR",
            "detail": "Charge account is invalid. Check details or contact support.",
            "field": "#/shipments/0/charge_account"
        }
    ]
}

Error codes

Response code	Error code	Description	Remarks
403	`AUTHORISATION_ERROR`	Charge account is invalid. Check details or contact support.
400	`VALIDATION_ERROR`	Shipment request can't contain shipments with different charge accounts.
400	`VALIDATION_ERROR`	Combination of suburb, state & postcode doesn't match.
400	`SCHEMA_VALIDATION_ERROR`	Valid state for addresses is `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`.	Domestic address validation
400	`SCHEMA_VALIDATION_ERROR`	Recipient country must be `AU`. Sender country must be `AU`. Return to sender country must be `AU`.
400	`SCHEMA_VALIDATION_ERROR`	Shipment contents type {type} isn't supported.
400	`SCHEMA_VALIDATION_ERROR`	Two of the dimensions must be at least `5` cm.
400	`SCHEMA_VALIDATION_ERROR`	{Dimension} must be greater than `0` cm.
400	`SCHEMA_VALIDATION_ERROR`	{Dimension} must not exceed `113` cm.
400	`SCHEMA_VALIDATION_ERROR`	{Dimension} must have at most `1` decimal place.
400	`VALIDATION_ERROR`	Cubic volume must not exceed `0.25` m3.
400	`SCHEMA_VALIDATION_ERROR`	Weight must be greater than `0` kg.
400	`SCHEMA_VALIDATION_ERROR`	Weight must not exceed `32` kg.
400	`SCHEMA_VALIDATION_ERROR`	Weight must have at most `3` decimal places.
400	`SCHEMA_VALIDATION_ERROR`	Cover amount must be at least $`1.00`.
400	`VALIDATION_ERROR`	Shipment can't have duplicate feature types.
400	`VALIDATION_ERROR`	Article can't have duplicate feature types.
400	`SCHEMA_VALIDATION_ERROR`	Shipment can't exceed `99` articles.
400	`SCHEMA_VALIDATION_ERROR`	Returns can't have more than `1` article.
400	`VALIDATION_ERROR`	Shipment request can't exceed `1000` articles.
400	`VALIDATION_ERROR`	Consignment tracking id {value} identified as a duplicate. Article tracking id {value} identified as a duplicate. Article barcode data {value} identified as a duplicate.
400	`SCHEMA_VALIDATION_ERROR`	Shipment can't contain article tracking ids with different formats.
400	`VALIDATION_ERROR`	Sender references can only contain letters, numbers, spaces, and the following symbols: # - : . ,
400	`VALIDATION_ERROR`	Article references can only contain letters, numbers, spaces, and the following symbols: # - : . ,
400	`VALIDATION_ERROR`	Label references can only contain letters, numbers, spaces, and the following symbols: # - : . ,

Get shipments

This endpoint retrieves information for shipments, and the articles contained within shipments created using the Create shipments service.

Sample request

GET https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}

curl --location --request GET 'https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}' \
--header 'Authorization: Bearer {{access_token}}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token

Path parameters

Parameter	Type	Required	Description
shipment_id	String	Yes	The shipment id you wish to retrieve. Separate multiple values with a comma (`,`)

Sample response

{
    "shipments": [
        {
            "consignment_tracking_id": "ABC0000001",
            "addresses": {
                "from": {
                    "name": "John Citizen",
                    "business_name": "Citizen Pty Ltd",
                    "email": "john.citizen@citizen.com",
                    "phone": "0401234567",
                    "lines": [
                        "1 Main Street"
                    ],
                    "suburb": "Melbourne",
                    "state": "VIC",
                    "postcode": "3000",
                    "country": "AU"
                },
                "to": {
                    "name": "Jane Smith",
                    "business_name": "Smith Pty Ltd",
                    "email": "jane.smith@smith.com",
                    "phone": "0412345678",
                    "lines": [
                        "123 Centre Road"
                    ],
                    "suburb": "Sydney",
                    "state": "NSW",
                    "postcode": "2000",
                    "country": "AU",
                    "type": "STANDARD_ADDRESS"
                },
                "return_to_sender": {
                    "name": "John Citizen",
                    "business_name": "Citizen Pty Ltd",
                    "email": "john.citizen@citizen.com",
                    "phone": "0401234567",
                    "lines": [
                        "1 Main Street"
                    ],
                    "suburb": "Melbourne",
                    "state": "VIC",
                    "postcode": "3000",
                    "country": "AU"
                }
            },
            "service": {
                "speed": "STANDARD",
                "partial_delivery": true,
                "features": [
                    {
                        "attributes": {
                            "delivery_option": "CARD_IF_NOT_HOME"
                        },
                        "type": "SIGNATURE_ON_DELIVERY"
                    }
                ]
            },
            "sender_references": [
                "XYZ-001-01"
            ],
            "shipment_contents": {
                "type": "NEUTRAL"
            },
            "articles": [
                {
                    "weight": 1,
                    "length": 10,
                    "height": 10,
                    "width": 10,
                    "packaging_type": "CTN",
                    "features": [
                        {
                            "attributes": {
                                "cover_amount": 100
                            },
                            "type": "TRANSIT_COVER"
                        }
                    ],
                    "label_references": [
                        "Order #001 - 12345"
                    ],
                    "article_references": [
                        "SKU-12345"
                    ],
                    "article_tracking_id": "ABC000000101002001404",
                    "article_id": "a53c04c048484268bcb49b5e99f6de3e"
                }
            ],
            "movement_type": "DESPATCH",
            "charge_account": "6543210",
            "shipment_id": "e28434257ecc4385b7587b1b64c9189c",
            "shipment_creation_date": "2020-08-25T09:17:36+10:00",
            "currency": "AUD",
            "total_price_inc_gst": 8.12,
            "total_price_exc_gst": 7.38,
            "total_gst": 0.74
        }
    ]
}

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the complete shipment and article details.

Name	Type	Description
shipments	Array	Shipment information for each shipment and articles created
consignment_tracking_id	String	The consignment id assigned to the shipment which can be used for tracking. This is normally generated by Australia Post during shipment creation. This can also be merchant supplied - refer to Tracking details
addresses	-	Similar to the details found in the Create shipments request
to	-	Similar to the details found in the Create shipments request
type	String	The address type as inferred from the recipient address line 1. Values: • `STANDARD_ADDRESS` • `PARCEL_LOCKER` • `PARCEL_COLLECT` • `PO_BOX` • `PUDO_LOCKER` (Doddle) • `PUDO_COLLECT` (Doddle) • `PUDO_HOST` (Doddle)
service	-	Similar to the details found in the Create shipments request
sender_references	Array	Similar to the details found in the Create shipments request
shipment_contents	-	Similar to the details found in the Create shipments request
articles	Array	An article element is to be supplied for each parcel
article_id	String	The Australia Post generated identifier for the article
article_tracking_id	String	The article id assigned to the article which can be used for tracking. This is normally generated by Australia Post during shipment creation. This can also be merchant supplied - refer to Tracking details
article_barcode_data	String	The barcode id assigned to the article. This is normally generated by Australia Post after the Create labels request. This can also be merchant supplied - refer to Tracking details
article details	-	Similar to the details found in the Create shipments request
movement_type	String	Indicates whether it is an outbound/normal shipment or a returns shipment
charge_account	String	The Australia Post account number used to price the shipment
shipment_id	String	The Australia Post generated identifier for the shipment
shipment_creation_date	Date & Time	The date and time the shipment was created
shipment_modified_date	Date & Time	The date and time the shipment was modified
currency	String	The currency at which the shipment was priced
total_price_exc_gst	Decimal (N.2)	The total estimated price of the shipment excluding GST
total_gst	Decimal (N.2)	The total estimated GST of the shipment
total_price_inc_gst	Decimal (N.2)	The total estimated price of the shipment including GST

Sample error response

{
    "id": "e896825f5164953c",
    "errors": [
        {
            "code": "SHIPMENT_NOT_FOUND",
            "detail": "The shipment ID or all shipment IDs can't be found."
        }
    ]
}

Error codes

Response code	Error code	Description
404	`SHIPMENT_NOT_FOUND`	The shipment ID or all shipment IDs can't be found.
400	`VALIDATION_ERROR`	Shipment id is invalid.

Update shipment

This endpoint updates an existing shipment that has previously been created using the Create shipments service.

If you have generated a label prior to updating an existing article, it is recommended that you reprint the label after the update request. For changes to the service parameters that result in a different article_tracking_id, you will not be allowed to manifest until the label is reprinted.

Sample request

PUT https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}

curl --location --request PUT 'https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "shipment_id": "{{shipment_id}}",
    "charge_account": "6543210",
    "addresses": {
        "from": {
            "name": "John Citizen",
            "business_name": "Citizen Pty Ltd",
            "phone": "0401234567",
            "email": "john.citizen@citizen.com",
            "lines": [
                "1 Main Street"
            ],
            "suburb": "Melbourne",
            "state": "VIC",
            "postcode": "3000"
        },
        "to": {
            "name": "Jane Smith",
            "business_name": "Smith Pty Ltd",
            "phone": "0412345678",
            "email": "jane.smith@smith.com",
            "lines": [
                "123 Centre Road"
            ],
            "suburb": "Sydney",
            "state": "NSW",
            "postcode": "2000"
        }
    },
    "shipment_contents":{
        "type": "DANGEROUS_GOODS",
        "attributes": {
            "transportable_by_air": true
        }
    },
    "service": {
        "speed": "PREMIUM_EXPRESS",
        "features": [
            {
                "type": "SIGNATURE_ON_DELIVERY",
                "attributes": {
                    "delivery_option": "CARD_IF_NOT_HOME"
                }
            }
        ]
    },
    "sender_references": [
        "XYZ-001-01"
    ],
    "articles": [
        {
            "article_id": "{{article_id}}",
            "packaging_type": "CTN",
            "length": 10,
            "height": 10,
            "width": 10,
            "dangerous_goods_declaration": "UN3481_Lithium_IonOrPolymer_contained_in_equipment",
            "weight": 1,
            "features": [
                {
                    "type": "TRANSIT_COVER",
                    "attributes": {
                        "cover_amount": 100
                    }
                }
            ],
            "label_references": [
                "Order #001 - 12345"
            ],
            "article_references": [
                "SKU-12345"
            ]
        },
        {
            "packaging_type": "CTN",
            "length": 20,
            "height": 20,
            "width": 20,
            "dangerous_goods_declaration": "UN3481_Lithium_IonOrPolymer_contained_in_equipment",
            "weight": 2,
            "features": [
                {
                    "type": "TRANSIT_COVER",
                    "attributes": {
                        "cover_amount": 100
                    }
                }
            ],
            "label_references": [
                "Order #002 - 67890"
            ],
            "article_references": [
                "Additional article"
            ]
        }
    ]
}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token

Request parameters

Parameter	Type	Required	Description
shipment_id	String	Yes	The specific `shipment_id` you wish to update
article_id	String	No	The specific `article_id` you wish to update. If not provided, it will replace the existing articles in the selected shipment
shipment details	-	-	Similar to the details found in the Create shipments request
article details	-	-	Similar to the details found in the Create shipments request

Sample response

{
    "shipment_id": "e28434257ecc4385b7587b1b64c9189c",
    "consignment_tracking_id": "ABC0000001",
    "shipment_creation_date": "2020-08-25T09:17:36+10:00",
    "shipment_modified_date": "2020-08-27T10:34:02+10:00",
    "articles": [
        {
            "article_id": "a53c04c048484268bcb49b5e99f6de3e",
            "article_tracking_id": "ABC000000101002021406"
        },
        {
            "article_id": "ccab9386d63f41adba2c98cdeb726f2a",
            "article_tracking_id": "ABC000000102002021403"
        }
    ],
    "currency": "AUD",
    "total_price_exc_gst": 14.64,
    "total_gst": 1.46,
    "total_price_inc_gst": 16.10
}

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the identifiers and the estimated shipment price.

Name	Type	Description
shipment_id	String	The Australia Post generated identifier for the shipment
consignment_tracking_id	String	The consignment id assigned to the shipment which can be used for tracking
shipment_creation_date	Date & Time	The date and time the shipment was created
shipment_modified_date	Date & Time	The date and time the shipment was modified
articles	Array	An article element is to be supplied for each parcel
article_id	String	The Australia Post generated identifier for the article
article_tracking_id	String	The article id assigned to the shipment which can be used for tracking
currency	String	The currency at which the shipment was priced
total_price_exc_gst	Decimal (N.2)	The total estimated price of the shipment excluding GST
total_gst	Decimal (N.2)	The total estimated GST of the shipment
total_price_inc_gst	Decimal (N.2)	The total estimated price of the shipment including GST

Sample error response

{
    "id": "e896825f5164953c",
    "errors": [
        {
            "code": "SHIPMENT_NOT_FOUND",
            "detail": "Shipment ID 1234567890 can't be found."
        }
    ]
}

Error codes

Response code	Error code	Description
404	`SHIPMENT_NOT_FOUND`	Shipment ID {shipmentId} can't be found.
404	`ARTICLE_NOT_FOUND`	Article ID {articleId} can't be found.
400	`SHIPMENT_MANIFESTED`	Shipment ID {shipmentId} can't be changed because it is included in manifest ID {manifestId}.
400	`VALIDATION_ERROR`	Shipment can't have duplicate article IDs.
400	`VALIDATION_ERROR`	Article-level tracking details must be provided for all articles.
400	`VALIDATION_ERROR`	Consignment tracking id can't be changed.
400	`VALIDATION_ERROR`	Article tracking id {value} identified as a duplicate. Article barcode data {value} identified as a duplicate.
400	`SCHEMA_VALIDATION_ERROR`	Some will be similar to the details found in the Create shipments error codes
400	`VALIDATION_ERROR`	Some will be similar to the details found in the Create shipments error codes

Delete shipment

This endpoint deletes one or more shipments that have not have been included in a manifest.

Sample request

DELETE https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}

curl --location --request DELETE 'https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}' \
--header 'Authorization: Bearer {{access_token}}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token

Path parameters

Parameter	Type	Required	Description
shipment_id	String	Yes	The shipment id you wish to delete. Separate multiple values with a comma (`,`)

Sample response

Empty body

Response

A successful request returns the HTTP 204 No Content status code and an empty JSON response body.

Sample error response

{
    "id": "8ee8de5f75c4cf98",
    "errors": [
        {
            "code": "SHIPMENT_MANIFESTED",
            "detail": "Shipment ID 1234567890 can't be deleted because it is included in manifest ID PC0000000001."
        }
    ]
}

Error codes

Response code	Error code	Description
404	`SHIPMENT_NOT_FOUND`	Shipment ID {shipmentId} can't be found.
400	`VALIDATION_ERROR`	Shipment id is invalid.
400	`SHIPMENT_MANIFESTED`	Shipment ID {shipmentId} can't be deleted because it is included in manifest ID {manifestId}.

Delete article

This endpoint deletes one or more articles from a shipment that has not been included in a manifest.

Sample request

DELETE https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}/articles/{article_id}

curl --location --request DELETE 'https://digitalapi.auspost.com.au/shipping/v2/shipments/{shipment_id}/articles/{article_id}' \
--header 'Authorization: Bearer {{access_token}}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token

Path parameters

Parameter	Type	Required	Description
shipment_id	String	Yes	The shipment id of the article id you wish to delete
article_id	String	Yes	The article id you wish to delete. Separate multiple values with a comma (`,`)

Sample response

Empty body

Response

A successful request returns the HTTP 204 No Content status code and an empty JSON response body.

Sample error response

{
    "id": "9712b26c3a749326",
    "errors": [
        {
            "code": "SHIPMENT_MANIFESTED",
            "detail": "Article/s can't be deleted because it is included in manifest ID PC0000000001."
        }
    ]
}

Error codes

Response code	Error code	Description
404	`SHIPMENT_NOT_FOUND`	Shipment ID {shipmentId} can't be found.
404	`ARTICLE_NOT_FOUND`	Article ID {articleId} can't be found.
400	`VALIDATION_ERROR`	Shipment id is invalid.
400	`VALIDATION_ERROR`	Article id is invalid.
400	`SHIPMENT_MANIFESTED`	Shipment ID {shipmentId} can't be deleted because it is included in manifest ID {manifestId}.
400	`SHIPMENT_MANIFESTED`	Article/s can't be deleted because it is included in manifest ID {manifestId}.
400	`NO_ARTICLES_LEFT`	Article/s can't be deleted because a shipment must have at least one article.

Labels

Create labels

This endpoint generates the labels for the requested shipments that have been previously created using the Create shipments service.

Labels for a subset of articles in a shipment can be generated by providing a list of article ids.

Sample request

POST https://digitalapi.auspost.com.au/shipping/v2/labels

curl --location --request POST 'https://digitalapi.auspost.com.au/shipping/v2/labels' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "shipment_ids": [
        "{{shipment_id}}"
    ],
    "preferences": {
        "format": "PDF",
        "layout": "A4_1PP",
        "left_offset": 0,
        "top_offset": 0
    },
    "additional_processing_options" : {
        "add_instructions_for": [
            "RETURNS"
        ]
    }
}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token
Content-Type	Yes	Should be set to `application/json`

Request body

Parameter	Type	Required	Description
shipment_ids	Array	See description	List each shipment for which you want labels generated. This is required if article_ids array is not provided
article_ids	Array	See description	List each article for which you want labels generated. This is required if shipment_ids array is not provided
preferences	-	No	Specifies print preferences to be applied. Default settings will apply if not provided in the request
format	String (enum)	No	Specifies the print format. Valid values: • `PDF` (default)
layout	String (enum)	No	Specifies the number of labels per page and the size of the page. Valid values: • `A6_1PP` (default) • `A4_4PP` • `A4_1PP`
left_offset	Integer	No	Adjusts the left margin of the page. Valid values: `-200` to `200`. Default is `0`
top_offset	Integer	No	Adjusts the top margin of the page. Valid values: `-200` to `200`. Default is `0`
additional_processing_options	-	No	Specifies additional processing options that can be applied to labels. Default settings will apply if not provided in the request.
add_instructions_for	Array (enum)	No	Specify the movement type of the labels for which the instructions are to be printed. Valid values: `RETURNS` Default value: `empty array` Constraints: if `add_instructions_for` array block is not null and is valid value, then `preferences.layout` must be set to `A4_1PP`, else `VALIDATION_ERROR` is returned.

Sample response

{
    "label_id": "b7c5e71b-b1d0-4e92-aefa-163ef2048352",
    "label_url": "https://auspost.com.au/lodgement/v2/labels/b7c5e71b-b1d0-4e92-aefa-163ef2048352.pdf?"
}

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the link to the label.

Name	Type	Description
label_id	String	The identifier for the request, generated and returned by the Create Labels service
label_url	String	The HTTP URL from which to download the label

Sample error response

{
    "id": "b2359e4604c323e8",
    "errors": [
        {
            "code": "UNABLE_TO_PRINT_SHIPMENT_NOT_FOUND",
            "detail": "Shipment ID 1234567890 can't be found."
        }
    ]
}

Error codes

Response code	Error code	Description
404	`UNABLE_TO_PRINT_SHIPMENT_NOT_FOUND`	Shipment ID {shipmentId} can't be found.
404	`UNABLE_TO_PRINT_ARTICLE_NOT_FOUND`	Article ID {articleId} can't be found.
400	`SCHEMA_VALIDATION_ERROR`	Label request must have either shipment ids or article ids.
400	`SCHEMA_VALIDATION_ERROR`	Left offset must be at least `-200` mm. Top offset must be at least `-200` mm.
400	`SCHEMA_VALIDATION_ERROR`	Left offset must not exceed `200` mm. Top offset must not exceed `200` mm.
400	`VALIDATION_ERROR`	Labels can't be printed - shipment id fe4184194eb848c0ac03fc83b292ac40 was manifested more than 24 hours ago. Please contact the lodgement support team.
400	`VALIDATION_ERROR`	Label instructions are only supported with label layout A4_1PP.
400	`VALIDATION_ERROR`	Labels can't be printed - request can't exceed `30` different charge accounts.

Manifests

Create manifest

This endpoint creates a manifest for the referenced shipments that have previously been created using the Create shipments service.

Sample request

POST https://digitalapi.auspost.com.au/shipping/v2/manifests

curl --location --request POST 'https://digitalapi.auspost.com.au/shipping/v2/manifests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "shipment_ids": [
        "{{shipment_id}}"
    ]
}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token
Content-Type	Yes	Should be set to `application/json`

Request body

Parameter	Type	Required	Description
shipment_ids	Array	Yes	List each shipment you want to include in the manifest
consignor	String (40)	No	The name of the consignor for this manifest. This information is included in the delivery documentation to assist traceability

Sample response

{
    "manifest_id": "PC0000000001",
    "manifest_creation_date": "2020-08-25T12:49:58+10:00"
}

Response

A successful request returns the HTTP 201 Created status code.

Name	Type	Description
manifest_id	String	The Australia Post generated identifier for the manifest
manifest_creation_date	Date & Time	The date and time the manifest was created

Sample error response

{
    "id": "3a88e8114af86c48",
    "errors": [
        {
            "code": "VALIDATION_ERROR",
            "detail": "Shipment ID 1234567890 has already been manifested, you can't create another manifest for it.",
            "field": "#/shipment_ids"
        }
    ]
}

Error codes

Response code	Error code	Description
404	`UNABLE_TO_MANIFEST_SHIPMENT_NOT_FOUND`	Shipment ID {shipmentId} can't be found.
400	`VALIDATION_ERROR`	Shipment ID {shipmentId} must have all labels printed first.
400	`VALIDATION_ERROR`	Shipment ID {shipmentId} has already been manifested, you can't create another manifest for it.
400	`VALIDATION_ERROR`	Manifests can't contain shipments with different charge accounts.
400	`VALIDATION_ERROR`	Manifests can't contain shipments with different movement types.
400	`VALIDATION_ERROR`	Manifest request can't exceed `2000` articles.

Get manifest

This endpoint retrieves information related to a manifest previously created using the Create manifest service.

Sample request

GET https://digitalapi.auspost.com.au/shipping/v2/manifests/{manifest_id}

curl --location --request GET 'https://digitalapi.auspost.com.au/shipping/v2/manifests/{manifest_id}' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw ''

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token

Path parameters

Parameter	Type	Required	Description
manifest_id	String	Yes	The Australia Post generated identifier for the manifest

Sample response

{
    "manifest_id": "PC0000000001",
    "manifest_creation_date": "2020-08-25T13:00:18+10:00",
    "consignor": "Consignor",
    "shipments": [
        {
            "shipment_id": "e28434257ecc4385b7587b1b64c9189c",
            "consignment_tracking_id": "ABC0000001",
            "addresses": {
                "from": {
                    "name": "John Citizen",
                    "business_name": "Citizen Pty Ltd",
                    "email": "john.citizen@citizen.com",
                    "phone": "0401234567",
                    "lines": [
                        "1 Main Street"
                    ],
                    "suburb": "Melbourne",
                    "state": "VIC",
                    "postcode": "3000",
                    "country": "AU"
                },
                "to": {
                    "name": "Jane Smith",
                    "business_name": "Smith Pty Ltd",
                    "email": "jane.smith@smith.com",
                    "phone": "0412345678",
                    "lines": [
                        "123 Centre Road"
                    ],
                    "suburb": "Sydney",
                    "state": "NSW",
                    "postcode": "2000",
                    "country": "AU",
                    "dpid": -5
                },
                "return_to_sender": {
                    "name": "John Citizen",
                    "business_name": "Citizen Pty Ltd",
                    "email": "john.citizen@citizen.com",
                    "phone": "0401234567",
                    "lines": [
                        "1 Main Street"
                    ],
                    "suburb": "Melbourne",
                    "state": "VIC",
                    "postcode": "3000",
                    "country": "AU"
                }
            },
            "service": {
                "speed": "STANDARD",
                "partial_delivery": true,
                "features": [
                    {
                        "attributes": {
                            "delivery_option": "CARD_IF_NOT_HOME"
                        },
                        "type": "SIGNATURE_ON_DELIVERY"
                    }
                ]
            },
            "sender_references": [
                "XYZ-001-01"
            ],
            "shipment_contents": {
                "type": "NEUTRAL"
            },
            "articles": [
                {
                    "article_id": "a53c04c048484268bcb49b5e99f6de3e",
                    "weight": 1,
                    "length": 10,
                    "height": 10,
                    "width": 10,
                    "cubic_weight": 0.25,
                    "packaging_type": "CTN",
                    "features": [
                        {
                            "attributes": {
                                "cover_amount": 100
                            },
                            "type": "TRANSIT_COVER"
                        }
                    ],
                    "label_references": [
                        "Order #001 - 12345"
                    ],
                    "article_references": [
                        "SKU-12345"
                    ],
                    "article_tracking_id": "ABC000000101002001404",
                    "article_barcode_data": "019931265099999891K63000161401002001400|4202000|8008200825125438"
                }
            ],
            "movement_type": "DESPATCH",
            "shipment_creation_date": "2020-08-25T09:17:36+10:00",
            "manifest_id": "PC0000000001",
            "manifest_creation_date": "2020-08-25T03:00:18Z",
            "charge_account": "6543210"
        }
    ]
}

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the complete manifest, shipment and article details.

Name	Type	Description
manifest_id	String	The Australia Post generated identifier for the manifest
manifest_creation_date	Date & Time	The date and time the manifest was created
consignor	String	The name of the consignor for this manifest
shipment details	-	Similar to the details found in the Get shipments response
article details	-	Similar to the details found in the Get shipments response

Sample error response

{
    "id": "da6f47c0a136180d",
    "errors": [
        {
            "code": "MANIFEST_NOT_FOUND",
            "detail": "Manifest ID 1234567890 can't be found."
        }
    ]
}

Error codes

Response code	Error code	Description
404	`MANIFEST_NOT_FOUND`	Manifest ID {manifestId} can't be found.
400	`VALIDATION_ERROR`	Manifest ID is invalid.

Get manifest summary

This endpoint returns the PDF summary document that contains a breakdown of the shipments in the manifest.

Sample request

GET https://digitalapi.auspost.com.au/shipping/v2/manifests/{manifest_id}/summary

curl --location --request GET 'https://digitalapi.auspost.com.au/shipping/v2/manifests/{manifest_id}/summary' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw ''

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token

Path parameters

Parameter	Type	Required	Description
manifest_id	String	Yes	The Australia Post generated identifier for the manifest

Sample response

{
    "manifest_id": "PC0000000001",
    "manifest_summary_url": "https://ptest.npe.auspost.com.au/lodgement/v2/manifest/7f2f586f-6025-4b3d-958f-3238197dce99.pdf?"
}

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the link to the PDF manifest summary.

Name	Type	Description
manifest_id	String	The Australia Post generated identifier for the manifest
manifest_summary_url	String	The HTTP URL from which to download the manifest summary

Sample error response

{
    "id": "412a95e967505428",
    "errors": [
        {
            "code": "MANIFEST_NOT_FOUND",
            "detail": "Manifest ID 1234567890 can't be found."
        }
    ]
}

Error codes

Response code	Error code	Description
404	`MANIFEST_NOT_FOUND`	Manifest ID {manifestId} can't be found.
400	`VALIDATION_ERROR`	Manifest ID is invalid.

Pricing

Estimate shipment price

This endpoint estimates the price of a shipment and returns a summary of the pricing.

Sample request

POST https://digitalapi.auspost.com.au/shipping/v2/prices

curl --location --request POST 'https://auspost.com.au/shipping/v2/prices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "shipments": [
        {
            "charge_account": "6543210",
            "addresses": {
                "from": {
                    "postcode": "3000"
                },
                "to": {
                    "postcode": "2000"
                }
            },
            "service": {
                "speed": "PREMIUM_EXPRESS",
                "features": [
                    {
                        "type": "SIGNATURE_ON_DELIVERY",
                        "attributes": {
                            "delivery_option": "CARD_IF_NOT_HOME"
                        }
                    }
                ]
            },
            "articles": [
                {
                    "length": 30,
                    "height": 30,
                    "width": 30,
                    "weight": 31,
                    "features": [
                        {
                            "type": "TRANSIT_COVER",
                            "attributes": {
                                "cover_amount": 250
                            }
                        }
                    ]
                }
            ],
            "movement_type": "DESPATCH"
        }
    ]
}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token
Content-Type	Yes	Should be set to `application/json`

Request body

Parameter	Type	Required	Description
shipments	Array	Yes	Shipment information is to be supplied for each delivery of items to a physical address
charge_account	String (10)	Yes	Your Australia Post account number (for production these are up to 7-digits) which is used to price the shipment
addresses	-	Yes	The block containing the sender, recipient and return to sender address details
from	-	Yes	The address where the parcels will be sent from
postcode	String (4)	Yes	The postcode for the address
to	-	Yes	The address where the parcels will be delivered
postcode	String (4)	Yes	The postcode for the address
postcode	String (4)	Yes	The postcode for the address
service	-	Yes	The block containing the desired speed and shipment features
speed	String (enum)	Yes	The chosen delivery speed. Valid values: • `STANDARD` • `PREMIUM_EXPRESS`
features	-	No	The block containing the features to be applied at shipment level
type	String (enum)	No	The specific type of feature to be applied at shipment level. Valid values: • `LEAVE_IN_A_SAFE_PLACE` (default) • `SIGNATURE_ON_DELIVERY` • `CAPTURE_ID`
attributes	-	See Features	Depending on the feature type selected, attributes maybe required
articles	-	Yes	An article element is to be supplied for each parcel
weight	Decimal (2.3)	Yes	The weight of the parcel in kilograms. Maximum value: `32`. Optional for `RETURN`
length	Decimal (3.1)	See description	The length of the parcel in centimetres. Maximum value: `113`. If volumetric pricing applies, then this is mandatory. Optional for `RETURN`
height	Decimal (3.1)	See description	The height of the parcel in centimetres. Maximum value: `113`. If volumetric pricing applies, then this is mandatory. Optional for `RETURN`
width	Decimal (3.1)	See description	The width of the parcel in centimetres. Maximum value: `113`. If volumetric pricing applies, then this is mandatory. Optional for `RETURN`
features	-	No	The block containing the features to be applied at article level
type	String (enum)	No	The specific type of feature to be applied at article level. Valid values: • `TRANSIT_COVER`
attributes	-	See Features	Depending on the feature type selected, attributes maybe required
movement_type	String (enum)	No	Indicates whether it is an outbound/normal shipment or a returns shipment. Valid values: • `DESPATCH` (default) • `RETURN`

Sample response

{
    "shipments": [
        {
            "movement_type": "DESPATCH",
            "currency": "AUD",
            "total_price_inc_gst": 30.49,
            "total_price_exc_gst": 27.72,
            "total_gst": 2.77,
            "shipment_summary": {
                "shipment_features_price": 3.75,
                "shipment_surcharges_price": 0.00,
                "shipment_fees_price": 0.00,
                "shipment_articles_price": 23.97,
                "details": {
                    "shipment_features": [
                        {
                            "name": "Signature on Delivery",
                            "type": "SIGNATURE_ON_DELIVERY",
                            "attributes": {
                                "delivery_option": "CARD_IF_NOT_HOME"
                            },
                            "price": 3.75
                        }
                    ],
                    "article_summary": {
                        "service_price": 20.55,
                        "features_price": 2.50,
                        "surcharges_price": 0.92,
                        "fees_price": 0.00
                    },
                    "shipment_surcharges": [],
                    "shipment_fees": []
                }
            },
            "articles": [
                {
                    "article_price_exc_gst": 23.97,
                    "details": {
                        "service": {
                            "base_price": 3.50,
                            "kg_price": 17.05
                        },
                        "features": [
                            {
                                "name": "Transit Cover",
                                "type": "TRANSIT_COVER",
                                "attributes": {
                                    "cover_amount": "250.00"
                                },
                                "price": 2.50
                            }
                        ],
                        "surcharges": [
                            {
                                "name": "Fuel Surcharge",
                                "type": "FUEL_SURCHARGE_FIXED",
                                "value": "2.50%",
                                "price": 0.51
                            },
                            {
                                "name": "Security Management Surcharge",
                                "type": "SECURITY_MANAGEMENT_SURCHARGE",
                                "value": "2.00%",
                                "price": 0.41
                            }
                        ],
                        "fees": [],
                        "cubic_weight": 6.750
                    }
                }
            ]
        }
    ]
}

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the identifiers and the estimated shipment price.

Name	Type	Description
shipments	Array	Shipment information for each shipment and articles created
movement_type	String	Indicates whether it is an outbound/normal shipment or a returns shipment. Valid values: • `DESPATCH` (default) • `RETURN`
currency	String	The currency at which the shipment was priced
total_price_inc_gst	Decimal (N.2)	The total estimated price of the shipment including GST
total_price_exc_gst	Decimal (N.2)	The total estimated price of the shipment excluding GST
total_gst	Decimal (N.2)	The total estimated GST of the shipment
shipment_summary	-	Refer to Shipment summary for more details
articles	Array	Refer to Articles for more details

Response Estimate Shipment Price - Shipment summary

Name	Type	Description
shipment_summary	-	Price summary for the shipment, breaking the shipment down into totals for features/surcharges applied at shipment level and article totals
shipment_features_price	Decimal (N.2)	The total price of features priced at shipment-level. Note: this does not include article-level features. This price will be pre-GST.
shipment_surcharges_price	Decimal (N.2)	The total price of surcharges priced at shipment-level. Note: this does not include article-level surcharges. This price will be pre-GST.
shipment_fees_price	Decimal (N.2)	The total price of fees priced at shipment-level. Note: this does not include article-level fees. This price will be pre-GST.
shipment_articles_price	Decimal (N.2)	The total price of the articles within the shipment. This includes the service, article-feature & article-surcharge prices. This price will be pre-GST.
details	-	The features and surcharges that were applied at shipment-level along with an article-level summary
shipment_features	Array	A given feature will be included here if it was priced at a shipment-level.
name	String	The name of the feature priced at shipment-level.
type	String	The feature code name passed into the price request.
attributes	String	Depending on the feature type, attributes may also be required in the pricing response. See Features
price	Decimal (N.2)	The price of the shipment-level feature. This price will be pre-GST
article_summary	Array	-
service_price	Decimal (N.2)	The total service (speed) price for all the articles in the shipment: - this includes base/subsequent + per kg prices for the selected speed. This price will be pre-GST.
features_price	Decimal (N.2)	The total features price for all the articles in the shipment: - this includes all features priced at article-level. This price will be pre-GST.
surcharges_price	Decimal (N.2)	The total surcharges price for all the articles in the shipment: - this includes all surcharges priced at article-level. This price will be pre-GST.
fees_price	Decimal (N.2)	The total fees price for all the articles in the shipment: - this includes all fees priced at article-level. This price will be pre-GST.
shipment_surcharges	Array	A given surcharge will be included here if it was priced at a shipment-level.
name	String	The name of the surcharge priced at shipment-level
type	String	The surcharge code for the surcharge priced at shipment-level
value	String	This is the value used to derive the surcharge price. Example: the % rate applied
price	Decimal (N.2)	The price of the shipment-level surcharge. This price will be pre-GST
shipment_fees	Array	A given fee will be included here if it was priced at a shipment-level.
name	String	The name of the fee priced at shipment-level
type	String	The fee code for the fee priced at shipment-level
value	String	This is the value used to derive the fee price. Example: the % rate applied
price	Decimal (N.2)	The price of the shipment-level fee. This price will be pre-GST

Response Estimate Shipment Price - Articles

Name	Type	Description
articles	Array	Summary information for each article in the shipment
article_price_exc_gst	Decimal (N.2)	The total price of the article, excluding goods and services tax (GST)
details	-	Details for article showing the breakdown of the article totals above
service	-
base_price	Decimal (N.2)	The base/subsequent price for the chosen speed (pre-GST) for the article.
kg_price	Decimal (N.2)	The per kg price for the chosen speed (pre-GST) for the article. This will not be returned for a flat-rate `RETURN`.
features	Array	A given feature will be included here if it was priced at an article-level.
name	String	The name of the feature priced at article-level. Example: Transit Cover
type	String	The feature code name passed into the price request. Example: `TRANSIT_COVER`
attributes	String	Depending on the feature type, attributes may also be required in the pricing response. In the case of Transit Cover, it is the cover amount for which the Transit Cover was priced. See Features
price	Decimal (N.2)	The price for the feature priced at article-level (pre-GST)
surcharges	Array	A given surcharge will be included here if it was priced at an article-level.
name	String	The name of the surcharge priced at article-level. Example: Fuel Surcharge
type	String	The surcharge code for the surcharge priced at article-level. Example: `FUEL_SURCHARGE_FIXED`
value	String	This is the value used to derive the surcharge price. Example: the % rate applied.
price	Decimal (N.2)	The price for the surcharge priced at article-level (pre-GST).
fees	Array	A given fee will be included here if it was priced at an article-level.
name	String	The name of the fee priced at article-level.
type	String	The fee code for the fee priced at article-level.
value	String	This is the value used to derive the fee price. Example: the % rate applied.
price	Decimal (N.2)	The price for the fee priced at article-level (pre-GST).
cubic_weight	Decimal (N.3)	The cubic weight calculated for a given article when pricing. If cubic weight is not calculated when pricing a given article, then cubic_weight will not be passed in the pricing response

Sample error response

{
    "id": "71560a0f690d4f87",
    "errors": [
        {
            "code": "AUTHORISATION_ERROR",
            "detail": "Charge account is invalid. Check details or contact support.",
            "field": "#/charge_account"
        }
    ]
}

Error codes

Response code	Error code	Description	Remarks
403	`AUTHORISATION_ERROR`	Charge account is invalid. Check details or contact support.
400	`VALIDATION_ERROR`	Shipment request can't contain shipments with different charge accounts.
400	`SCHEMA_VALIDATION_ERROR`	Sender postcode is invalid. Recipient postcode is invalid.	Address lines, suburb, state, country are all currently ignored in the Pricing endpoints
400	`SCHEMA_VALIDATION_ERROR`	Two of the article dimensions must be at least `5` cm.
400	`SCHEMA_VALIDATION_ERROR`	{Dimension} must be greater than `0` cm.
400	`SCHEMA_VALIDATION_ERROR`	{Dimension} must not exceed `113` cm.
400	`SCHEMA_VALIDATION_ERROR`	{Dimension} must have at most `1` decimal place.
400	`VALIDATION_ERROR`	Cubic volume must not exceed `0.25` m3.
400	`SCHEMA_VALIDATION_ERROR`	Article weight must be greater than `0` kg.
400	`SCHEMA_VALIDATION_ERROR`	Article weight must not exceed `32` kg.
400	`SCHEMA_VALIDATION_ERROR`	Article weight must have at most `3` decimal places.
400	`SCHEMA_VALIDATION_ERROR`	Cover amount must be at least $`1.00`.
400	`VALIDATION_ERROR`	Shipment can't have duplicate feature types.
400	`VALIDATION_ERROR`	Article can't have duplicate feature types.
400	`SCHEMA_VALIDATION_ERROR`	Shipment can't exceed `99` articles.
400	`SCHEMA_VALIDATION_ERROR`	Returns can't have more than `1` article.
400	`VALIDATION_ERROR`	Estimate shipment price request can't exceed `1000` articles.
500	`PRICING_ERROR`	Price for shipment[XXXX] can’t be calculated. For further assistance, please contact your Account Manager.	XXXX = the sequence number of the shipment as per the order of shipments passed in the request
500	`DATA_NOT_FOUND`	Price for shipment[XXXX] can’t be calculated. For further assistance, please contact your Account Manager.	XXXX = the sequence number of the shipment as per the order of shipments passed in the request

Miscellaneous

Validate suburb

This endpoint validates a suburb, state, and postcode combination for an Australian postal address and returns the acceptable suburbs for the given state and postcode.

Sample request

GET https://digitalapi.auspost.com.au/shipping/v2/address

curl --location --request GET 'https://digitalapi.auspost.com.au/shipping/v2/address?suburb=Greensborough&state=VIC&postcode=3088' \
--header 'Authorization: Bearer {{access_token}}'

Header parameters

Parameter	Required	Description
Authorization	Yes	Must be set to `Bearer`. Use the `access_token` generated from Get access token

Path parameters

Parameter	Type	Required	Description
suburb	String (40)	Yes	The suburb for the address
state	String (enum)	Yes	The state code for the address. Valid values: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`
postcode	String (4)	Yes	The postcode for the address

Sample response

{
    "found": true,
    "results": [
        "BRIAR HILL",
        "GRACE PARK",
        "GREEN HILLS",
        "GREENSBOROUGH",
        "SAINT HELENA",
        "ST HELENA"
    ]
}

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the valid suburbs for the given state and postcode.

Name	Type	Description
found	Boolean	If the submitted suburb, state, and postcode combination is valid, this will be `true`. If the state and postcode combination is valid, and the suburb name is not found, this will be `false`
results	Array	A list of acceptable suburb names based upon the submitted state and postcode

Sample error response

{
    "id": "fc4847db8f6fa46a",
    "errors": [
        {
            "code": "VALIDATION_ERROR",
            "detail": "State is invalid.",
            "field": "#URL_PARAM:state"
        }
    ]
}

Error codes

Response code	Error code	Description
400	`VALIDATION_ERROR`	Suburb is invalid.
400	`VALIDATION_ERROR`	State is invalid.
400	`VALIDATION_ERROR`	Postcode is invalid.

Get charge accounts

This service retrieves the charge accounts the authenticated user can transact on.

Sample request

GET https://digitalapi.auspost.com.au/shipping/v2/auth/charge-accounts/

curl --location --request GET 'https://digitalapi.auspost.com.au/shipping/v2/auth/charge-accounts/' \
--header 'Authorization: Bearer {{access_token}}'

Header parameters

Parameter	Required	Description
Authorization	Yes	`Bearer` token value. See Get access token

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the client ID and authorised charge accounts that the client ID can transact on.

Element name	Description	Type
`customer_identifier`	client_id used to search for authorised charge accounts.	String
`customer_identifier_type`	Customer identifier type. Valid values: `CLIENT_ID`, `C_NUMBER`, `USER`	String (enum)
`authorised_charge_accounts`	A list of authorised charge accounts with the type string.	Array

Sample Response

{
  "customer_identifier": "client_id_1",
  "customer_identifier_type": "CLIENT_ID",
  "authorised_charge_accounts": [
    "account1",
    "account2"
  ]
}

Error codes

Response code	Error code	Description
403	`HTTP_FORBIDDEN`	Invalid credentials

Errors

Error response structure

Sample error response

{
    "id": "c12850a61b8635c9",
    "errors": [
        {
            "code": "AUTHORISATION_ERROR",
            "detail": "Charge account is invalid. Check details or contact support.",
            "field": "#/shipments/0/charge_account"
        }
    ]
}

An unsuccessful request returns the appropriate HTTP status code and a JSON response body with the following details.

Name	Type	Description
id	String	The identifier for the error message which can be used by our support teams
errors	Array	Error information is to be supplied for each error message encountered when calling any of the API endpoints
code	String	A high-level description of the error encountered
detail	String	A more detailed description of the error encountered
field	String	In certain cases, the location (path) where the error occurred will be displayed
sub_code	String	In certain cases, a more descriptive error code to describe the error encountered

HTML response codes

The Shipping and Tracking APIs use the following HTML response codes:

Response code	Meaning
200	`OK` — Successful request
201	`Created` — Successful request
204	`No Content` — Successful deletion request
400	`Bad Request` — Your request is invalid
401	`Unauthorized` — Your authorisation header or access token is invalid
403	`Forbidden` — Your credentials are valid but do not have suffcient authority (e.g. incorrect charge account)
404	`Not Found` — The specified resource could not be found
500	`Internal Server Error` — We had a problem with our server. Try again later

Common error messages

The following errors are used across various endpoints:

Response code	Error code	Description	Remarks
400	`SCHEMA_VALIDATION_ERROR`	Mandatory detail {field name} is missing.	When a required field is not provided
400	`SCHEMA_VALIDATION_ERROR`	{field name} should be of type {field type}.	When the value provided is an incorrect data type
400	`SCHEMA_VALIDATION_ERROR`	{field name} exceeds {maxLength} characters.	When the value provided exceeds the maximum length
400	`SCHEMA_VALIDATION_ERROR`	{field name} is invalid.	When the value provided does not follow the expected format/pattern
400	`SCHEMA_VALIDATION_ERROR`	{field name} {error data} isn't supported.	When the value provided is not one of the acceptable enum values
400	`SCHEMA_VALIDATION_ERROR`	{field name} must have at most {array size} lines.	When the array exceeds the size definition
403	`AUTHORISATION_ERROR`	This action can’t be performed due to a charge account error. For further assistance, contact your Credit Officer (details are on your tax invoice).	`sub_code` will be `CHARGE_ACCOUNT_ERROR`
500	`SYSTEM_ERROR`	An unexpected error has occurred. If this problem continues, send us a support request via: auspost.com.au/lodgement-techsupport.

SCHEMA_VALIDATION_ERROR occurs where there is a problem with the structure of the request or an invalid character is included. You must resolve this type of error first because it prevents the validation being run in full.

Business rules

Features

A feature represents optional extras that you can add to the base service to add peace of mind to your delivery. Simply choose which of the below features you need when you lodge your parcel.

Depending on the desired feature, they may be applicable either at shipment-level or article-level. There may be additional attributes required depending on the selected feature type.

Leave in a safe place

Want to have the parcel delivered even when the recipient is not able to receive it in person? This feature allows our drivers and posties to leave the parcel in a safe place.

Sample service block with LEAVE_IN_A_SAFE_PLACE feature

 "service": {
        "speed": "STANDARD",
        "features": [
            {
                "type": "LEAVE_IN_A_SAFE_PLACE"
            }
        ]
    }

How to add this feature

This is the default feature at shipment-level so you may choose to leave it out or specify under service.features with type set to LEAVE_IN_A_SAFE_PLACE

This feature is available for movement types DESPATCH and RETURN.

Signature on Delivery

Want to know the parcel has been delivered and signed for? Signature on Delivery captures a signature of the recipient once the parcel has been delivered.

Sample service block with SIGNATURE_ON_DELIVERY feature

 "service": {
        "speed": "STANDARD",
        "features": [
            {
                "type": "SIGNATURE_ON_DELIVERY",
                "attributes": {
                    "delivery_option": "CARD_IF_NOT_HOME"
                }
            }
        ]
    }

How to add this feature

Specify at shipment-level, under service.features with type set to SIGNATURE_ON_DELIVERY
Under attributes, specify one of the accepted values for delivery_option

`delivery_option`	Description	Remarks
`CARD_IF_NOT_HOME`	A signature and name will be captured when your customer is at home. If not, the parcel will be taken to a nearby Post Office to sign for the parcel	Available for movement types `DESPATCH` and `RETURN`
`RECIPIENT_CAN_CHOOSE_SAFE_DROP`	A signature and name will be captured when your customer is at home. If not, the parcel will be left in a safe place if your customer has requested this during the delivery process (through MyPost or through an invitation if they receive email tracking notifications). In all other cases, a notification card will be left and the parcel taken to a nearby Post Office	Available for movement type `DESPATCH`

Capture ID

Want to know your parcel has been delivered and signed for with added security of identity check? This feature checks the ID and captures the signature of the recipient once the parcel has been delivered.

Sample service block with CAPTURE_ID

 "service": {
        "speed": "STANDARD",
        "features": [
            {
                "type": "CAPTURE_ID",
                "attributes": {
                    "id_capture_option": "ADDRESSEE_ONLY"
                }
            }
        ]
    }

How to add this feature

Specify at shipment-level, under service.features with type set to CAPTURE_ID
Under attributes, specify one of the accepted values for id_capture_option

`id_capture_option`	Description	Remarks
`ADDRESSEE_ONLY`	Requires only the Addressed Receiving Person at the physical recipient address to present a valid form of identification - Passport, proof of Age card or a valid Australian Drivers License	Available for movement type `DESPATCH`
`OCCUPANT`	Requires any person at the physical recipient address to present a valid form of identification - Passport, Proof of Age Card or a valid Australian Drivers License	Not available for Customer Pilot

Transit Cover

Provides you with cover for the specified value if a parcel is lost or damaged while being carried by Australia Post. Note: minimum, maximum and default transit cover may apply, depending on your contract terms and conditions.

Sample article features block with TRANSIT_COVER

 "features": [
    {
        "type": "TRANSIT_COVER",
        "attributes": {
            "cover_amount": 100
        }
    }
]

How to add this feature

Specify at article-level, under features with type set to TRANSIT_COVER
Under attributes, specify the desired cover_amount in Decimal (N.2) format

This feature is available for movement types DESPATCH and RETURN.

Returns

The Shipping and Tracking APIs can be used to generate a return shipment and create a return label to be sent to your customer so they do not have to pay for the postage to return their goods. You must manifest the return shipment after a label has been created.

Creating a return shipment

In order to create a return shipment, you will use the Create shipments API with slight differences in the parameters that are supplied.

You must set the movement_type to RETURN
You set the addresses.from to indicate the person lodging the return
You set the addresses.to to indicate the merchant receiving the return
You do not have to provide the dimensions (length, width and height) and weight
You can only include one article
You do not need to provide the partial_delivery attribute as this is ignored

Creating a return label

In order to create a return label, you will use the Create labels API. It will be used the same way you create labels for outbound shipments.

Creating a return manifest

In order to create a manifest for returns, you will use the Create manifest API. It will be used the same way you create a manifest for outbound shipments. As a rule, you are not allowed to create a manifest that contains both outbound shipments and return shipments.

A manifest summary report is not applicable for returns so you do not have to generate this document.

Dangerous goods

Sample request for a shipment containing dangerous goods

POST https://digitalapi.auspost.com.au/shipping/v2/shipments

curl --location --request POST 'https://digitalapi.auspost.com.au/shipping/v2/shipments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "shipments": [
        {
            "charge_account": "6543210",
            "addresses": {
                "from": {
                    "name": "John Citizen",
                    "business_name": "Citizen Pty Ltd",
                    "phone": "0401234567",
                    "email": "john.citizen@citizen.com",
                    "lines": [
                        "1 Main Street"
                    ],
                    "suburb": "Melbourne",
                    "state": "VIC",
                    "postcode": "3000"
                },
                "to": {
                    "name": "Jane Smith",
                    "business_name": "Smith Pty Ltd",
                    "phone": "0412345678",
                    "email": "jane.smith@smith.com",
                    "lines": [
                        "123 Centre Road"
                    ],
                    "suburb": "Sydney",
                    "state": "NSW",
                    "postcode": "2000"
                }
            },
            "shipment_contents": {
              "type": "DANGEROUS_GOODS",
              "attributes": {
                "transportable_by_air": true
              }
            }
            "sender_references": [
                "XYZ-001-01"
            ],
            "service": {
                "speed": "PREMIUM_EXPRESS",
                "features": [
                    {
                        "type": "SIGNATURE_ON_DELIVERY",
                        "attributes": {
                            "delivery_option": "CARD_IF_NOT_HOME"
                        }
                    }
                ]
            },
            "articles": [
                {
                    "packaging_type": "CTN",
                    "weight": 1,
                    "length": 10,
                    "height": 10,
                    "width": 10,
                    "dangerous_goods_declaration": "UN3481_Lithium_IonOrPolymer_contained_in_equipment",
                    "features": [
                        {
                            "type": "TRANSIT_COVER",
                            "attributes": {
                                "cover_amount": 100
                            }
                        }
                    ],
                    "label_references": [
                        "Order #001 - 12345"
                    ],
                    "article_references": [
                        "SKU-12345"
                    ]
                }
            ]
        }
    ]
}'

Requirements for parcels considered to be dangerous goods vary depending on the chosen service - whether it can be fulfilled by air or by road transport, and whether it's an outbound shipment or a return.

If you need more information about Australia Post's dangerous and prohibited items rules, please refer to the guidelines and read the quick reference guide.

How to declare parcels containing dangerous goods

During shipment creation or update, shipment_contents must always be explicitly provided. If you want to send dangerous goods that meet the Australia Post guidelines, you MUST set the shipment_contents.type to DANGEROUS_GOODS.
Under shipment_contents.attributes, you must set the transportable_by_air flag according to the chosen speed.
Depending on the chosen speed and movement_type, you may be required to specify the dangerous_goods_declaration attribute at article-level.

The following table explains the rules for dangerous goods for a given combination of speed and movement_type:

speed	movement_type	Parameter	Required
`STANDARD`	`DESPATCH` or `RETURN`	`transportable_by_air` `dangerous_goods_declaration`	Yes, can be TRUE or FALSE No, any value entered will be ignored
`PREMIUM_EXPRESS`	`DESPATCH`	`transportable_by_air` `dangerous_goods_declaration`	Yes, but it must be TRUE Yes, must be one of the allowed 6 UN numbers: • UN2910_radioactive_excepted_limited_qty • UN2911_radioactive_excepted_instruments_or_articles • UN3373_BioSubstance_B • UN3481_Lithium_IonOrPolymer_contained_in_equipment • UN3091_Lithium_MetalAndAlloy_contained_in_equipment • UN1845_DryIce_and_UN3373_BioSubstance_B Articles within the same shipment may have different values
`PREMIUM_EXPRESS`	`RETURN`	`transportable_by_air` `dangerous_goods_declaration`	Yes, but it must be TRUE Yes, must be one of the allowed 4 UN numbers: • UN2910_radioactive_excepted_limited_qty • UN2911_radioactive_excepted_instruments_or_articles • UN3373_BioSubstance_B • UN1845_DryIce_and_UN3373_BioSubstance_B

Addresses

Ensure your system adheres to the minimum (1) and maximum (3) number of address lines and the maximum length of these lines (40).

Australian addresses don't usually have a "city" component. If your system includes a field for city, you can use this value as the "suburb" field when communicating with the API.

Origin address

When the user enters a physical address (such as their ship-from address), use the Validate suburb API call to check the suburb/state/postcode combinations.

This must be specified at all times at shipment-level under the addresses.from block.

Destination address

Your system may provide a way to manually enter a destination address. If so, we recommend that you use the Validate suburb API call to check the suburb/state/postcode combinations to minimise errors when creating shipments.

If importing orders from an eCommerce platform, we recommend that you validate the address prior to attempting to create the shipment – either at the time of import or at the time of creating the label.

This must be specified at all times at shipment-level under the addresses.to block.

Return to sender address

When the parcel becomes undeliverable, you have the option to provide a return-to-sender address which may be different to the ship-from address.

This can specified at shipment-level under the addresses.return_to_sender block.

This only applies to outbound shipments and not for returns. If this is specified for returns, it will be ignored.

Post Office Boxes

Please ensure you accept "PO Box" and "GPO Box" and similar addresses, as these are valid and commonly-used addresses within Australia.

Parcel collection addresses

Australia Post offers Parcel Locker and Parcel Collect services. These services are growing in popularity amongst merchants and consumers, so we recommend that you confirm that your system accepts these types of addresses.

The following examples show typical Parcel Locker and Parcel Collect addresses:

Parcel Locker	Parcel Collect
Parcel Locker 1001278912 211 Tucker Road Mckinnon VIC 3204	Parcel Collect 1001278912 2307 Point Nepean Road Rye VIC 3941

Tracking details

Merchants are given the option to manage their own labels. In order to do this, you must provide your own consignment, article, and barcode identifiers for each parcel. If these attributes are not supplied, Australia Post will generate the tracking identifiers.

To use your own tracking details, you must provide the following information using the required format at the right level:

Identifier	Parameter	Type	Required	Description
Consignment	consignment_tracking_id	String (10 or 12)	Yes	Specified at shipment-level. The first 3 or 5 alphanumeric characters represent your MLID. The letters must be in UPPERCASE. Then, it must be followed by exactly 7 digits. Examples: `ABC0000001` or `33XYZ0000001`
Article	article_tracking_id	String (21 or 23, 20 if SSCC)	Yes	Specified at article-level. Option 1: Must start with the consignment_tracking_id followed by exactly 11 digits. Example: `ABC000000100000010203` Option 2: Must be provided in SSCC format with exactly 20 digits including the two leading zeros. Example: `00001234560000000018`
Barcode	article_barcode_data	String (100)	Yes	Specified at article-level. A string representing your barcode identifier. This accepts numbers, UPPERCASE letters and the pipe character. If this is provided, you must generate the labels on your own and you cannot use the Create labels endpoint.

Usage information

REST and authentication

The Shipping and Tracking APIs use a RESTful architecture and the OAuth 2.0 authorization framework.

All POST and PUT requests expect a data payload to be sent as the HTTP body, together with specific header values. The request payload is always JSON format (which must be specified using the Content-Type header). JSON does not enforce element order within messages and any client implementation must not assume an order within elements.

GET and DELETE requests expect parameters in the URL, together with specific header values.

HTTP header

Here is an example of a complete list of required headers:

--header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access_token}}' \

Content-Type header

The client must specify the content type of the request body within the HTTP header. The client is required to send JSON content in the body, the following header needs to be specified: Content-Type: application/json

Authentication header

HTTP Bearer authentication scheme is used for all API service calls. The client must generate an access_token using their client credentials. See Authentication for more details on how to generate an access_token.

Field formats

Decimals

Throughout the documentation, we use the following notation to indicate the format of fields containing fixed point or decimal numbers: N.M

N is the maximum number of digits to the left of the decimal point, and M is the maximum number of digits to the right of the decimal point.

For example, "6.2" means up to 6 digits left of the decimal point and up to 2 digits to the right.

When there is no imposed limit on the number of digits to the left of the decimal point, we use this notation: N.2, N.3, ... This means the maximum number of digits on the right of the decimal point is provided, but there is no limit on the number of digits on the left. In these cases, extremely large numbers are possible.

When providing a decimal value to an API service, in all cases the API service treats the decimal point and fractional part as optional. For example, sending "9" is the same as sending "9.0".

Date and time

Except where otherwise indicated, the API services use this XSD (XML Schema Definition) Date/Time format for response fields:

yyyy ’-‘ mm ’-‘ dd ‘T’ hh ‘:’ mm ‘:’ ss (‘.’ s+)? (zzzzzz)?

where:

yyyy is the year
mm is the month
dd is the day
The letter ‘T’ signifies that the time will follow
hh is the hour in 24 hour time
mm is the minute of the hour
ss is the second of the minute
. s+ (if present) represents the fractional seconds
zzzzz (if present) represents the timezone

For example: 2005-06-10T14:20:17+10:00

For further information, refer to https://www.w3.org/TR/xmlschema-2/#dateTime

Allowed characters

A number of attributes have restrictions in regards to what characters are allowed to be provided.

Object	Parameter	Allowed characters
Shipment	sender_references article_references label_references	Letters (uppercase and lowercase), numbers, spaces, symbols # @ - : _ . , An error is generated if the attribute contains characters outside this list
Shipment	from.name to.name return_to_sender.name	Letters (uppercase and lowercase), numbers, spaces, symbols . , / ' & - The shipment will be persisted and strip off any characters outside this list
Shipment	from.business_name to.business_name return_to_sender.business_name	Letters (uppercase and lowercase), numbers, spaces, symbols . , / ' & - The shipment will be persisted and strip off any characters outside this list
Shipment	delivery_instructions	Letters (uppercase and lowercase), numbers, spaces, symbols . , - The shipment will be persisted and strip off any characters outside this list
Shipment	article.description	Letters (uppercase and lowercase), numbers, spaces, symbols . , - The shipment will be persisted and strip off any characters outside this list
Shipment	from.lines to.lines return_to_sender.lines	Letters (uppercase and lowercase), numbers, spaces, symbols . , / ' & - The shipment will be persisted and strip off any characters outside this list
Manifest	consignor	Letters (uppercase and lowercase), numbers, spaces, symbols . , / ' & - The manifest will be persisted and strip off any characters outside this list

Strip whitespace

Strip leading and trailing whitespace from data that you send to the API. For example, a space after a suburb name may cause the API to reject the address.

Testing

Learn how to test the Shipping and Tracking APIs without writing software.

Install Postman

One of the tools successfully used in development testing is an app called Postman. You can click here to download the app.

Download Postman collection

Once you've installed Postman or registered for the online version, you can download our latest API collection.

Import Postman collection

To import and use the collection in Postman, follow these steps:

Click Import.
Under Files, click Upload Files.
Navigate to where you downloaded the collection above. Select Import to confirm.
The collection uses an "environment" to control the API's URL, and your credentials. Click Environments, then the + button to create a new environment.
Create a name for your environment, e.g. "Demo".
You need the following parameters added as environment variables:

Parameter	Description
`url`	Specifies the URL to access the Shipping and Tracking APIs
`charge_account`	Your Australia Post account number (for production these are up to 7-digits)
`client_id`	The `client_id` provided to you by Australia Post when you were onboarded
`client_secret`	The `client_secret` provided to you by Australia Post when you were onboarded

Migration

If you are an existing customer currently integrated with our Shipping and Tracking APIs, this section provides an overview of the differences between the two versions of the API suites to help you with your migration journey.

What's different between v1 and v2

This section describes the major differences between the Shipping and Tracking v1 and v2 APIs.

v1	v2
When authenticating requests...
You provide a `username` and `password`	You get an `access_token` using your `client_id` and `client_secret`
When creating shipments...
You specify the `account-number` in the request header	You specify the `charge_account` in the request body
You specify the `product_id`	You specify the `service.speed` plus the optional `service.features`
You specify individual parcels under `items`	You specify individual parcels under `articles`
You cannot specify a `return_to_sender` address	You can specify an optional `return_to_sender` address
You specify the complete set of `tracking_details` for each individual parcel if you want to generate your own labels. The `tracking_details` include the `consignment_id`, `article_id`, `barcode_id`	You specify the `consignment_tracking_id` once at shipment-level and for each individual parcel, the `article_tracking_id` and the `article_barcode_data`. The tracking details include the `consignment_tracking_id`, `article_tracking_id` and `article_barcode_data`. All tracking details are mandatory when generating your own labels.
When creating labels...
You may have to send up to two API requests (Create label + Get label) to generate a label	You generate the label in a single Create labels request
You must specify both `shipment_id` and `item_id` if you want to print labels for specific articles	You only need to specify the `article_ids` to print labels for specific articles
When creating a manifest...
You despatch shipments into an `order`	You despatch shipments into a `manifest`
You can create an order including shipments	There is no functionality yet to create a manifest including shipments (BACKLOG)
When creating a manifest summary document...
You *Save to a file* to download the order summary pdf	You click a URL to download the manifest summary pdf (same as the Create labels response)
When you want to know the price breakdown...
You see a detailed price breakdown when creating a shipment	You only see a shipment-level price during Create shipment (excluding and including GST). The Estimate shipment price endpoint will give the detailed price breakdown
You can estimate the postage price for an item and it will be returned for available products	There is no functionality yet to estimate the shipment price and return it for various speeds (BACKLOG)

Field translation from v1 to v2 APIs

This section describes how the data elements map between the Shipping and Tracking v1 and v2 APIs.

Shipment

v1 Element Name		v2 Element Name	Remarks
shipments	→	shipments
account-number	→	charge_account	Renamed and moved from header to request
		addresses	NEW - Required
from	→	from
name	→	name
business_name	→	business_name
phone	→	phone
email	→	email
lines	→	lines
suburb	→	suburb
state	→	state
postcode	→	postcode
country	→	country
to	→	to
name	→	name
business_name	→	business_name
phone	→	phone
email	→	email
lines	→	lines
suburb	→	suburb
state	→	state
postcode	→	postcode
country	→	country
delivery_instructions	→	delivery_instructions	Moved from `to` to `shipments`
		return_to_sender	NEW - Optional block
		name	NEW
		business_name	NEW
		phone	NEW
		email	NEW
		lines	NEW
		suburb	NEW
		state	NEW
		postcode	NEW
		country	NEW
		service	NEW - Required
		speed	NEW - Required
features	→	features	Moved and usage is slightly different
name	→	type	Renamed and usage is slightly different
attributes	→	attributes	Moved and usage is slightly different
		delivery_option	NEW - Required for features.type = `SIGNATURE_ON_DELIVERY`
		id_capture_option	NEW - Required for features.type = `CAPTURE_ID`
		shipment_contents	NEW - Optional
		type	NEW
		attributes	NEW
sender_references	→	sender_references
items	→	articles	Renamed
item_description	→	description	Renamed
packaging_type	→	packaging_type
weight	→	weight
length	→	length
height	→	height
width	→	width
		article_references	NEW - Optional
		label_references	NEW - Optional
dangerous_goods_declaration	→	dangerous_goods_declaration
transportable_by_air	→	transportable_by_air	Moved from `items` to `shipment_contents.attributes`
allow_partial_delivery	→	partial_delivery	Renamed and moved from `items` to `service`
tracking_details	→		Removed and underlying elements modified
consignment_id	→	consignment_tracking_id	Renamed and moved from `items.tracking_details` to `shipments`
article_id	→	article_tracking_id	Renamed and moved from `items.tracking_details` to `articles`
barcode_id	→	article_barcode_data	Renamed and moved from `items.tracking_details` to `articles`
features	→	features
name	→	type	Renamed
attributes	→	attributes
cover_amount	→	cover_amount
movement_type	→	movement_type

Label

v1 Element Name		v2 Element Name	Remarks
shipments.shipment_id	→	shipment_ids	Simplified array that contains a list of shipment IDs. Generates the labels for all the articles in the shipments
shipments.items.item_id	→	article_ids	Simplified array that contains a list of article IDs. Generates the labels for specific articles
preferences	→	preferences	Set from required to optional
format	→	format
groups.layout	→	layout	Removed `groups`
groups.left_offset	→	left_offset	Removed `groups`
groups.top_offset	→	top_offset	Removed `groups`

Manifest

v1 Element Name		v2 Element Name	Remarks
shipments.shipment_id	→	shipment_ids	Simplified array that contains a list of shipment IDs. Creates the manifest for all the shipments
consignor	→	consignor