{{ activeApiMethod.description }}
This interface creates a shipment with items and returns a summary of the pricing for the items. A shipment is a set of items associated to a charge account’s location to be delivered to the one physical address.
This page describes how to create an international shipment. To create a domestic shipment, see the Create Domestic Shipment page.
HTTP Response Code: 201
HTTP Response Code: 400
| Element Name | Description | Optional / Mandatory | Type | Length |
|---|---|---|---|---|
| shipments | Shipment information is to be supplied for each delivery of items to a physical address. | Mandatory | Array | |
| shipment_reference | A unique reference for the shipment, generated by the merchant. | Optional | String | 50 |
| sender_references | A merchant specified array of references for the shipment. Effectively deprecates customer_reference_1 and customer_reference_2. The array length supported varies as noted in the Sender references documentation. | Optional | Array | |
| customer_reference_1 | A merchant specified reference for the shipment. This value is not required to be unique. | Optional | String | 50 |
| customer_reference_2 | A merchant specified reference for the shipment. This value is not required to be unique. | Optional | String | 50 |
| email_tracking_enabled | Whether the recipient of the shipment will receive tracking notification email. The email address of the receiver must be provided if the email_tracking_enabled field is set to true. | Optional - for some products this defaults to true | Boolean - true or false | N/A |
| from | The address where the items will be sent from. | Mandatory | ||
| name | The name of the sender. | Mandatory | String | 40 |
| business_name | The name of the sending business. | Optional | String | 40 |
| type | The type of address. If this field is supplied, its value must be "MERCHANT_LOCATION". | Optional | String (See Desc.) | |
| lines | The address lines of the address. Minimum of one address line, up to a maximum of three. The second address line can accommodate up to 60 characters. | Mandatory | Array | 40 |
| suburb | The suburb for the address. | Mandatory | String | 40 |
| state | The state code for the address. Valid values are: ACT, NSW, NT, QLD, SA, TAS, VIC, WA. | Mandatory | String | 3 |
| postcode | The postcode for the address. | Mandatory | String | 4 |
| phone | The sender’s phone number. | Optional | String | 20 |
| The sender’s email address. | Optional | String | 50 | |
| to | The address where the items will be delivered. | Mandatory | ||
| name | The name of the receiver. | Mandatory | String | 35 |
| apcn | The Australia Post customer number. | Optional | String | 10 |
| business_name | The name of the business for the address. | Optional | String | 40 |
| type | The type of address. Valid values are:
| Optional | String (See Desc.) | |
| lines | The address lines of the address. Minimum of one address line, up to a maximum of three. The second address line can accommodate up to 60 characters. | Mandatory | Array | 40 |
| suburb | The suburb for the address. | Mandatory | String | 35 |
| state | The state code for the address. | Optional | String | 10 |
| postcode | The postcode for the address. | Mandatory | String | 4 |
| country | The country code for the address. The country code must conform to ISO 3166-1 alpha-2 standard. | Mandatory | String | 2 |
| phone | The receiver’s phone number. | Optional | String | 20 |
| The receiver’s email address. | Optional | String | 50 | |
| delivery_instructions | Instructions to aid in prompt delivery of the item. | Optional | String | 128 |
| features | Additional features for the shipment. | Optional | ||
| name | Name of additional feature. Eg: COMMERCIAL_CLEARANCE | Mandatory | String | N/A |
| attributes | Additional information about the feature. Please note that attributes depend on the feature. Please refer to Shipment Features. | Mandatory | String | N/A |
| items | An item element is to be supplied for each parcel. Important Note: The maximum number of items for Parcel Post and Express Post domestic despatch movements is 20 items | Mandatory | Array | |
| item_reference | A unique reference for the item, generated by the merchant. | Optional | String | 50 |
| product_id | The Australia Post code representing the postage product for the item. | Mandatory | String | 5 |
| item_description | A description of the item, generated by the merchant. It is mandatory for APGL products and is used to capture the overall description of the article. | Optional (See Desc.) | String | |
| length | The length of the parcel in centimetres. If volumetric pricing applies then this is mandatory. | Optional (See Desc.) | Decimal | 4.1 |
| width | The width of the parcel in centimetres. If volumetric pricing applies then this is mandatory. Please refer to the length field for more information. | Optional (See Desc.) | Decimal | 4.1 |
| height | The height of the parcel in centimetres. If volumetric pricing applies then this is mandatory. Please refer to the length field for more information. | Optional (See Desc.) | Decimal | 4.1 |
| weight | The parcel’s weight in kilograms. This must not be specified for flat-rate return shipments (movement_type = RETURN). However, it is mandatory for normal (outbound) shipments (movement_type = DESPATCH) and zonal returns (movement_type = RETURN). Your contract with Australia Post (not your API call) determines whether a return shipment has zonal pricing or flat-rate pricing. Note that most returns contracts are flat-rate. | See Desc. | Decimal | N.3 |
| contains_dangerous_goods | Whether the item contains dangerous goods, generated by the merchant. | Optional. Defaults to false. | Boolean - true or false | |
| transportable_by_air | If the goods being sent are dangerous but are permitted to be transported by air, set this value to 'true'. | (Optional) | Boolean - true or false | |
| dangerous_goods_declaration | If the goods being sent are dangerous and the transportable_by_air value is 'true', then the DG Declaration becomes mandatory. The DG declaration value can be found here. | See Desc. | String | |
| allow_partial_delivery | Whether items can be delivered to their final destination as they become available or whether all items in the resulting consignment must be delivered together. | Optional. Defaults to true. | Boolean - true or false | N/A |
| features | Additional features for the item. | Optional | ||
| name | Name of the feature. Eg: TRANSIT_COVER. | Mandatory | String | |
| attributes | Additional information about the feature. Please note that attributes depend on the feature. | Depends on feature. | String | |
| cover_amount | Cover amount. | Decimal | 4.2 | |
| tracking_details | The merchant can optionally define the specific consignment, article, and barcode identifiers for the item. If this information is not supplied, Australia Post will generate the identifiers. Important note: if you are generating your own identifiers you must adhere to the specifications provided by Australia Post. Please contact Lodgement and APIs support for details. | Optional | ||
| consignment_id | The consignment ID, generated by the merchant, to be assigned to the item. | Mandatory | String | 30 |
| article_id | The article ID, generated by the merchant, to be assigned to the item. | Mandatory | String | 30 |
| barcode_id | The barcode ID, generated by the merchant, to be assigned to the item. | Mandatory | String | |
| commercial_value | Whether the item has commercial value (i.e. the goods are for resale). This is generated by the merchant and will be shown on the customers form and label. | Mandatory | Boolean - true or false | |
| export_declaration_number | Export declaration number (EDN), generated by the merchant. This field is mandatory for item contents worth more than AUD$2000. | Optional (See Desc.) | String | 9 to 12 |
| description_of_other | Description of the goods. This is mandatory if classification_type is "OTHER". | See Desc. | String | 40 |
| non_delivery_action | Your desired action if the delivery cannot be completed. You can specify "RETURN" or "ABANDONED". The default if not specified is to return the item by the most economical route or by air. | Optional | String | |
| certificate_number | If you are supplying certificates with your customs forms, you can include the certificate numbers in this field. | Optional | String | 35 |
| licence_number | If you are supplying licence information with your customs forms, you can include the licence numbers in this field. | Optional | String | 35 |
| invoice_number | Use this field to include an invoice number on the label. | Optional | String | 35 |
| comments | Use this field to include any additional comments on the label. | Optional | String | 120 |
| item_contents | An item_contents element describes part of the contents of the item. You can specify up to 20 elements in this array. | Mandatory | Array | 20 |
| description | Description of the contents. This description is validated against a defined list of keywords, to determine whether the item can be carried by Australia Post and/or the item is prohibited in the destination country. | Mandatory | String | 40 |
| quantity | The quantity of this described content. | Mandatory | Integer | |
| weight | The weight in kilograms of this described content. If you provide a weight for one item_contents element, you must provide weights for all item_contents elements. | See Desc. | Decimal | N.3 |
| value | The value in Australian Dollars of this described content. | Mandatory | Decimal | 4.2 |
| tariff_code | The Harmonised Tariff number that indicates the type of this described content. It is only mandatory if commercial_value is "true", otherwise it is optional. However, it is a recommended field to expedite the customs process in the receiving country. | See Desc. | String | 6 to 12 |
| country_of_origin | The country in which this described content was manufactured. It is only mandatory if commercial_value is "true", otherwise it is optional. | See Desc. | String | 2 |
| Element Name | Description | Type | Length |
|---|---|---|---|
| shipments | Shipment information for each shipment and items created. | Array | |
| shipment_id | The identifier for the shipment generated by Australia Post. | String | 50 |
| shipment_reference | The reference for the shipment, generated by the merchant and passed in the request. | String | 50 |
| shipment_creation_date | The date and time that the shipment was created. | Date and time | N/A |
| email_tracking_enabled | Whether the recipient of the shipment will receive tracking notification email. | Boolean - true or false | N/A |
| items | An item element is to be supplied for each parcel. | Array | |
| item_id | The identifier for the item generated by Australia Post. | String | 50 |
| item_reference | A unique reference for the item, generated by the merchant. | String | 50 |
| product_id | The Australia Post code representing the postage product for the item. | String | 5 |
| tracking_details | The unique identifiers for the item. If these values have not been provided when creating the order or labels, then they will have been generated by Australia Post. | ||
| consignment_id | The consignment ID assigned to the item. | String | 100 |
| article_id | The article ID assigned to the item. | String | 100 |
| barcode_id | The barcode ID assigned to the item. | String | |
| item_summary | Summary information for each item in the shipment. | ||
| total_cost | The total price of the shipment, including goods and services tax (G.S.T). This field is not used for StarTrack shipments, as they are costed at the shipment level only. | Decimal | N.2 |
| total_cost_ex_gst | The total price of the shipment, excluding goods and services tax (G.S.T). This field is not used for StarTrack shipments, as they are costed at the shipment level only. | Decimal | N.2 |
| total_gst | The goods and services tax amount included in the total cost. This field is not used for StarTrack shipments, as they are costed at the shipment level only. | Decimal | N.2 |
| status | The status for the item. | String | N/A |
| item_description | A description of the item, generated by the merchant. | String | |
| height | The height of the parcel in centimetres. | Decimal | 4.1 |
| length | The length of the parcel in centimetres. | Decimal | 4.1 |
| width | The width of the parcel in centimetres. | Decimal | 4.1 |
| weight | The parcel’s weight in kilograms. | Decimal | N.3 |
| allow_partial_delivery | Whether items can be delivered to their final destination as they become available or whether all items in the resulting consignment must be delivered together. | Boolean - true or false | N/A |
| features | Additional features for the item. | List | |
| name | Name of additional feature. Eg: TRANSIT_COVER. | String | |
| type | Type of additional feature. Eg: TRANSIT_COVER. | String | |
| attributes | Additional information about the feature. Please note that the attributes depend on the feature type. | String | |
| rate | Percentage rate for calculating the TRANSIT_COVER cost. | Decimal | 2.1 |
| cover_amount | The amount of TRANSIT_COVER requested. | Decimal | 4.2 |
| included_cover | The amount of TRANSIT_COVER included in the delivery product. | Decimal | 4.2 |
| maximum_cover | The maximum amount of TRANSIT_COVER that can be requested. | Decimal | 4.2 |
| movement_type | Value is "DESPATCH" to indicate an outbound or normal shipment, "RETURN" to indicate a returns shipment, "TRANSFER" to indicate a transfer. "TRANSFER" is only available for StarTrack products. | String | 8 |
| shipment_summary | Summary pricing information for the shipment. | ||
| total_cost | The total price of the shipment, including goods and services tax (G.S.T). | Decimal | N.2 |
| total_cost_ex_gst | The total price of the shipment, excluding goods and services tax (G.S.T). | Decimal | N.2 |
| shipping_cost | The shipping cost for this shipment. | Decimal | N.2 |
| total_gst | The goods and services tax amount included in the total cost. | Decimal | N.2 |
| status | The status of the item. | String | |
| number_of_items | The number of items within the shipment. | Integer | |
| tracking_summary | The number of items in the shipment for each delivery status. The delivery status will be listed with the number of items in the shipment where the delivery status has been applied. | Array | |
| freight_charge | The freight charge for this shipment. | Decimal | N.2 |
| discount | The discount for this shipment. | Decimal | N.2 |
| transit_cover | The transit cover charge for this shipment. This field may be used to specify Transit Cover, Extra Cover or Transit Warranty for Contract, Non-Contract or StarTrack products respectively. | Decimal | N.2 |
| security_surcharge | The security surcharge for this shipment. | Decimal | N.2 |
| fuel_surcharge | The fuel surcharge for this shipment. | Decimal | N.2 |
| Element Name | Description | Type | Length |
|---|---|---|---|
| errors | The error codes and descriptions related to the action attempted. | Array | |
| code | The code associated with the error. | String | |
| name | The name category for the error. | String | |
| message | The human readable error message. | String | |
| context | A map of values that attempts to highlight important information that may have caused the error. This may or may not be populated depending on the type of error. | Map |
| Code | Name | Example Message |
|---|---|---|
| 42012 | PRODUCT_NOT_SUPPORTED_BY_CONTRACT_ERROR | The product CODE you have entered is not available on your contract ACCOUNT for the destination postcode POSTCODE. For further assistance, please contact your Account Manager or call Australia Post on 13 21 31. |
| 43017 | ALL_OR_NONE_SHIPMENT_NO_ERROR | The request contains shipments with items that are missing barcode ids. Please add barcode ids to the items where the ids are missing, and resubmit your request. |
| 44002 | ALL_OR_NONE_AUSPOST_ID_ERROR | The request contains shipments with items that are missing a tracking identifier field. Please ensure that each item contains values for the fields consignment_id, article_id, and barcode_id, and resubmit your request. |
| 41007 | FROM_POSTCODE_DOES_NOT_ MATCH_CONTRACT_ORIGIN_POSTCODE | The postcode POSTCODE submitted for the sender "from" address does not match the lodgement postcode POSTCODE the contract. Please change the sender "from" postcode to match the lodgement postcode in the contract and attempt the request again. |
| 42002 | NO_PRICES_FOR_PRODUCT | The service CODE is not available based upon the information submitted. |
| 43003 | UNABLE_TO_CALCULATE_PRICE | The service CODE is not available based upon the submitted weight of WEIGHT kg. |
| 43004 | UNABLE_TO_CALCULATE_PRICE | The service CODE is not available based upon the calculated cubic weight of WEIGHT kg for the submitted dimensions and weight. |
| 42006 | MAX_WIDTH | Maximum width must not exceed 105 cm |
| 42007 | MAX_HEIGHT | Maximum height must not exceed 105 cm |
| 42008 | MAX_LENGTH | Maximum length must not exceed 105 cm |
| 42009 | MAX_VOLUME | Maximum volume must not exceed 0.25 m3 |
| 42010 | MAX_WEIGHT | Maximum weight must not exceed 10000 kg |
| 42011 | TWO_DIMENSIONS_LESS_THAN_5CM | At least 2 dimensions must be 5 cm |
| 44010 | MAX_LENGTH_MERCHANT_REFERENCE_TEXT | A value for merchant reference exceeds the maximum limit of 50 characters. Please reduce the length of the value and submit the request again. |
| 44003 | DANGEROUS_GOODS_NOT_ SUPPORTED_BY_PRODUCT_ERROR | The product CODE specified in an item has indicated that dangerous goods will be included in the parcel, however, the product does not allow dangerous goods to be sent using the service. Please choose a product that allows dangerous goods to be included within the parcel to be sent. |
| 44005 | DUPLICATE_ARTICLE_ID_ERROR | The merchant specified article_id of ABCZ12345678EXP00001 has been identified as a duplicate. All article_id values submitted must be unique. Please resubmit using a unique article_id for the item. |
| 44006 | DUPLICATE_CONSIGNMENT_ID_ERROR | The merchant specified consignment_id of ABCZ12345678 has been identified as a duplicate. All consignment_id values submitted must be unique. Please resubmit using a unique consignment_id for the item. |
| 44007 | DUPLICATE_BARCODE_ID_ERROR | The merchant specified barcode_id of ABCZ12345678EXP00001 has been identified as a duplicate. All barcode_id values submitted must be unique. Please resubmit using a unique barcode_id for the item. |
| 43009 | MAX_LENGTH_CUSTOMER_REFERENCE_TEXT | A value for customer reference 1 or 2 exceeds the maximum limit of 50 characters. Please reduce the length of the value and submit the request again. |
| 43011 | MAX_LENGTH_DELIVERY_INSTRUCTION | A value for delivery instructions exceeds the maximum limit of 128 characters. Please reduce the length of the value and submit the request again. |
| 400 | MAX_LENGTH_DESTINATION_BUSINESS_NAME | Business name longer than 40 characters: VALUE |
| 40002 | JSON_MANDATORY_FIELD_MISSING | The input request is missing the mandatory field with the name 'FIELD NAME'. Please resubmit the request including the required fields and values. |
| 44043 | ITEM_DIMENSION_WEIGHT_NOT_APPLICABLE_ERROR | The product PRODUCT is a flat-rate product and must not include weight or dimensions. |
| 80002 | INVALID_OPTION_COMBINATION | The combination of authority to leave, partial delivery allowed and safe drop enabled are not valid for product PRODUCT. Please enter valid values for these fields. If you need assistance, please contact us at auspost.com.au/lodgement-techsupport. |
| 400 | INVALID_PRINT_AT_DEPOT_PRODUCT | Print at Depot is not available for this product. Startrack EXP, PRM and FPP products are supported. |
| 400 | INVALID_PRINT_AT_DEPOT_MOVEMENT_TYPE | Print at Depot is not available for this movement type. Movement type can be either RETURN or TRANSFER. |
| Code | Name | Example Message |
|---|---|---|
| 66004 | NO_CONTRACT_PRICING_AVAILABLE_FOR_SHIPMENT | Your account currently does not have a contracted rate for this product, "from" and "to" lane combination in shipment SHIPMENT ID - please contact your account manager for further information. |
| 44062 | PARTIAL_DIMENSIONS_IN_SHIPMENT_WARNING | Incomplete dimensions supplied - price will be calculated on weight. |
| 44061 | PARTIAL_DELIVERY_NOT_APPLICABLE_WARNING | Partial delivery is not applicable for this product. |
| Warning Message | Description |
|---|---|
| Only the first 2 lines of the Sender's address can be included in the lodgement information. | This warning occurs if you specify more than 2 lines in the "from" address for StarTrack products. |
| One or more shipments have a cubic weight more than 4 times greater than dead weight. | The cubic weight of a shipment is more than 4 times greater than the dead weight you specified. Please ensure that the weight and dimensions are correct. The shipping price is calculated on the larger weight value. |
| One or more shipments have a dead weight more than 4 times greater than cubic weight. | The dead weight of a shipment is more than 4 times greater than the cubic weight we calculated. Please ensure that the weight and dimensions are correct. The shipping price is calculated on the larger weight value. |