Shipping with Australia Post in the GoRoute dashboard

GoRoute Shipping buys Australia Post labels on your own MyPost Business account. You connect that account once. Then you create shipments, buy their labels, print them, book a pickup and follow the parcels, from the Shipping page of the GoRoute dashboard or through the API.

This page covers the first two steps in full: connecting the account and creating a shipment. The later steps are listed at the end, each with its API call.

Postage is charged by Australia Post to your own MyPost Business account, with the card stored there or your charge account. GoRoute's own shipping plans (Free, 10 labels a month, or Unlimited) are on Shipping plans.

Selling on Wix? The Wix app does all of this inside Wix: see Wix app — GoRoute: AusPost Shipping.

Who can use it

Shipping is for organisations in Australia, and is never switched on by hand: who has it, and the 404 SHIPPING_NOT_AVAILABLE everyone else gets, are set out in Who has shipping.

Connect your MyPost Business account

In the dashboard, open Shipping. On your first visit the page offers Connect MyPost Business. It opens Settings, with two parts:

Sender address. The name and address printed on every label. The dashboard keeps it in your browser and fills it into each new shipment.
Carrier account. Where you connect MyPost Business, in one of the two ways below.

Once an account is connected, the setup screen gives way to the shipments list. Settings stays at the top of the page, with Connect another account and Disconnect.

When this GoRoute service has Australia Post sign-in set up, Carrier account shows a second button, Connect with your carrier sign-in. You sign in to MyPost Business, approve GoRoute, and come back to the Shipping page with the account connected. There is no token to copy.

The dashboard shows that button when GET /api/v1/shipping/carriers answers "oauth_available": true for the carrier. Through the API:

curl "https://app.goroute.ai/peppol-api/api/v1/shipping/oauth/auspost/start" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "authorize_url": "https://…",
  "redirect_uri": "https://…",
  "expires_in": 900
}

Send the person's browser to authorize_url. The link lasts 15 minutes (expires_in, in seconds). Australia Post then returns the browser to GoRoute, which connects the account and sends the person to the dashboard's Shipping page with one of these outcomes in the address:

Ends with	Meaning
`#shipping?connect=ok&account=<id>`	Connected. `<id>` is the new carrier account's `id`
`#shipping?connect=denied`	The person did not approve the connection at Australia Post
`#shipping?connect=failed&code=<code>`	The connection could not be completed. `<code>` says why, for example `CARRIER_OAUTH_STATE_EXPIRED` when the 15 minutes ran out

GET …/oauth/auspost/start also takes display_name, the name GoRoute shows for the account.

Paste a token

In MyPost Business: Business details → eCommerce Partners → Connect GoRoute, add a payment card, then Copy token. In the dashboard, paste the token under Carrier account and press Connect. GoRoute never shows the token again.

Through the API:

curl -X POST "https://app.goroute.ai/peppol-api/api/v1/shipping/carrier-accounts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"carrier": "auspost", "token": "PASTE_THE_TOKEN", "display_name": "Our MyPost Business"}'

Field	Required	Meaning
`carrier`	Yes	`auspost`
`token`	Yes	The MyPost Business token, 8 to 500 characters
`display_name`	No	The name GoRoute shows for the account, up to 120 characters

GoRoute first asks Australia Post which MyPost Business account the token belongs to, then stores the token encrypted. The answer is 201 with the account:

Field	Meaning
`id`	The carrier account's id. Every shipment names it as `carrier_account_id`
`external_account_ref`	Your MyPost Business account number
`status`	`active`; `expired` or `blocked` when Australia Post reports the account so
`charge_accounts`	The charge accounts linked to the account, for paying by charge account
`display_name`, `carrier`, `environment`, `connected_at`, `last_verified_at`, `last_error`	As named

Connecting a new account for Australia Post disconnects any earlier one for it.

Check, list and remove an account

Call	What it does
`GET /api/v1/shipping/carrier-accounts`	The organisation's connected accounts
`POST /api/v1/shipping/carrier-accounts/{account_id}/verify`	Asks Australia Post about the account again and updates `status` and the account number. If Australia Post refuses the token, the account becomes `expired`
`DELETE /api/v1/shipping/carrier-accounts/{account_id}`	Disconnects the account. Answers `204`. Labels already bought stay in MyPost Business

GoRoute also asks Australia Post about the account again before using it, once a day at most.

When connecting is refused

`code`	Status	When
`CARRIER_NOT_AVAILABLE`	`422`	The carrier named is not offered for your organisation's country
`CARRIER_AUTH_FAILED`	`409`	Australia Post refused the token. Copy a new one from MyPost Business
`CARRIER_NO_ACCOUNT`	`422`	Australia Post returned no MyPost Business account for the token. Connect GoRoute under eCommerce Partners again and copy a new token
`CARRIER_TOKEN_REQUIRED`	`502`	The token is only spaces
`CARRIER_OAUTH_NOT_AVAILABLE`	`502`	`…/oauth/auspost/start` was called where this service has no Australia Post sign-in set up. Paste a token instead
`OAUTH_RETURN_NOT_ALLOWED`	`422`	`…/oauth/auspost/start` was given a `return_to` that is not one of GoRoute's own app addresses. Only GoRoute's store apps use `return_to`

After the sign-in, a failure arrives in the dashboard's address as connect=failed&code=<code> instead: CARRIER_OAUTH_STATE_INVALID (the link was altered), CARRIER_OAUTH_STATE_EXPIRED (the 15 minutes ran out), CARRIER_OAUTH_CODE_MISSING or CARRIER_OAUTH_NO_TOKEN (Australia Post sent nothing GoRoute could use), or one of the codes above. In each case, start the connection again.

Who may connect an account

Connecting, checking and removing an account needs a key with the admin scope, or a signed-in person with the Owner, Admin or Developer role. Listing accounts needs a key with the read, write or admin scope, or a person who may read invoices.

Create a shipment

A shipment is one parcel, from your sender address to one receiver, on one Australia Post product. Creating it registers it with Australia Post and returns its price. It buys nothing. The label is bought when you order the shipment (see Order, pay and print labels).

In the dashboard, press + New shipment. The panel has three steps: Receiver, Parcel and Review, where Australia Post's prices are shown. Create shipment finishes it.

Choose a product

GET /api/v1/shipping/carriers/{carrier}/products, with carrier auspost, lists the products you can choose. Each is one of three kinds:

Kind	Products	What the parcel needs
Your own packaging, within Australia	`B20`, `B30` (up to 5 kg); `B21`, `B31` (over 5 kg, up to 22 kg). `B2x` is Express Post, `B3x` Parcel Post	Weight, length, width and height
Australia Post flat-rate box or satchel	The `BE9P…` (Express Post) and `BE1P…` (Parcel Post) products. Each carries its package size	Neither weight nor size
International	`I65` International Standard, `I67` International Express, up to 20 kg	Weight, and a customs declaration (see International parcels)

Ask for prices first (optional)

POST /api/v1/shipping/quotes asks Australia Post what a parcel would cost on each product it can carry it on. It buys nothing.

Field	Required	Meaning
`carrier_account_id`	Yes	The connected account
`from_postcode`	Yes	The sender's postcode
`to_postcode`	For Australia	The receiver's postcode. It may be left out for a receiver abroad
`to_country`	No	Two letters. Default `AU`
`parcels`	Yes	1 to 20 parcels, each as in the shipment's `parcel` below

The answer lists quotes, each with product_id, product_name, price_inc_tax, price_ex_tax, currency and delivery_time, as Australia Post gives them.

The call

POST /api/v1/shipping/shipments:

curl -X POST "https://app.goroute.ai/peppol-api/api/v1/shipping/shipments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier_account_id": "CARRIER_ACCOUNT_ID",
    "reference": "ORDER-1001",
    "order_reference": "PO-5521",
    "sender": {
      "name": "Dispatch",
      "business_name": "Example Pty Ltd",
      "lines": ["1 Example Street"],
      "suburb": "MELBOURNE",
      "state": "VIC",
      "postcode": "3000",
      "phone": "03 9000 0000"
    },
    "receiver": {
      "name": "Sam Receiver",
      "lines": ["2 Sample Road"],
      "suburb": "SYDNEY",
      "state": "NSW",
      "postcode": "2000",
      "country": "AU",
      "email": "receiver@example.com"
    },
    "parcel": {
      "product_id": "B30",
      "weight_kg": 1.2,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 10,
      "description": "Books"
    }
  }'

Replace the addresses and the email with real ones: Australia Post emails tracking updates to the receiver's email address.

The answer is 201 with the shipment. Its status is created: registered with Australia Post, not yet paid. It carries id, carrier_ref (Australia Post's shipment id), tracking_ids, price_inc_tax, price_ex_tax, currency, the addresses and items. warnings lists anything Australia Post noted without refusing.

The fields

The shipment:

Field	Required	Meaning
`carrier_account_id`	Yes	The connected account
`reference`	Yes	Your reference, 1 to 50 characters. It must be new within your organisation
`order_reference`	No	Your order or purchase-order number, up to 50 characters. Sent to Australia Post as the sender's reference
`sender`	Yes	An address, as below. The sender is always in Australia
`receiver`	Yes	An address, as below
`parcel`	Yes	The parcel, as below
`delivery_instructions`	No	Up to 128 characters
`transaction_id`	No	A GoRoute transaction (for example the invoice) to link the shipment to
`channel`, `channel_ref`	No	Where the shipment came from. Default `api`
`email_tracking_to_receiver`	No	Deprecated and ignored. Australia Post emails tracking to the receiver's email address by default

An address (sender and receiver):

Field	Rule
`name`	Required, up to 40 characters
`business_name`	Optional, up to 40 characters
`lines`	1 to 3 lines, each up to 40 characters
`suburb`	Required, up to 40 characters (the town or city abroad)
`state`	In Australia: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC` or `WA`. Abroad: optional, up to 10 characters
`postcode`	In Australia: 4 digits. Abroad: optional, 2 to 10 letters or digits
`country`	Two letters. Default `AU`
`phone`	Optional: digits, spaces and `+ ( ) -`, up to 20 characters
`email`	Optional, up to 50 characters

The parcel:

Field	Meaning
`product_id`	Required. A product from the list above
`weight_kg`	The weight in kilograms. Two decimal places at most on an international product
`length_cm`, `width_cm`, `height_cm`	The size in centimetres
`signature_on_delivery`	`true` asks for Signature on Delivery. `I67` always includes it
`extra_cover`	Extra cover in Australian dollars
`description`	What is in the parcel, up to 50 characters
`item_reference`	Your reference for the parcel. Default: the shipment's `reference`

Check an Australian address first (optional)

GET /api/v1/shipping/address/validate asks Australia Post, through your connected account, whether a suburb, state and postcode go together. It creates and buys nothing.

curl "https://app.goroute.ai/peppol-api/api/v1/shipping/address/validate?carrier_account_id=CARRIER_ACCOUNT_ID&suburb=SYDNEY&state=NSW&postcode=2000" \
  -H "X-API-Key: YOUR_API_KEY"

Query parameter	Required	Meaning
`carrier_account_id`	Yes	The connected account
`suburb`	Yes	The suburb, up to 40 characters
`state`	Yes	The state, up to 10 characters
`postcode`	Yes	The postcode, up to 10 characters

The answer has two fields:

Field	Meaning
`found`	`true` when Australia Post knows the combination
`suburbs`	What Australia Post returned for it, as it gives it

An account that cannot be used is refused with the account codes listed under What GoRoute checks before Australia Post is called, and a refusal by Australia Post arrives as described under Reading a refusal.

What GoRoute checks before Australia Post is called

GoRoute refuses a shipment that breaks one of these rules before it asks Australia Post to create the shipment, so a refused shipment costs nothing and creates nothing. Each refusal names the rule in its code and, for most, the field at fault in details.field.

Rule	`code`
The `reference` is already used by another shipment of your organisation	`SHIPMENT_REFERENCE_TAKEN`
The receiver has no way to be told about the parcel. In Australia: an email address or an Australian mobile number (starting `04` or `+61 4`). In China: both a phone number and an email address. Elsewhere: an email address or a phone number	`CARRIER_RECEIVER_CONTACT_REQUIRED`
An address breaks a rule in the address table above: for example no name, no address line, no suburb, a state that is not one of the eight, a postcode that is not 4 digits, or an email address that is not one	`CARRIER_FIELD_INVALID`
`product_id` is not an Australia Post product	`CARRIER_UNKNOWN_PRODUCT`
Your own packaging without length, width and height	`CARRIER_DIMENSIONS_REQUIRED`
Your own packaging without a weight	`CARRIER_WEIGHT_REQUIRED`
Your own packaging with fewer than two sides of 5 cm or more	`CARRIER_TOO_SMALL`
The weight is over the product's limit	`CARRIER_OVER_WEIGHT`
`B20` or `B30` for a parcel whose cubic weight is over 5 kg. Over 1 kg, Australia Post charges the greater of the actual weight and the cubic weight (length × width × height in metres × 250 kg). Choose `B21` or `B31`	`CARRIER_OVER_CUBIC_WEIGHT`
`B21` or `B31` for a parcel whose charged weight (the greater of the two, as above) is 5 kg or less. Choose `B20` or `B30`	`CARRIER_UNDER_WEIGHT`
Your own packaging within Australia: over 0.25 m³, or a side over 105 cm. International: a girth over 140 cm (twice the two shorter sides added together)	`CARRIER_OVER_SIZE`
Extra cover over A$5,000	`CARRIER_COVER_TOO_HIGH`
Within Australia: extra cover of A$500 or more without `signature_on_delivery`	`CARRIER_SIGNATURE_REQUIRED`
International: extra cover over the declared value of the contents	`CARRIER_COVER_EXCEEDS_VALUE`

The connected account must also be usable. These refusals concern the account, not the parcel:

`code`	When
`CARRIER_ACCOUNT_NOT_FOUND`	`carrier_account_id` is not one of your organisation's accounts
`CARRIER_ACCOUNT_REVOKED`	The account was disconnected. Connect it again
`CARRIER_ACCOUNT_EXPIRED`	Australia Post reports the account or its token as expired. Connect it again with a new token
`CARRIER_ACCOUNT_BLOCKED`	Australia Post reports the account as credit-blocked. Australia Post's credit management team can help

International parcels

An international product (I65, I67) needs a customs declaration on the parcel:

Field	Rule
`classification_type`	Why the goods leave Australia: `SALE_OF_GOODS` (the default), `COMMERCIAL_SALE_OF_GOODS`, `DOCUMENT`, `RETURN` or `OTHER`. Gifts and commercial samples are not taken. With `OTHER`, `description` (1 to 40 characters) says what the goods are
`customs`	1 to 20 lines. Each has `description` (up to 40 characters), `quantity`, `value` (each item, in Australian dollars, A$1 to A$9,999.99), `country_of_origin` (two letters) and `tariff_code` (the HS code: 6 to 12 digits, or exactly 10 for the United States). `sku` (up to 22 characters) is required for a country of the European Union. `weight_kg` is given on every line or on none
`export_declaration_number`	Required when the contents are worth more than A$2,000 in total: 9 to 12 letters or digits
`landed_costs_payer`	Who pays duties and taxes: `RECEIVER_PAYS`, `SENDER_PAYS_TAX_ID` (then `import_reference_number` is required, for example an IOSS number) or `SENDER_PAYS_ZONOS` (then it must be left out)
`non_delivery_action`	`RETURN` (the default) or `ABANDONED`

sender_customs_reference, invoice_number, comments, certificate_number and licence_number are optional label fields.

A declaration that breaks these rules is refused with CARRIER_CUSTOMS_REQUIRED (no lines), CARRIER_CUSTOMS_DETAIL_REQUIRED (a line is incomplete or out of range), CARRIER_CUSTOMS_CLASSIFICATION (an unknown reason for export) or CARRIER_FIELD_INVALID.

To find a tariff code, GET /api/v1/shipping/hs-codes?q= searches the Australian export classification, or the US tariff schedule with country=US.

Reading a refusal

A refusal by GoRoute's shipping rules or by Australia Post is a JSON object with code and message. Refusals from the rules above also carry action (what to do), details and retryable. Australia Post's own refusals arrive the same way, with Australia Post's message.

Decide on code and retryable rather than on the HTTP status. Most content refusals answer 422, a refused token 409, and Australia Post being unreachable 502 with retryable true. Some refusals made by GoRoute itself, such as SHIPMENT_REFERENCE_TAKEN and the account refusals, also answer 502, with retryable false.

A body that does not fit the field limits (a name over 40 characters in the request, for example) is refused 422 before any rule runs. That refusal has no code. It carries a detail list instead, and each entry names the field at fault in loc and says what is wrong in msg.

Who may create a shipment

Creating a shipment needs a key with the send or admin scope, or a signed-in person who may send invoices. Asking for prices and checking an address need a key with the read, write or admin scope, or a person who may read invoices.

Change the parcel before ordering

PUT /api/v1/shipping/shipments/{shipment_id}/parcel replaces the parcel of a shipment at Australia Post: a wrong weight, size or product, for example, without cancelling the shipment. The body is the same parcel object as parcel when the shipment was created (see The fields). The addresses and the reference stay as they are.

Only a shipment that has not been ordered (status created) can be changed. Any other is refused with SHIPMENT_NOT_EDITABLE, which answers 502 with retryable false. The parcel rules of What GoRoute checks before Australia Post is called run again on the new parcel, and so do the customs rules of International parcels, with the same refusals.

The answer is the shipment, with its price and tracking IDs as Australia Post gives them for the new parcel. A shipment.updated webhook is sent.

Changing a parcel needs a key with the send or admin scope, or a signed-in person who may send invoices.

Re-read a shipment after a timeout

POST /api/v1/shipping/shipments/{shipment_id}/refresh asks Australia Post for its own view of the shipment. Use it when a call about the shipment timed out and you are not sure what happened. The answer has shipment, carrier_status (Australia Post's status text) and tracking_ids.

It records what Australia Post says and the tracking IDs it gives. It never marks the shipment as ordered or paid by itself.

It is refused with SHIPMENT_NO_CARRIER_REF when the shipment has no Australia Post shipment id to look up, and with CARRIER_NOT_FOUND when Australia Post no longer has the shipment. Decide on code, as described under Reading a refusal.

Re-reading a shipment needs a key with the read, write or admin scope, or a person who may read invoices.

Order, pay and print labels

Creating a shipment buys nothing. To get a label you order the shipments, which is when Australia Post takes payment, and then print the labels of that order.

Order the shipments

POST /api/v1/shipping/orders puts one or more created shipments into one Australia Post order and pays for them.

Field	Required	Meaning
`shipment_ids`	Yes	1 to 100 shipment ids. Every one must have `status` `created` and use the same carrier account
`reference`	No	Your reference for the order, up to 50 characters
`payment_method`	No	`STORED_PAYMENT` (the default): the card stored in MyPost Business. `CHARGE_TO_ACCOUNT`: a charge account linked to the MyPost Business account
`charge_account_ref`	With `CHARGE_TO_ACCOUNT`	The charge account's number

To find the charge accounts, call GET /api/v1/shipping/carrier-accounts/{account_id}/charge-accounts. Each entry's account_number is a value for charge_account_ref.

The answer is 201 with the order: id, status, carrier_ref (Australia Post's order id), payment_method, charge_account_ref, paid_at, shipment_count, total_inc_tax, total_ex_tax and currency. Its status is:

paid for a stored-card order: the card was charged when the order was created;
pending_payment for a charge-account order, until you pay it (below).

The shipments in the order move to status ordered, and their tracking_ids are final from then on.

GoRoute refuses an order before Australia Post is called when:

When	Status and `code`
A shipment id is not one of your organisation's shipments	`404`
The shipments use more than one carrier account	`422` `ORDER_MIXED_ACCOUNTS`
On the Free plan, the order would take you past this month's labels	`402` `SHIPPING_LABEL_LIMIT`: see At the limit
A shipment's `status` is not `created` (it is already ordered or cancelled, for example)	`ORDER_SHIPMENTS_NOT_READY`, with the shipments in `details.shipment_ids`
`payment_method` is neither of the two values	`ORDER_PAYMENT_METHOD`
`CHARGE_TO_ACCOUNT` without `charge_account_ref`	`ORDER_CHARGE_ACCOUNT_REQUIRED`
The charge account is not linked to the carrier account	`ORDER_CHARGE_ACCOUNT_UNKNOWN`
The charge account is credit-blocked, or has no credit available	`ORDER_CHARGE_ACCOUNT_BLOCKED`, `ORDER_CHARGE_ACCOUNT_NO_CREDIT`

The refusals in the table without a status answer 502 with retryable false, as described under Reading a refusal. The account refusals of What GoRoute checks before Australia Post is called apply to every call in this section.

Australia Post's own refusals of an order include:

`code`	When
`CARRIER_PAYMENT_FAILED` (`402`)	The stored card is missing, expired or declined. `action` says what to change in MyPost Business
`CARRIER_ACCOUNT_ON_HOLD` (`409`)	The MyPost Business account is on hold until underpaid postage is paid
`CARRIER_CHARGE_ACCOUNT_REFUSED` (`409`)	Australia Post refused payment by that charge account

Pay an order placed on a charge account

POST /api/v1/shipping/orders/{order_id}/pay takes payment from the order's charge account. The answer is the order, now paid. Its labels cannot be printed before.

It is refused with ORDER_ALREADY_PAID when the order is already paid, and with ORDER_NOT_CHARGE_ACCOUNT for a stored-card order, which was paid when it was created. Both answer 502 with retryable false.

POST /api/v1/shipping/orders/{order_id}/refresh re-reads the order from Australia Post: its totals, and whether it has been paid. Use it when a call timed out and you are not sure what happened. GET /api/v1/shipping/orders/{order_id} returns the order with its shipments.

Print the labels

POST /api/v1/shipping/orders/{order_id}/labels asks Australia Post for the labels of an order's shipments.

Field	Required	Meaning
`layout`	No	`A4-1pp` (the default), `A4-4pp` or `THERMAL-LABEL-A6-1PP`
`shipment_ids`	No	Only these shipments of the order. Default: all of them
`wait_for_url`	No	Default `true`: GoRoute waits for Australia Post's PDF and keeps it. `false` returns at once with a pending label

The answer is 201 with the label: id, status, layout, shipment_ids and download_path. status is:

ready: the PDF is kept. The shipments move to status labelled;
pending: Australia Post has not produced the PDF yet. Call POST /api/v1/shipping/labels/{label_id}/refresh until the label is ready.

The labels of one order can be printed again: each call makes a new label.

It is refused with CARRIER_ORDER_NOT_PAID (422) while a charge-account order is unpaid, and with LABEL_NOTHING_TO_PRINT (502, retryable false) when none of the shipments is ordered. An unknown layout is refused 422, and so is a request for more than 100 labels (CARRIER_LABEL_BATCH_TOO_LARGE).

GET /api/v1/shipping/labels/{label_id}/download returns the PDF (application/pdf). It answers 404 while the label is still pending.

List your labels

GET /api/v1/shipping/labels lists your organisation's labels, newest first. Page with limit (1 to 200, default 50) and offset. The answer has labels, limit and offset. Each label has:

Field	Meaning
`id`	The label's id
`shipment_order_id`	The order it was printed for
`shipment_ids`	The shipments on the label
`layout`	`A4-1pp`, `A4-4pp` or `THERMAL-LABEL-A6-1PP`
`status`	`ready`, `pending` or `failed`
`carrier_ref`	Australia Post's reference for the label request
`byte_size`	The size of the kept PDF, or `null` while there is none
`label_url_known`	`true` once Australia Post has given the PDF's address
`download_path`	The path to download the PDF from
`created_at`	When the label was asked for

An example

Order two shipments with the stored card, print their labels and save the PDF:

curl -X POST "https://app.goroute.ai/peppol-api/api/v1/shipping/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_ids": ["SHIPMENT_ID_1", "SHIPMENT_ID_2"],
    "reference": "DISPATCH-0507",
    "payment_method": "STORED_PAYMENT"
  }'

curl -X POST "https://app.goroute.ai/peppol-api/api/v1/shipping/orders/ORDER_ID/labels" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"layout": "A4-1pp"}'

curl "https://app.goroute.ai/peppol-api/api/v1/shipping/labels/LABEL_ID/download" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o labels.pdf

ORDER_ID is the id the first call returns, and LABEL_ID the id the second returns.

Who may order and print

Ordering, paying and printing need a key with the send or admin scope, or a signed-in person who may send invoices. Refreshing an order or a label, and listing and downloading labels, need a key with the read, write or admin scope, or a person who may read invoices.

Book a pickup and track parcels

Instead of taking the parcels to a Post Office, you can have an Australia Post driver collect them. A pickup is booked by the number of parcels you expect, then paid for in an order of its own. Once a parcel has a label, GoRoute follows it and tells you when it is delivered.

Check that a pickup is available

Australia Post offers two pickup products, each collected between 9 am and 4 pm:

PU1: the same day. It must be booked before 1 pm, local time where the parcels are, on a business day.
PU3: the next business day.

POST /api/v1/shipping/pickups/products asks which pickups can be booked at an address. Send the carrier_account_id and the address, in the same shape as a shipment's sender; only its suburb, state and postcode are used. The answer lists products (each with product_id, description, the collection times and the shipping products it can collect) and says whether the address is serviceable.

POST /api/v1/shipping/pickups/prices prices pickup products. Send the carrier_account_id and up to ten product_ids; leave the list out to price both. Each entry of prices has product_id, product_name, price_inc_tax, price_ex_tax and currency.

Book a pickup

POST /api/v1/shipping/pickups books one or more pickups on one carrier account: the carrier_account_id and a pickups list of 1 to 20 entries.

Field	Required	Meaning
`reference`	Yes	Your reference for the pickup, up to 50 characters
`product_id`	Yes	`PU1` or `PU3`
`estimated_quantity`	Yes	How many parcels the driver collects: 1 to 100. Book another pickup for more
`address`	Yes	Where the parcels are collected. It must have a contact `phone`: an Australian number of ten digits, such as `0412 345 678`
`pickup_date`	No	Leave it out. GoRoute fills in the only date the product allows: today for `PU1`, the next business day for `PU3`
`start_time`, `end_time`	No	The collection window, `HH:MM`. Default `09:00` to `16:00`
`unattended`	No	`true` if nobody will be there. Default `false`
`instructions`	With `unattended`	Where the driver finds the parcels, up to 128 characters
`shipment_ids`	No	Up to 100 of your shipments that this pickup is for. GoRoute keeps the list for you; Australia Post only takes the number

The answer is 201 with pickups. Each has id, status created, pickup_date, the costs Australia Post gives (cost_inc_tax, cost_tax, currency) and date_passed.

A booked pickup cannot be cancelled through the API. To cancel one, contact MyPost Business support. Pay for a booked pickup with the call below.

GoRoute refuses a booking before Australia Post is called when:

When	Status and `code`
A shipment in `shipment_ids` is not one of your organisation's	`422` `PICKUP_SHIPMENT_NOT_FOUND`, with those ids in `details.shipment_ids`
`product_id` is not `PU1` or `PU3`	`422` `CARRIER_PICKUP_PRODUCT_UNKNOWN`
`PU1` after 1 pm, or on a weekend	`422` `CARRIER_PICKUP_OUTSIDE_CUTOFF`: book `PU3` instead
`pickup_date` is not the date the product allows	`422` `CARRIER_PICKUP_DATE`, with that date in `details.expected`
`unattended` without `instructions`	`422` `CARRIER_PICKUP_INSTRUCTIONS_REQUIRED`
No usable contact phone on the `address`	`422` `CARRIER_FIELD_INVALID`, with `details.field` `sender.phone`

An estimated_quantity outside 1 to 100 is a field limit, so it is refused 422 before any of these rules runs, as described under Reading a refusal. That answer carries no code: it is a detail list, and the entry for the quantity names it in its loc.

Pay for a pickup

POST /api/v1/shipping/pickups/order pays for booked pickups in one Australia Post order.

Field	Required	Meaning
`pickup_ids`	Yes	1 to 50 pickup ids. Every one must have `status` `created` and use the same carrier account
`reference`	No	Your reference for the order, up to 50 characters
`payment_method`	No	`STORED_PAYMENT` (the default) or `CHARGE_TO_ACCOUNT`, as for a label order
`charge_account_ref`	With `CHARGE_TO_ACCOUNT`	The charge account's number

The answer is 201 with the order, in the same shape as a label order with pickup_count, and its pickups. The pickups move to status ordered and carry Australia Post's pickup_number. An order placed on a charge account is paid with POST /api/v1/shipping/orders/{order_id}/pay, as a label order is.

GoRoute refuses the order before Australia Post is called when:

When	Status and `code`
A pickup id is not one of your organisation's pickups	`404`
The pickups use more than one carrier account	`422` `ORDER_MIXED_ACCOUNTS`
A pickup's date has passed where it is collected (its `date_passed` is `true`)	`422` `ORDER_PICKUP_DATE_PASSED`: Australia Post cannot take payment for it, so book a new pickup and pay for that one
A pickup is not `created` (it is already paid for, for example)	`ORDER_PICKUPS_NOT_READY`, with the pickups in `details.pickup_ids`

ORDER_PICKUPS_NOT_READY answers 502 with retryable false, as described under Reading a refusal. The payment-method and charge-account refusals of Order the shipments apply here too.

List and read pickups

GET /api/v1/shipping/pickups lists your organisation's pickups, newest first. Filter with status, such as created or ordered, and page with limit (1 to 200, default 50) and offset. GET /api/v1/shipping/pickups/{pickup_id} returns one pickup.

Track a parcel

GoRoute follows every domestic parcel that has a label by itself, asking Australia Post about it at most about once an hour, and stops once the parcel is delivered. The first scan moves the shipment to status in_transit, and a delivery scan to delivered, with delivered_at and a proof_of_delivery record on the shipment.

To ask now, call POST /api/v1/shipping/shipments/{shipment_id}/track. The answer has the shipment, new_events (how many new scans were recorded) and delivered (true when this call found the delivery).

It is refused, with 502 and retryable false, with:

SHIPMENT_TRACKING_NOT_AVAILABLE for an international parcel. Australia Post does not offer tracking for international parcels through MyPost Business: follow the parcel with its tracking number on auspost.com.au;
SHIPMENT_NOT_TRACKABLE for a shipment with no tracking number yet. The tracking number comes with the order.

An unknown shipment id answers 404.

Webhooks. New scans send shipment.tracking_updated, and a delivery sends shipment.delivered. Booking a pickup sends shipment.pickup_created, and paying for it shipment.pickup_ordered.

Read a shipment's whole record

GET /api/v1/shipping/shipments/{shipment_id}/record returns, in one answer, everything GoRoute knows about one shipment. A shipment that is not your organisation's answers 404.

Field	Meaning
`shipment`	The shipment, as the other shipment calls return it
`order`	The order it was bought in, or `null` before it is ordered: `id`, `status`, `reference`, `carrier_ref`, `payment_method`, `charge_account_ref`, `paid_at`, `total_inc_tax`, `total_ex_tax`, `currency` and `created_at`
`labels`	Every label printed for it, oldest first: `id`, `layout`, `status`, `byte_size`, `download_path` and `created_at`
`tracking`	Its tracking scans, newest first: `tracking_id`, `status`, `description`, `location`, `occurred_at` and `delivered`
`proof_of_delivery`	The proof of delivery, or `null` until it is delivered
`transaction`	The GoRoute transaction it is linked to (`id`, `status`, `message_id`), or `null`
`assessment`, `invoice`	Always `null` for now: reserved for a later release
`generated_at`	When this answer was put together

An example

Book a next-day pickup for two parcels:

curl -X POST "https://app.goroute.ai/peppol-api/api/v1/shipping/pickups" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier_account_id": "CARRIER_ACCOUNT_ID",
    "pickups": [{
      "reference": "PICKUP-0507",
      "product_id": "PU3",
      "estimated_quantity": 2,
      "shipment_ids": ["SHIPMENT_ID_1", "SHIPMENT_ID_2"],
      "address": {
        "name": "Jane Citizen",
        "business_name": "Wattle Outdoor Supplies",
        "lines": ["12 Example Street"],
        "suburb": "MELBOURNE",
        "state": "VIC",
        "postcode": "3000",
        "phone": "0412 345 678"
      }
    }]
  }'

Then pay for it with the stored card, using the pickup's id from the answer:

curl -X POST "https://app.goroute.ai/peppol-api/api/v1/shipping/pickups/order" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pickup_ids": ["PICKUP_ID"], "payment_method": "STORED_PAYMENT"}'

Who may book and track

Booking and paying for a pickup need a key with the send or admin scope, or a signed-in person who may send invoices. Checking and pricing pickups, listing and reading them, tracking a parcel and reading a shipment's record need a key with the read, write or admin scope, or a person who may read invoices.

List your receivers

GET /api/v1/shipping/receivers lists everyone your organisation has shipped to, read from the shipments GoRoute already holds. Nothing new is collected. One row is one receiver at one delivery address: the same person shipped to two addresses is two rows. Rows come newest first, by the last shipment.

curl "https://app.goroute.ai/peppol-api/api/v1/shipping/receivers?q=sydney" \
  -H "X-API-Key: YOUR_API_KEY"

q is optional, up to 100 characters. It keeps the receivers whose name, business name, email, phone, suburb, state, postcode or country contains it.

The answer:

Field	Meaning
`receivers`	The rows, as below
`total`	How many rows are listed
`complete`	How many of them have `contact_complete` `true`
`shipments_read`	How many shipments the list was built from: your newest 5,000 at most

Each row:

Field	Meaning
`key`	GoRoute's key for this receiver at this address
`shipments`	How many shipments went to them
`international`	How many of those were international
`spend`	What those shipments cost, cancelled ones left out
`currency`	The currency of `spend`
`first_shipped_at`, `last_shipped_at`	When the first and the latest shipment to them were created
`last_reference`, `last_shipment_id`	The `reference` and `id` of the latest shipment
`address`	The receiver as captured on the latest shipment: `name`, `business_name`, `lines`, `suburb`, `state`, `postcode`, `country`, `email` and `phone`
`has_email`, `has_phone`	Whether that address has an email address, and a phone number
`contact_complete`	Whether the receiver can be told about a parcel: an email address or, for a receiver in Australia, an Australian mobile number; for anyone else, any phone number

A shipment whose receiver has neither a name nor an email address is left out.

Listing receivers needs a key with the read, write or admin scope, or a person who may read invoices.

See your shipping at a glance

GET /api/v1/shipping/insights sums up your organisation's shipping: how many parcels, what the postage cost, where they went, which products you used and how many have been delivered. It is the summary on the Insights tab of the dashboard's Shipping page. Like the receivers list, it is read from the shipments GoRoute already holds.

curl "https://app.goroute.ai/peppol-api/api/v1/shipping/insights?days=28" \
  -H "X-API-Key: YOUR_API_KEY"

days is optional: the number of days to look back from now, from 7 to 365. It defaults to 90. A value outside that range is refused 422, as described under Reading a refusal.

The figures cover the shipments created in that window, your newest 5,000 at most. If you created more than 5,000 shipments in the window, the older ones are not counted, and the answer does not say so. Ask for fewer days to get a complete count for a shorter period.

An example answer, with invented figures:

{
  "days": 28,
  "since": "2026-10-12T05:00:00.412318+00:00",
  "currency": "AUD",
  "shipments": 40,
  "cancelled": 2,
  "spend": 612.4,
  "average_postage": 15.31,
  "domestic": 36,
  "international": 4,
  "delivered": 31,
  "average_days_to_deliver": 2.4,
  "contact_complete": 34,
  "contact_complete_share": 0.85,
  "by_week": [
    { "week": "2026-10-12", "shipments": 9, "spend": 138.15 },
    { "week": "2026-10-19", "shipments": 11, "spend": 171.6 },
    { "week": "2026-10-26", "shipments": 8, "spend": 119.85 },
    { "week": "2026-11-02", "shipments": 10, "spend": 152.1 },
    { "week": "2026-11-09", "shipments": 2, "spend": 30.7 }
  ],
  "by_status": { "delivered": 31, "in_transit": 5, "labelled": 3, "ordered": 1, "cancelled": 2 },
  "top_services": [
    { "product_id": "B30", "shipments": 22 },
    { "product_id": "B20", "shipments": 9 },
    { "product_id": "B31", "shipments": 5 },
    { "product_id": "I65", "shipments": 3 },
    { "product_id": "I67", "shipments": 1 }
  ],
  "top_destinations": [
    { "destination": "AU-NSW", "shipments": 15 },
    { "destination": "AU-VIC", "shipments": 12 },
    { "destination": "AU-QLD", "shipments": 6 },
    { "destination": "AU-WA", "shipments": 3 },
    { "destination": "NZ", "shipments": 3 },
    { "destination": "US", "shipments": 1 }
  ]
}

The fields:

Field	Meaning
`days`	The window asked for
`since`	Where the window starts: `days` days before the call
`currency`	The currency of the amounts: `AUD` unless your shipments carry another
`shipments`	Shipments created in the window, cancelled ones left out. Every figure below except `cancelled` and `by_status` counts only these
`cancelled`	Shipments created in the window and then cancelled
`spend`	The postage of those shipments, including tax. A shipment with no price yet counts as nothing
`average_postage`	`spend` divided by `shipments`, or `null` when there are none
`domestic`, `international`	How many went within Australia and how many abroad. A shipment counts as international when it was created as one or its receiver's country is not `AU`
`delivered`	How many have been delivered
`average_days_to_deliver`	The average time from creating a shipment to its delivery, in days to one decimal place, or `null` when none has been delivered
`contact_complete`	How many shipments have a receiver whose contact is complete, by the rule in List your receivers
`contact_complete_share`	`contact_complete` as a fraction of `shipments`, from 0 to 1, or `null` when there are none
`by_week`	Every week of the window, oldest first, empty weeks included. Each has `week` (the date of its Monday), `shipments` and `spend`
`by_status`	How many shipments are in each status, cancelled ones included
`top_services`	Up to eight Australia Post products, most used first: `product_id` (the product code, as in Choose a product) and `shipments`
`top_destinations`	Up to eight destinations, most used first: `destination` and `shipments`. A shipment abroad counts under its country code. A shipment within Australia counts under `AU-` and the receiver's state, or `AU-?` when no state was given

Times and week boundaries are in UTC.

Reading the summary needs a key with the read, write or admin scope, or a person who may read invoices. An organisation without shipping gets the same 404 SHIPPING_NOT_AVAILABLE as on every other shipping call (see Who can use it).

What comes next

Step	Call	Notes
Order and pay	`POST /api/v1/shipping/orders`	See Order the shipments
Pay an order placed on a charge account	`POST /api/v1/shipping/orders/{order_id}/pay`	See Pay an order placed on a charge account
Print labels	`POST /api/v1/shipping/orders/{order_id}/labels`, then `GET /api/v1/shipping/labels/{label_id}/download`	See Print the labels
List your labels	`GET /api/v1/shipping/labels`	See List your labels
Book a pickup	`POST /api/v1/shipping/pickups`, then `POST /api/v1/shipping/pickups/order`	See Book a pickup and Pay for a pickup
Track	`POST /api/v1/shipping/shipments/{shipment_id}/track`	See Track a parcel
Read a shipment's whole record	`GET /api/v1/shipping/shipments/{shipment_id}/record`	See Read a shipment's whole record
List your receivers	`GET /api/v1/shipping/receivers`	See List your receivers
See your shipping at a glance	`GET /api/v1/shipping/insights`	See See your shipping at a glance
Check an Australian address	`GET /api/v1/shipping/address/validate`	See Check an Australian address first
Change a parcel not yet ordered	`PUT /api/v1/shipping/shipments/{shipment_id}/parcel`	See Change the parcel before ordering
Re-read a shipment after a timeout	`POST /api/v1/shipping/shipments/{shipment_id}/refresh`	See Re-read a shipment after a timeout
Cancel a shipment not yet ordered	`DELETE /api/v1/shipping/shipments/{shipment_id}`

Every call above answers for the organisation the credential belongs to. All paths are relative to the production base URL https://app.goroute.ai/peppol-api; the test service serves the same paths under its own base URL (see Environments).

Help

Write to admin@goroute.ai with the shipment's reference and the request_id from any refusal.

Who can use it​

Connect your MyPost Business account​

Sign in with Australia Post​

Paste a token​

Check, list and remove an account​

When connecting is refused​

Who may connect an account​

Create a shipment​

Choose a product​

Ask for prices first (optional)​

The call​

The fields​

Check an Australian address first (optional)​

What GoRoute checks before Australia Post is called​

International parcels​

Reading a refusal​

Who may create a shipment​

Change the parcel before ordering​

Re-read a shipment after a timeout​

Order, pay and print labels​

Order the shipments​

Pay an order placed on a charge account​

Print the labels​

List your labels​

An example​

Who may order and print​

Book a pickup and track parcels​

Check that a pickup is available​

Book a pickup​

Pay for a pickup​

List and read pickups​

Track a parcel​

Read a shipment's whole record​

An example​

Who may book and track​

List your receivers​

See your shipping at a glance​

What comes next​

Help​

Who can use it

Connect your MyPost Business account

Sign in with Australia Post

Paste a token

Check, list and remove an account

When connecting is refused

Who may connect an account

Create a shipment

Choose a product

Ask for prices first (optional)

The call

The fields

Check an Australian address first (optional)

What GoRoute checks before Australia Post is called

International parcels

Reading a refusal

Who may create a shipment

Change the parcel before ordering

Re-read a shipment after a timeout

Order, pay and print labels

Order the shipments

Pay an order placed on a charge account

Print the labels

List your labels

An example

Who may order and print

Book a pickup and track parcels

Check that a pickup is available

Book a pickup

Pay for a pickup

List and read pickups

Track a parcel

Read a shipment's whole record

An example

Who may book and track

List your receivers

See your shipping at a glance

What comes next

Help