Creating International Consignments via the MachShip API

Overview

Welcome to the guide on international consignments using the MachShip API. This document serves as a companion to our main guide on Creating Consignments and focuses specifically on the additional considerations and steps required when shipping dangerous goods.

Understanding International Consignments

International consignments are consignments where either the from OR to location is a country outside of Australia. MachShip does not support shipments where both to and from are outside of Australia - either the from OR to country must be Australia.

In the context of MachShip, an international consignment includes all the standard consignment information (pick-up location, delivery location, items) plus additional details regarding the goods being sent.

Key Differences for International Consignments

When creating an international consignment via the MachShip API, there are several key differences compared to standard consignments:

  1. API Endpoint: You'll use the /apiv2/consignments/createConsignmentwithComplexItems endpoint instead of the standard consignment creation endpoint. This endpoint is not limited for use with international consignments and can be used to create any consignment - it simply has additional fields.
  2. International State & Country Fields: You must provide the city, state, country
  3. Package Contents: Inside each package, we required detailed information about the goods being shipped for duties purposes.

Creating International Consignments

The process of creating an international consignment is similar to creating a standard consignment, with some additional steps and parameters.

Request Preparation

When preparing your request to the /apiv2/consignments/createConsignmentwithComplexItems endpoint for an international consignment, you'll need to include additional information beyond what's required for standard consignments.

isInternational flag

This is a required field for all consignments being shipped internationally. You must set this to true for international consignments:

{
  "isInternational": true
}

Pick Up & Delivery Location

For an International location consignment, there must be either the pickup or the delivery address as an international location.

You can provide one of either:

  • Imports: internationalFromCity, internationalFromPostcode, internationalFromProvince and fromCountryCode
  • Exports: internationalToCity, internationalToPostcode, internationalToProvince and toCountryCode

Note: that the country codes will be the 3 alpha country codes

Example Export to the Texas United States:

{
  ...
  "fromName": "My Warehouse",
  "fromContact": "Bob Jones",
  "fromPhone": "123123123",
  "fromEmail": "test@test.com",
  "fromAddressLine1": "testAddressLine1",
  "fromAddressLine2": "testAddressLine2",

  "isInternational": true,
  "internationalFromCity": "Texas",
  "internationalFromPostcode": "73301",
  "fromCountryCode": "USA",

  "toName": "Customers House",
  "toContact": "Stacy Smith",
  "toPhone": "123123123",
  "toEmail": "test@test.com",
  "toAddressLine1": "testAddressLine1",
  "toAddressLine2": "testAddressLine2",
  "toLocation": {
    "suburb": "Sydney",
    "postcode": "2000"
  },
  ...
}

Users must also provide a valid phone number

Items with item contents

In order to allow for a smooth transfer through customs, it is very important that you supply the customs fields in the item contents section - please note that you will only be able to proceed to a quote if you provide this information.

Details to supply will be:

  • Description - The description of the goods being imported/exported
  • Reference 1, Reference 2, Reference 3, CL Marks and Numbers, Part Number - These fields will all identify either the object or the invoice/order
  • Quantity - Quantity of the physical goods being shipped - note this will be different to the item quantity above, if it was five t-shirts packed in a carton then the quantity is 5
  • Harmonized Code - The global customs identifier for the class of goods being shipped
  • Purpose - This must describe the reason for sending the goods. Needs to match up with a known classification reason i.e. sale, gift, return etc.
  • Country of Manufacture - Will identify where the product was manufactured. You will need to select this from the drop-down of allowable MachShip values.
  • Dollar Value - This is the commercial dollar value of the goods in AUD
{
  "items": [
    {
      "itemType": "Carton",
      "name": "Test Carton",
      "sku": "CART",
      "quantity": 1,
      "standardItem": {
        "height": 25,
        "weight": 5,
        "length": 20,
        "width": 20
      },
      "consignmentItemContents": [
        {
          "description": "Tshirts",
          "reference1": "INV123456",
          "reference2": "OR9876",
          "reference3": "PO1234",
          "quantity": 5,
          "dollarValue": 5,
          "ciMarksAndNumbers": null,
          "harmonizedCode": "61091000 ",
          "partNumber": null,
          "purpose": "Sale",
          "countryOfManufactureCode": "USA"
          }
      ]
    }
  ]
}

Send Your Request

Once you've prepared all the necessary information, including the international fields and details, you're ready to send your request. Here's an example of what a complete request for an international consignment might look like:

POST https://live.machship.com/apiv2/consignments/createConsignmentwithComplexItems HTTP/1.1
Host: live.machship.com
token: <api_token>
body:
{
  "dgsDeclaration": false,
  "items": [
    {
      "itemType": "carton",
      "name": "Test Carton",
      "sku": "CART",
      "quantity": 1,
      "standardItem": {
        "height": 25,
        "weight": 5,
        "length": 20,
        "width": 20
      },
      "consignmentItemContents": [
        {
          "description": "test item content",
          "reference1": "Test Ref 1",
          "reference2": "Test Ref 2",
          "reference3": "Test Ref 3",
          "quantity": 1,
          "dollarValue": 5.0,
          "ciMarksAndNumbers": "CI Test Mark Num",
          "harmonizedCode": "12345",
          "partNumber": "TEST Part No",
          "purpose": "BUSINESS",
          "countryOfManufactureCode": "USA"
        }
      ]
    }
  ],
  "carrierId": 11,
  "carrierServiceId": 123,
  "carrierAccountId": 456,

  "fromName": "My Warehouse",
  "fromContact": "Bob Jones",
  "fromPhone": "123123123",
  "fromEmail": "test@test.com",
  "fromAddressLine1": "testAddressLine1",
  "fromAddressLine2": "testAddressLine2",
  "fromLocation": {
    "suburb": "melbourne",
    "postcode": "3000"
  },

  "toName": "Customers House",
  "toContact": "Stacy Smith",
  "toPhone": "123123123",
  "toEmail": "test@test.com",
  "toAddressLine1": "testAddressLine1",
  "toAddressLine2": "testAddressLine2",

  "internationalToCity": "Beverly Hills",
  "internationalToPostcode": "90210",
  "internationalToProvince": "CA",
  "toCountryCode": "USA",
  "isInternational": true,

  "specialInstructions": "leave at front door"
}

Response Handling

The response for a consignment includes:

  • id: Unique identifier for the consignment
  • carrierConsignmentId: Carrier's reference
  • status: Usually "Unmanifested" for new consignments
  • consignmentTotal: Breakdown of pricing and surcharges
  • items: Detailed item information

Error Handling

Common international-specific errors include:

  1. "International routes require that customs information be provided for all items. Please specify the contents on each item": Missing item contents and key fields inside.

For more information on handling API errors, refer to our Common API Errors guide.