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.

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

• 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 consignment in MachShip. This article assumes you have read the Generating Prices and Routes article as routing is a precursor to creating a consignment. Note that 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/createConsignment 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

Please refer to our Working with Locations when Routing and Creating Consignments documentation for details on how to specify locations when generating a routing request.

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 front door'.

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.

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 ID (Optional)

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.

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",
  ...
}

Note that 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": true,
  ...
}

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",
  ...
}

ReceiverAccount(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 as true or false based on if the consignment contains Dangerous Goods. 

For an understanding of how to create a dangerous goods consignment via the API, please refer to the article linked below:

How to Create A DG Consignment via the API

{
  ...
"dgsDeclaration": false,
  ...
}

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 Request Example

{
  "items": [
    {
      "itemType": "Carton",
      "name": "test",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10
    }
  ],
  "dgsDeclaration": false,
  "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",
  "toLocation": {
    "suburb": "Sydney",
    "postcode": "2000"
  },
  "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
  },
  "errors": [
    
  ]
}