One of MachShip's primary functions is to dynamically generate prices, routes and service availability based on the items that are being sent. When pricing, MachShip will describe every carrier, service and price that is available based on:
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:
MachShip's routing and pricing engine will provide different prices/dispatch options as consignment details change.
To get routes and prices from MachShip, you need to provide all the relevant details to either of the following endpoints:
/apiv2/routes/returnroutes - for standard consignments/apiv2/routes/returnrouteswithcomplexitems - for dangerous goods consignments, or when you are delegating your own barcodes/labels.
Important: Do not use the Quotes endpoint - this refers to the creation of a stored quote in MachShip and does not generate prices.
Please refer to the "Routes" section of our API documentation for further technical details.
Return Routes allows you to specify key consignment details in a variety of ways.
A company in MachShip refers to a business unit that has been setup inside your MachShip account and typically relates to a warehouse.
For further information on companies and how they work, please refer to our article on the topic here.
Different companies have different carriers and accounts attached, so it is important to ensure you are appending the correct companyID in your request, or you may get different carriers/services showing if you have such a setup.
If no company ID is provided, the company that your user token is under will be used to return routes.
A list of company ids can be ontained from /apiv2/companies/getAll.
{
"...": "...",
"companyId": 9999,
"...": "..."
}MachShip offers the following ways to specify the pickup (from) and delivery (to) locations for the consignment:
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.
Example of using suburb and postcodes to specify the pickup and delivery suburbs:
{
"...": "...",
"fromLocation": {
"suburb": "Melbourne",
"postcode": "3000"
},
"toLocation": {
"suburb": "Sydney",
"postcode": "2000"
},
"...": "..."
}Note, if you have the data available it is advisable to include the to and from address line as some carriers validate this when doing a pricing request via their API - so including it will ensure rates are as accurate as possible for all carriers.
Mapping the address in would look like:
{
"...": "...",
"fromAddressLine1": "5 Main Road",
"fromLocation": {
"suburb": "Melbourne",
"postcode": "3000"
},
"toAddressLine1": "1 Smith St",
"toLocation": {
"suburb": "Sydney",
"postcode": "2000"
},
"...": "..."
}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 endpoint.
{
"...": "...",
"fromCompanyLocationId": 1234,
"toCompanyLocationId": 5346,
"...": "..."
}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,
"...": "..."
}It is common when using the generate routes endpoint to use a mixture of methods to define locations - specifically, it's common to use a saved location as the from location, and a suburb/postcode as the to location.
This would appear like so:
{
"...": "...",
"fromLocationId": 5002,
"toLocation": {
"suburb": "Sydney",
"postcode": "2000"
},
"...": "..."
}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"
}
]
}MachShip allows you to specify the dispatch date and time of the consignment. The dispatch 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 Dispatch DateTime that has been provided. If you provide a Dispatch DateTime that is in the past, MachShip will default the dispatch DateTime to NOW. If no Dispatch DateTime is provided, MachShip will default to NOW. Dispatch date can be specified in two ways, and only one of them should be provided:
"dispatchDateTimeUtc": "yyyy-MM-ddThh:mm:ss.000Z""dispatchDateTimeLocal": "yyyy-MM-ddThh:mm:ss.000Z"If you provide both UTC and local time, UTC time will be used.
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:
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.
Items can be provided per request by specifying the following properties:
{
"...": "...",
"items": [
{
"itemType": "Carton",
"name": "test",
"sku": "test",
"quantity": 1,
"height": 10,
"weight": 10,
"length": 10,
"width": 10
}
],
"...": "..."
}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 or SKU. 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"
}
]
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": [
{
"sku":"PALLET-A",
"quantity":2,
"height":100,
"weight":150
}
]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 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 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 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 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]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
}
]
}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:
{
"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
}{
"object": null,
"errors": [
{
"validationType": "Error",
"memberNames": [],
"errorMessage": "From Location is invalid"
}
]
}If services are not being returned, please check the following limitations:
For further documentation on the potential errors responses, see this article - Common API Error Responses.
If all of these conditions have been met, you can contact either the account holder or the MachShip support team at clientintegrations@machship.com and we can help you diagnose any possible issues.