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 / Pickup Country
- Delivery suburb and postcode / Delivery Country
- Items being sent
- Desired despatch date and time
MachShip uses its pricing and routing engine to determine which carriers and services are available 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, postcode, country
- The service/your rates do not travel to the delivery suburb, postcode, country
- 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 International Routes and Prices from Machship
All these details must be provided to/apiv2/routes/returnrouteswithcomplexitems for MachShip to return your valid despatch options. Please look at our API documentation for additional 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 with Complex Items Parameters
Return Routes allow 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)
- Country, Province, City and Postcode Combination
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 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. Note that when consigning internationally you can only provide either the pickup or delivery location as an international location
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 optional as routing will also validate the entered suburbs for you.
Example of using suburbs 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"
}
]
}
International Country, City, Province and Postcode Combination
In order to define a route as International a 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 fromCountryCode2
for an Import or
one of either the internationalToCity, internationalToPostcode, internationalToProvinceand toCountryCode2
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",
"fromCountryCode2": "USA",
...
}
Items
MachShip offers multiple ways to specify the items for the consignment. To return international prices, at least 1 item must be supplied along with valid customs information, 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 just specify the item details as you requested.
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": "string",
"sku": "string",
"quantity": 0,
"standardItem": {
"height": 0,
"weight": 0,
"length": 0,
"width": 0
} ...
}
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
}
]
Item Contents
In order to allow for a smooth transfer through customs, it is critical that you supply the customs fields in the item contents section - note 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",
"countryOfManufacture": {
"code2": "NZL"
}
}
]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 ask about TNT routes. To do this, you would set carriers to [11]. All routes will be returned if this is not included in the request.
{
...
"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 Complex Routes Example
Request Example 1: Suburbs and item details provided.
Example Item Content of TShirts manufactured in NZ
{
"fromLocation": {
"suburb": "melbourne",
"postcode": "3000"
},
"isInternational": true,
"internationalToCity": "Beverly Hills",
"internationalToPostcode": "90210",
"internationalToProvince": "CA",
"toCountryCode": "USA",
"items": [{
"itemType": "carton",
"name": "test Carton",
"sku": "string",
"quantity": 1,
"standardItem": {
"height": 10,
"weight": 1,
"length": 10,
"width": 10
},
"consignmentItemContents": [{
"description": "Tshirts",
"reference1": "INV123456",
"reference2": "OR9876",
"reference3": "PO1234",
"quantity": 5,
"dollarValue": 5,
"ciMarksAndNumbers": null,
"harmonizedCode": "61091000 ",
"partNumber": null,
"purpose": "Sale",
"countryOfManufacture": {
"code3": "NZL"
}
}]
}]
}
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"
}
]
"isInternational": true
},
"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.
Comments
0 comments
Please sign in to leave a comment.