{{ activeApiMethod.description }}
This service adds or updates an item in an existing shipment that has previously been created using the Create Shipment service.
Please Note: The maximum number of items for Parcel Post and Express Post domestic despatch movements is 20 items.
HTTP Response Code: 201
HTTP Response Code: 400
| Element Name | Description | Optional / Mandatory | Type | Length |
|---|---|---|---|---|
| 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_id | The identifier for the item previously generated by Australia Post during a Create Domestic Shipments API call. You specify this field to make changes to an existing item. If you don't specify this field, then a new item is created and added to the shipment. It will replace any older items on the shipment. | Optional | String | 50 |
| 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. | Optional | 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. | Optional (See Desc.) | Decimal | 4.1 |
| height | The height of the parcel in centimetres. If volumetric pricing applies then this is mandatory. | Optional (See Desc.) | Decimal | 4.1 |
| weight | The parcel’s weight in kilograms. | Mandatory | Decimal | N.3 |
| contains_dangerous_goods | Whether the item contains dangerous goods, generated by the merchant. | Optional. Defaults to false. | Boolean - true or false | |
| authority_to_leave | Whether the item can be left in a safe place on delivery without receiving a signature. This is optional for domestic shipments, but must not be specified for international shipments. | Optional (See Desc.) - Defaults to true for Australia Post, and false for StarTrack. | Boolean - true or false | |
| 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 |
| 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). | Decimal | N.2 |
| total_gst | The goods and services tax amount included in the total cost. | 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 |
| contains_dangerous_goods | Whether the item contains dangerous goods, generated by the merchant. | Boolean - true or false | |
| authority_to_leave | Whether the item can be left in a safe place on delivery without receiving a signature. | Boolean - true or false | N/A |
| 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 |
| 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 |
| 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 |
| 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 |
|---|---|---|
| 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 to be included within the parcel to be sent. |
| 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. |
| 44013 | SHIPMENT_NOT_FOUND_ERROR | The shipment with shipment id SHIPMENT you requested can not be found. Please check the shipment id requested and submit the request again. |
| 44025 | NO_SHIPMENT_TO_UPDATE | The request you have entered does not contain any shipments |
| 44038 | SHIPMENT_NOT_WITH_CONTRACT_ERROR | The shipment with shipment id SHIPMENT does not belong to the contract with account number ACCOUNT. Please process the shipment which belongs to only one contract defined by the account number in the request. |
| 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. |
| 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. |
| 42002 | NO_PRICES_FOR_PRODUCT | The service CODE is not available based upon the information submitted. |
| 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 |
| 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. |
| Warning Message | Description |
|---|---|
| One or more shipments have a cubic weight more than 4 times greater than dead weight. | The cubic weight of an item in the 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 an item in the 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. |