Creating Pending Consignments using the MachShip API

Creating Pending Consignments using the MachShip API

One of the key efficiency targets for any business is to cut out manual tasks and automate as many processes as possible. In the Supply Chain and Logistics sector, a key blocker to this achievement is having prior knowledge of the final shipping dimensions and weights of a consignment. In order to allow for partial automation of the consignment creation process, MachShip has the Pending Consignment feature which will enable a user to pass through Order Data or incomplete consignment data. 

So unlike creating a consignment, you do not need to provide the full data to create a Pending Consignment. However, the more info you provide, the easier it is to convert the pending consignment into a consignment.

This article will outline the properties and steps required to create a pending consignment in MachShip

Create Pending Consignment Request Parameters

All these details must be provided to the /apiv2/pendingConsignments/createPendingConsignment 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.

Only Address 1 field for both Pickup and Delivery Locations is required.

Special Instructions (optional)

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 (optional)

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.

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]

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

Create Pending Consignment Request Example

A basic request

{
  "fromAddressLine1": "testAddressLine1",
  "toAddressLine1": "testAddressLine1"
}

 A request with many fields provided

{
  "items": [
    {
      "itemType": "Carton",
      "name": "test",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10
    }
  ],
  "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 Pending Consignment Response

If a pending 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 pending consignment. For future API calls, it is recommended that this ID is stored within your system.
  • consignmentNumber: This is the ID with a PC 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.
{  
   "object":{  
      "id":12978,
      "consignmentNumber":"PC00012978"
   },
   "errors":[  
      {  
         "validationType":"Success",
         "memberNames":[  

         ],
         "errorMessage":"Pending Consignment Created Successfully"
      }
   ]
}
    • Related Articles

    • A guide to creating Consignments via the API

      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 ...
    • Machship API Integration Workflow Guide

      The objective of this article is to give you a quick-start guide in working with our API that demostrates common integration workflows, and how that affects which API endpoints you wish to use. API Authentication & Documentation Our API accepts and ...
    • A guide to creating Dangerous Goods Consignments via the API

      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 ...
    • Creating Benign Consignments Via The API

      Benign consignments are consignments created in Machship purely for the purpose of tracking and reporting - they cannot be manifested and no data is sent to the carriers. The endpoint is a version 1 API endpoint with the following URL: ...
    • Working with items when routing and creating Consignments

      When routing or creating consignments, MachShip requires the details of the items that are being sent. MachShip offers multiple ways to specify the items for the consignment/route request. To return prices, at least 1 item must be supplied. Multiple ...