One of MachShip's primary functions is to dynamically generate prices and routes based on the items that are being sent. When pricing, MachShip will describe every despatch option and price that is available for a given combination of:

• Pickup suburb and postcode
• Delivery suburb and postcode
• Items being sent
• Desired despatch date and time

MachShip uses its own pricing and routing engine to determine which carriers and services are available to be used for any given consignment. If a route/price is not returned, this could mean:

• The service/your rates do not pick up from the pickup suburb and postcode
• The service/your rates do not travel to the delivery suburb
• The service does not support the items that you are sending. For example, the goods could be too big or too small

MachShip's routing and pricing engine will provide different prices/despatch options as consignment details change.

Getting Routes and Prices from Machship

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

Route and Price Response

When valid routes and prices are found, MachShip will return all available options for the given route parameters. This means it will return an array of the available Carrier / Service / Account options. Each option will be provided with the following information:

• Carrier: For example, TNT or Startrack
• CarrierService: For example, General or Express
• CarrierAccount: Details of the account for this carrier
• CompanyCarrierAccountID: Details of the company carrier account
• ConsignmentTotal: This contains all pricing information for the route
• Details of the Pickup and Delivery Locations: For example, if you use a saved location, this will return all the details of that location
• Despatch Options: This includes the despatch date, the ETA, whether the date is affected by public holidays, and so on
• Item summary details: A summary of the items being sent

Return Routes Parameters

Return Routes allows you to specify consignment details in any way that works for you and your system.

Despatch DateTime (optional)

MachShip allows you to specify the despatch date and time of the consignment. The despatch DateTime should be set to when the goods are picked and ready to be picked up by the carrier. MachShip will return valid routes AFTER the Despatch DateTime that has been provided. If you provide a Despatch DateTime that is in the past, MachShip will default the despatch DateTime to NOW. 

If no Despatch DateTime is provided, MachShip will default to NOW. Despatch date can be specified in 2 ways and only one of them should be provided:

Despatch Date UTC
This is the Despatch DateTime in UTC time

"despatchDateTimeUtc": "yyyy-MM-ddThh:mm:ss.000Z"

Despatch Date Local
This is the despatch date and time localised to the pickup suburb's timezone

"despatchDateTimeLocal": "yyyy-MM-ddThh:mm:ss.000Z"

If you provide both UTC and local time, UTC time will be used.

Pickup and Delivery Locations

MachShip offers the following ways to specify the pickup and delivery locations for the consignment.

• Suburb and Postcode Combination
• Saved Company Location ID
• MachShip's Location ID (Suburb ID)

The pickup location and delivery location can be specified via different methods. For instance, the pickup location could be provided as a saved company location while the delivery location may be specified as a suburb and postcode. You only need to specify one of these methods for both the pickup and delivery locations for generating routes and pricing. For example, if you provide a companyLocationId for the pickup location, you do not need to provide the suburb and postcode.

Suburb and Postcode Combination

MachShip uses an up-to-date suburb postcode list which you can use when specifying pickup and delivery locations. These can be specified with the location.suburb and location.postcode properties. You can also validate a suburb that a user has entered outside of routing via /apiv2/locations/GetLocations, however, this is not required as routing will also validate the entered suburbs for you.

Example of using suburb and postcodes to specify the pickup and delivery suburbs.

{
  ...
  "fromLocation": {
    "suburb": "melbourne",
    "postcode": "3000"
  },
  "toLocation": {
    "suburb": "sydney",
    "postcode": "2000"
  }
  ...
}

Saved Company Location ID

MachShip allows you to create saved company locations for frequently used pickup or delivery locations. These saved locations can be specified when generating routes and prices by providing the id of the appropriate saved company location. Saved company location IDs can be retrieved via our /apiv2/companyLocations endpoints.

{
  ...
  "fromCompanyLocationId": 1234,
  "toCompanyLocationId": 5346,
  ...
}

MachShip's Location ID (Suburb ID)

MachShip maintains its own list of suburbs and the IDs of these locations can be used when returning routes. Please refer to our /apiv2/locations documentation for retrieving location IDs from MachShip.

{
  ...
  "fromLocationId": 5002,
  "toLocationId": 111,
  ...
}

Pickup and Delivery Location Errors

If there are any issues with the locations provided, you will receive a response similar to below:

{
  "object": null,
  "errors": [
    {
      "validationType": "Error",
      "memberNames": [],
      "errorMessage": "From Location is invalid"
    }
  ]
}

Items

MachShip offers multiple ways to specify the items for the consignment. To return prices, at least 1 item must be supplied. Multiple items can be specified. MachShip offers the following ways for you to specify items:

• Specifying the item details
• Referencing Items saved in MachShip via ID, SKU or Name

You can save items in MachShip and refer to these items via the API. These saved items can be used or you can specify the item details per request. 

Specifying Item Details

Items can be provided per request by specifying the following properties:

• 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', '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 KGs
• Length (required): The length of the item in CMs
• Width (required): The width of the item in CMs
• Height (required): The height of the item in CMs

{
  ...
  "items": [
    {
      "itemType": "Carton",
      "name": "test",
      "sku": "test",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10
    }
  ]
  ...
}

Saved Items

MachShip allows you to save commonly used items which can then be used when routing and creating consignments. A saved item can be referred to by either its ID, SKU or Name. Please refer to our /apiv2/companyItems documentation for retrieving saved items from MachShip.

//accessing a saved item by id
"items": [
    {
      "companyItemId":999
    }
  ]
  
//accessing a saved item by SKU
"items": [
    {
      "sku":"test"
    }
  ]
  
//accessing a saved item by Name
"items": [
    {
      "name":"test"
    }
  ]

When using saved items, you can also override any of the properties of the item by specifying them along with the ID, SKU or Name. The below example will set the quantity to 5 and the weight 15kg but all other properties will be taken from the saved item.

"items": [
    {
      "companyItemId":999,
      "quantity":5,
      "weight":15
    }
  ]

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

Carrier IDs allow you to restrict the routes that are returned to certain carriers. It allows you to specify an array of carrier IDs. For example, you may want to only query TNT routes. To do this, you would set carrierIds to [11]. If this is not included in the request, all routes will be returned.

{
  ...
  "carrierIds": [11]
  ...
}

Carrier Account ID (optional)

Carrier Account ID allows you to restrict the routes that are returned to a particular carrier account. If this is not included in the request, all routes from all carrier accounts will be returned.

{
  ...
  "carrierAccountId": 9999
  ...
}

Carrier Service ID (optional)

Carrier Service ID allows you to restrict the routes that are returned to a particular carrier service. If this is not included in the request, all routes from all carrier services will be returned.

{
  ...
  "carrierServiceId": 9999
  ...
}

Company Carrier Account ID (optional)

Company Carrier Account ID allows you to restrict the routes that are returned to a particular company carrier account. If this is not included in the request, all routes from all carrier services will be returned.

{
  ...
  "companyCarrierAccountId": 9999
  ...
}

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]

Return Routes Example

Request Example 1: Suburbs and item details provided.

{
  "fromLocation": {
    "suburb": "melbourne",
    "postcode": "3000"
  },
  "toLocation": {
    "suburb": "sydney",
    "postcode": "2000"
  },
  "items": [
    {
      "itemType": "Carton",
      "name": "test",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10
    }
  ]
}

Request Example 2: Pickup Saved Location, Delivery Suburb and saved item via SKU provided.

{
  "fromCompanyLocationId": 1234,
  "toLocation": {
    "suburb": "sydney",
    "postcode": "2000"
  },
  "items": [
    {
      "sku":"test"
    }
  ]
}

Request Example 3: DespatchDateTime, Company, Carrier, Service, Account and Company Carrier Account and Questions provided.

{
  "despatchDateTimeUtc": "2018-06-30T02:24:00Z",  
  "companyId": 9999,
  "carrierIds": [11],
  "questions": [1],
  "carrierAccountId": 123,
  "carrierServiceId": 456,
  "companyCarrierAccountId": 789,
  "fromLocation": {
    "suburb": "melbourne",
    "postcode": "3000"
  },
  "toLocation": {
    "suburb": "sydney",
    "postcode": "2000"
  },
  "items": [
    {
      "itemType": "Carton",
      "name": "test",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10
    }
  ]
}

Routes Response Example

{
  "object": {
    "id": "0361877e-8112-4932-a610-1aed0e798e02",
    "routes": [
      {
        "carrier": {
          "id": 2,
          "name": "Toll IPEC",
          "abbreviation": null,
          "displayName": "Toll IPEC (IPEC)",
        },
        "carrierService": {
          "id": 16,
          "name": "Road Express",
          "abbreviation": "X",
          "displayName": "Road Express (X)"
        },
        "carrierAccount": {
          "id": 999,
          "name": "Test Account",
          "accountCode": "TEST",
          "carrierId": 2,
          "carrier": null,
          "displayName": "Test Account (TEST)"
        },
        "companyCarrierAccountId": 9999,
        "companyId": 9999,
        "consignmentTotal": {
          "sellPricesCleared": false,
          "consignmentCarrierSurchargesCostPrice": 0,
          "consignmentCarrierSurchargesSellPrice": 0,
          "consignmentCarrierSurchargesFuelExemptCostPrice": 0,
          "consignmentCarrierSurchargesFuelExemptSellPrice": 0,
          "totalConsignmentCarrierSurchargesCostPrice": 0,
          "totalConsignmentCarrierSurchargesSellPrice": 0,
          "totalSellPrice": 14.19935,
          "totalCostPrice": 11.86152,
          "totalBaseSellPrice": 11,
          "totalBaseCostPrice": 9.43,
          "totalTaxSellPrice": 1.29085,
          "totalTaxCostPrice": 1.07832,
          "costFuelLevyPrice": 1.3532,
          "sellFuelLevyPrice": 1.9085,
          "consignmentRouteCostPrice": 9.43,
          "consignmentRouteSellPrice": 11,
          "totalCostBeforeTax": 10.7832,
          "totalSellBeforeTax": 12.9085
        },
        "fromCompanyLocationId": null,
        "fromAddress": {
          "name": null,
          "addressLine1": null,
          "addressLine2": null,
          "location": {
            "id": 5002,
            "postcode": "3000",
            "state": {
              "code": "VIC",
              "name": "Victoria",
              "id": 1
            },
            "stateId": 1,
            "timeZoneId": 1,
            "timeZone": {
              "id": 1,
              "name": "Australia/Sydney",
              "jsName": "Australia/Sydney"
            },
            "suburb": "MELBOURNE",
            "searchStr": null,
            "description": "MELBOURNE, 3000, VIC",
            "descriptionShort": "MEL",
            "isFrom": false,
            "locationAliases": null,
            "locationType": 0,
            "countryId": 1,
            "country": {
              "id": 1,
              "name": "Australia",
              "code2": "AU",
              "code3": "AUS",
              "numeric": "036",
              "taxPercentage": 10
            },
            "subLocality": null
          },
          "contact": null,
          "phone": null,
          "email": null
        },
        "fromLocation": null,
        "fromZone": {
          "guid": "4dba15c4-67d8-441e-bb08-764626ae6029",
          "id": 539,
          "name": "Melbourne VIC 1",
          "abbreviation": "MEL1",
          "carrierId": 0,
          "displayName": "Melbourne VIC 1 (MEL1)"
        },
        "toCompanyLocationId": null,
        "toAddress": {
          "name": null,
          "addressLine1": null,
          "addressLine2": null,
          "location": {
            "id": 111,
            "postcode": "2000",
            "state": {
              "code": "NSW",
              "name": "New South Wales",
              "id": 5
            },
            "stateId": 5,
            "timeZoneId": 1,
            "timeZone": {
              "id": 1,
              "name": "Australia/Sydney",
              "jsName": "Australia/Sydney"
            },
            "suburb": "SYDNEY",
            "searchStr": null,
            "description": "SYDNEY, 2000, NSW",
            "descriptionShort": "SYD",
            "isFrom": false,
            "locationAliases": null,
            "locationType": 0,
            "countryId": 1,
            "country": {
              "id": 1,
              "name": "Australia",
              "code2": "AU",
              "code3": "AUS",
              "numeric": "036",
              "taxPercentage": 10
            },
            "subLocality": null
          },
          "contact": null,
          "phone": null,
          "email": null
        },
        "toLocation": null,
        "toZone": {
          "guid": "84278c29-a593-4c0f-b3d2-cda0b797262e",
          "id": 531,
          "name": "Sydney NSW 1",
          "abbreviation": "SYD1",
          "carrierId": 0,
          "displayName": "Sydney NSW 1 (SYD1)"
        },
        "despatchOptions": [
          {
            "despatchDateLocal": "2017-04-10T00:00:00",
            "despatchDateUtc": "2017-04-09T14:00:00Z",
            "etaLocal": "2017-04-11T23:59:59",
            "etaUtc": "2017-04-11T13:59:59Z",
            "durationInMinutes": 2880,
            "isTimeWindow": false,
            "totalDays": 2,
            "totalHours": 0,
            "totalBusinessDays": 1,
            "etaAffectedByPublicHolidays": false,
            "despatchDateAffectedByPublicHolidays": false,
            "businessDaysOnly": true
          }
        ],
        "fuelLevyPercentage": 10,
        "taxPercentage": 10,
        "electiveSurcharges": [
          {
            "costPrice": 0,
            "sellPrice": 150,
            "quantity": 1,
            "name": "Tailgate Required at Delivery"
          }
        ]
        "automaticSurcharges":[],
        "totalWeight": 10,
        "totalCubic": 0.18,
        "totalVolume": 0.001,
        "carrierLogoFileName": "tollIpec.png"
      }
    ]
  },
  "errors": null
}

Error Response Example

{
  "object": null,
  "errors": [
    {
      "validationType": "Error",
      "memberNames": [],
      "errorMessage": "From Location is invalid"
    }
  ]
}

No Routes Returned

MachShip's Routing and Pricing engine determine which carrier and services are available to you based on the properties of the consignment. Transport carriers often have limitations on their services including item size restrictions, rates for that service and limiting suburbs that a service covers. If MachShip determines that there are no valid routes for the given consignment, you will receive the following response

No Routes Response Example

{
  "object": null,
  "errors": null
}

If services are not being returned, please check the following limitations:

• Does the Carrier/Service operate within both your pickup and delivery locations?
• Are these areas covered by the rates that are loaded into MachShip?
• Are there sizing restrictions on the service and do your items exceed these limits?
• Does the specified company have access to the expected Carrier/Service via the carrier account and company carrier accounts?

If all of these conditions have been met, you can contact either the account holder or the MachShip support team at support@machship.com and we can help you diagnose any possible issues.