Troubleshooting

This section contains some common problems you might encounter when working with the Shippit APIs.

If you are having trouble, start debugging with these strategies:

  • Check the response body: the error response usually contains a detailed message explaining the issue.
  • Validate your request: double-check that your request payload matches the expected format and includes all required fields.
  • Inspect API logs: if available, review your API logs to see the exact request and response details.
  • Contact Shippit support: if you’re unable to resolve the issue, reach out to the Shippit support team for assistance.

Common mistakes in order creation

Order creation is the most complicated part of the Shippit APIs, and the area where most errors are found. Check these things first:

Incorrect units

Shippit expects specific units for various measurements in the /orders request payload:

  • Parcel dimensions: Length, width, and depth should be in metres. A common mistake is to provide these values in centimetres or inches.
  • Parcel weight: Weight should be in kilograms. Make sure you convert from other units like grams or pounds.

Missing required fields

The required fields for an order can vary depending on several factors:

  • Order type: Standard, express, priority, click & collect, and on-demand orders have different requirements.
  • Carrier: Different carrier may have specific data requirements.
  • International: International orders typically require more information, such as customs declarations and tariff codes.

Carefully review the API documentation for the specific order type and carrier you are using to ensure all required fields are included.

Incorrect data types

Ensure that the data types of the values you provide in the request payload match the expected types in the API documentation. For example:

  • Quantities: Should be integers
  • Prices: Should be numbers, and can include decimals
  • Booleans: Should be true or false

Address validation

Shippit has strict address validation. If the validate field is set to true in the request, the order is only saved if the address is valid. Common issues include:

  • Incorrect postcode: Ensure the postcode matches the suburb and state.
  • Invalid suburb: Double check the spelling and ensure it is a valid suburb for the given postcode.
  • Missing address components: Some countries require additional address fields like delivery_district_city.

If the address is invalid, Shippit sometimes returns a suggested_address in the response, which you can use to correct the address.

Parcel and product specification

  • Parcel attributes and product attributes: Understand the difference between these two fields and when to use each one. If you are specifying product details separately from parcel information, use both parcel_attributes and product_attributes. Otherwise, use only parcel_attributes.
  • Parcel allocation: Be aware of the Allocate each item in an order to a separate carton setting in your Shippit account. This setting affects how Shippit allocates parcels based on the provided information.

Tracking only orders

  • Required fields: When creating a tracking-only order where the courier is booked outside of Shippit, make sure you provide the tracking_only, courier_allocation, and parcel_attributes → label_number fields.
  • Tracking histories: Consider providing tracking_histories to give the recipient more visibility into the order’s progress.

Package allocation errors

If you find that you’re not getting the expected package allocation responses when shipping multiple parcels, it could be because of the way the package allocation engine works.

When you send an order containing multiple items, the system consolidates the items into a single shipment, and calculates the dead weight and volumetric weights. The larger of the dead weight or the volumetric weight is then used for quoting shipping costs. For example, if you have two items weighing 300g each, the total of 600g is the amount used for quoting.

This consolidated weight then gets matched against the parcel presets that exist in the system. This depends on your package allocation settings, which you can adjust in the Shippit web interface. For example, the 600g total might get allocated to a 1kg satchel. This is despite the fact that the items themselves only weigh 300g each.

For more information about package allocation, see the understanding package allocation article in the Shippit help centre.