Creating consignments is at the core of MachShip's functionality. Consignments describe everything related to a job that needs to travel, including the pick-up location, delivery location and the individual items themselves. On top of this, a consignment is linked to a specific carrier, service, and account, which describes who will be transporting this consignment.

Moreover, international Consignments are Consignments that will be sent with one either the from location or the to location as an international address. These consignments will also contain valid customs information that will allow for a successful 

When creating a consignment via the API, the standard workflow process is as follows:

• You generate prices and routes from Machship's /apiv2/routes/returnRoutes endpoint
• Your user or system selects the route and despatch option they want to use
• You create a consignment in MachShip based on that route

This article will outline the properties and steps required to create a dangerous goods consignment in MachShip. This article assumes you have read the Generating Prices and Routes article as routing is a precursor to creating a consignment. Just so you know, it is not required to generate routes before creating consignments, however, this is only recommended for advanced users.

Create Consignment Request Parameters

All these details must be provided to the /apiv2/consignments/createConsignmentwithComplexItems for MachShip to return your valid despatch options. Please refer to our API documentation for further technical documentation regarding creating consignments.

Despatch DateTime (optional)

MachShip allows you to specify the despatch date and time of the consignment. Please refer to our Working with Despatch Dates when Routing and Creating Consignments documentation for further information on specifying the Despatch DateTime.

Pickup and Delivery Locations

For an International location consignment, there must be either the pickup or the delivery address as an international location. To understand how to work with Australia addresses please refer to our working with locations when routing and creating consignments documentation. The specific differences required for an international address will be:

User must first set the IsInternational flag as true
Example of using setting the Is International Flag as Try and postcodes to specify the pickup and delivery suburbs.

{
  ...
  "isInternational": true,
 ...
}

Once completed you can provide one of either the internationalFromCity, internationalFromPostcode, internationalFromProvinceand fromCountryCode

for an Import or

one of either the internationalToCity, internationalToPostcode, internationalToProvinceand toCountryCode

for an export

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

Example Export to the Texas United States

{
...  
"internationalFromCity": "Texas",
"internationalFromPostcode": "73301",
"fromCountryCode": "USA",
  ...
}

Users must also provide a valid phone number location name and address

Special Instructions

Special Instructions allow you to specify any special instructions that need to be passed on to the carrier regarding the delivery location. This could include instructions such as 'leave at the front door'.

Items

The Items Please refer to our Working with Items when Routing and Creating Consignments documentation for details on how to specify items when generating a routing request. Below details discuss specifically the differences in the creation of a consignment using Complex Items:

• Item Type (required). You should choose the item type that best describes the goods that you are sending. ItemType must be one of the following values: 'Carton', 'Skid', 'Pallet', 'Crate', 'Satchel', 'Roll', 'Panel', 'Bag', 'Tube', 'Stillage', 'Envelope', 'Pack', 'Rails', 'TimberPack', 'Pipe', 'BDouble', 'Semi', 'TwentyFootContainer', 'FortyFootContainer', 'Bundle', and 'Case'
• Name (required). A brief description of the item
• SKU (optional). The SKU of the item from your calling system
• Quantity (required). The number of this item that you are sending. For example, if you were sending 5 cartons with the same dimensions, you would send through 1 item object with a Quantity of 5.
• Weight (required). The weight of the item in kg
• Length (required). The length of the item in cm
• Width (required). The width of the item in cm
• Height (required). The height of the item in cm

{
  ......
"items": [
    {    
      "itemType": "Carton",
      "name": "string",
      "sku": "string",
      "quantity": 0,     
      "standardItem": {
        "height": 0,
        "weight": 0,
        "length": 0,
        "width": 0
      }  ...
}

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

Example Item Content of TShirts manufactured in NZ

"consignmentItemContents": [
        {
          "description": "Tshirts",
          "reference1": "INV123456",
          "reference2": "OR9876",
          "reference3": "PO1234",
          "quantity": 5,
          "dollarValue": 5,
          "ciMarksAndNumbers": null,
          "harmonizedCode": "61091000 ",
          "partNumber": null,
          "purpose": "Sale",
          "countryOfManufactureCode": "USA"
          }
        }
      ]

Company ID (optional)

Company ID can be used if you wish to get routes for a specific company in MachShip. This is useful if you have multiple companies in MachShip and need to get routing and pricing for different companies. If no company ID is provided, the company that your user is assigned to will be used to return routes. Please refer to /apiv2/companies for company documentation.

{
  ...
  "companyId": 9999
  ...
}

Carrier Selection:

Carrier ID (Optionally required)

Carrier ID tells MachShip which carrier should be used for this consignment. This should be taken from the selected route using the carrier.id property.

Carrier Account ID ( Optional )

Carrier Account ID tells MachShip which account should be used for this consignment. This should be taken from the selected route using the carrierAccount.id property.

Company Carrier Account ID ( Optional )

Company Carrier Account ID tells MachShip which carrier should be used for this consignment. This should be taken from the selected route using the companyCarrierAccountId property.

Carrier Service ID ( Optional )

Carrier ID tells MachShip which carrier should be used for this consignment. This should be taken from the selected route using the carrierService.id property.

Alternatively you can have MachShip select either the cheapest or the fastest available option by not providing any of the above and setting

Default Route Selection (Optional)

Should you not know the carrier you have the option to allow MachShip to select either the "cheapest" or the "Fastest" carrier option.

This would be passed through as:

{
  ...
  "defaultRouteSelection": "cheapest",
  ...
}

Just so you know, you will need to either pass through the Default Route Selection or at a minimum the CarrierId when creating a consignment.

Customer References (optional)

You can provide 2 customer references when creating a consignment. These could be a Purchase Order number, an internal reference to your system, etc. These can be provided using the following properties.

{
  ...
  "customerReference": "testRef",
  "customerReference2": "testRef2"
  ...
}

Question IDs (optional)

Question IDs allow you to pass in answers to questions that allow MachShip to further restrict routes. This should not be specified unless advised to do so by the MachShip support team.

"questionIds": [0]

Send Tracking Emails (optional)

If you wish to send out a tracking email (ASN) to a client you would provide the SendTrackingEmail option as true and then provide an email address(es) in the toEmail field.

{
  ...
 "sendingTrackingEmail": false,
  ...
}

Send Custom Values (optional)

Custom Values are in MachShip are consignment specific integration options that exist for a carrier. These are shown within the platform like the below:

To Set these via the API you would set the property name (email us at support@machship.com) if you are looking for a specific property and then set the value for that property.

{
  ...
  "customValues": [
    {
      "propertyName": "string",
      "value": "string"
    }
  ]
  ...
}

Printer Token (optional)

When using the MachShip Printing Application to automate the printing process in MachShip a user has the facility to utilise an internal identifier to direct the printing. Via the API this can be set as the printerToken. If you are using this then you would configure it internally via with a Printer Configuration Evaluation. See the instructions linked below:

Printer Configuration Evaluation

{
  ...
 "printerToken": "string",
  ...
}

ReceieverAccount(s) (optional)

Should you wish to generate a receiver pays consignment in MachShip to charge the consignment to a third party or receiver then you would provide either the receiverAccountCode or the save receiverAccountId. 

Note when booking Receiver Pays there is a requirement to pass through the Carrierid and the CarrierAccountId for the sending account. The account must also be configured to allow receiver pays based on the instructions below:

How to allow a Company to Consign Receiver Pays

{
  ...
  "receiverAccountCode": "string",
  "receiverAccountId": 0,
  ...
}

Staff Member Name (optional)

The staff member name is a free text field that is optional which will allow a user to set which internal team member has generated the consignment. 

{
  ...
"staffMemberName": "string",
  ...
}

Dangerous Goods Declaration (Required) 

This should be set to false

{
  ...
"dgsDeclaration": true,
  ...
}

Elective Surcharge Id's (Optional) 

If you have an elective surcharge that you wish to include in this consignment creation, an example would be a hydraulic tailgate or hand unload the delivery, pass through the id of this surcharge in the array provided. These ids will be provided back as options to you when generating routes. 

{
  ...
"electiveSurchargeIds": [
   11,12
 ]
  ...
}

Create Consignment with complex Items Request Example

{
  "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,
  "companyCarrierAccountId": 789,
  "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",
  "specialInstructions": "leave at front door"
}

Create Consignment Response

If a consignment is created successfully, MachShip will return an object with a subset of the properties relating to the consignment including:

• ID: this is the unique identifier that you should reference for all other API calls relating to this consignment. For future API calls, it is recommended that this ID is stored within your system
• ConsignmentNumber: This the ID with a MS prefix. This is the human-friendly ID that is used in MachShip's UI and is also the main reference that is sent through to the carrier
• CarrierConsignmentID: This is the reference that will be used by the carrier
• Status: Most consignments, when created, will remain in an unmanifested state until a user manifests the consignment. Unmanifested means that it exists solely in MachShip and has not been transmitted to the carrier. Note that some carriers and accounts are configured to automatically manifest on consignment creation. This means that a status of Manifested would be returned for these consignments and that details of the consignment have been transmitted to the carrier.
• Pricing: This will provide the pricing of the consignment and also breakdown the surcharges. 
• Items - this will provide a breakdown of  the consignments Items information including the dimensions, weights, references (barcode data) and item contents

  {
  "object": {
  "carrierConsignmentId": "ABC000123456",
  "status": {
  "id": 2,
  "name": "Unmanifested",
  "description": "Unmanifested"
  },
  "trackingPageAccessToken": "<tracking page token>",
  "consignmentTotal": {
  "sellPricesCleared": false,
  "consignmentCarrierSurchargesCostPrice": 0.00000,
  "consignmentCarrierSurchargesSellPrice": 0.00000,
  "consignmentCarrierSurchargesFuelExemptCostPrice": 0.00000,
  "consignmentCarrierSurchargesFuelExemptSellPrice": 0.00000,
  "totalConsignmentCarrierSurchargesCostPrice": 0.00000,
  "totalConsignmentCarrierSurchargesSellPrice": 0.00000,
  "totalSellPrice": 20.30691,
  "totalCostPrice": 0.00000,
  "totalBaseSellPrice": 16.78257,
  "totalBaseCostPrice": 0.00000,
  "totalTaxSellPrice": 1.84608,
  "totalTaxCostPrice": 0.00000,
  "costFuelLevyPrice": 0.00000,
  "sellFuelLevyPrice": 1.6782,
  "consignmentRouteCostPrice": 0.00000,
  "consignmentRouteSellPrice": 16.78257,
  "totalCostBeforeTax": 0.00000,
  "totalSellBeforeTax": 18.46083
  },
  "consignmentHourlyPricing": null,
  "consignmentCarrierSurcharges": [],
  "printSettings": {
  "printConsignmentLabels": false,
  "printItemLabels": true,
  "printSpecialInstructionsLabels": true
  },
  "items": [{
  "companyItemId": 0,
  "itemType": "Carton",
  "name": "test",
  "sku": null,
  "quantity": 1,
  "height": 10.00000,
  "weight": 10.00000,
  "length": 10.00000,
  "width": 10.00000,
  "references": [
  "ABC000123456001"
  ],
  "consignmentItemContents": null
  }],
  "id": 123456,
  "consignmentNumber": "MS00123456",
  "despatchDateLocal": "2018-07-02T09:00:00",
  "despatchDateUtc": "2018-07-01T23:00:00",
  "etaLocal": "2018-07-04T17:00:00",
  "etaUtc": "2018-07-04T07:00:00",
  "carrier": {
  "id": 11,
  "name": "TNT Express",
  "abbreviation": "TNT",
  "displayName": "TNT Express (TNT)"
  },
  "carrierService": {
  "id": 123,
  "name": "Road Express",
  "abbreviation": "76",
  "displayName": "Road Express (76)"
  },
  "isTest": false
  "isInternational": true
  },
  "errors": [
  ]
  }