Unmanifested Consignment Workflow
Overview
The objective of this guide is to help you to implement an unmanifested consignment workflow with MachShip.
The primary reasons you would use this workflow if you're wanting a "touchless" integration where your team don't need to touch MachShip to consign and get labels.
Workflow Demo & Diagram
Here is a summary of the most common workflow:
- Shipment/order created in your system
- Data is sent to MachShip - via one of our supported integration methods - you can route cheapest, fastest, or preselect a carrier and/or service
- Labels print out - based on a printing rule that has been setup in MachShip
- Consignments Are Manifested - typically done in bulk on a per carrier basis in MachShip
If you'd like to display carrier service options, ETAs and prices to your users, there is a slightly different workflow.
In this workflow, you must use our API, and make a request to us for carrier service options and prices first prior to creating your consignments:
- Shipment/order created in your system
- Route Request sent to MachShip - MachShip returns a list of carrier service options, etas and prices that you can display to the user for selection.
- You capture carrier, service and account - based on the users selection, you capture these values and append them to your create consignment payload
- Create Consignment API request sent to MachShip - creating the consignment
- Labels print out - based on a printing rule that has been setup in MachShip
- Consignments Are Manifested - typically done in bulk on a per carrier basis in MachShip
Here is a demo of these workflows in action:
[Add Video Here]
Workflow Implementation
1. Flat File Via Import
MachShip provides flexible methods for importing consignment data into the platform. Whether you need to upload files manually through our web interface or automate the process through folder monitoring, MachShip supports both standard CSV formats and custom file structures through workflow tasks. This guide helps you understand the available options and choose the right approach for your shipping workflow.
For detailed instructions on how to import consignments, see our import guide here.
2. Printer app
Once you've got your file importer setup, you can then automate the pick up of your files using our printer app.
For detailed instructions on how to automate your imports using our printer app, read our printer app import guide here.
3. API Integration
The below examples are API endpoints and requests that you can use as the basis for your integration.
Note, any carrier and service ids, from company location ids and company ids are just an example and will not work if you were to test them in your integration as they are all account specific values. At the bottom of this document is a list of endpoints that allow you to query for these values from your account so you can get the values you should use.
Example 1 - Full From & To Address, Pre-selected Carrier, Full Item Data
POST https://live.machship.com/apiv2/consignments/createConsignment HTTP/1.1
token: <api_token>{
"items": [
{
"itemType": "Carton",
"name": "test",
"quantity": 1,
"height": 10,
"weight": 10,
"length": 10,
"width": 10
}
],
"dgsDeclaration": false,
//pre-selects the carrier and service
"carrierId": 11,
"carrierServiceId": 123,
"carrierAccountId": 456,
"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"
}Example 2 - Stored From Address, Full To Address, No Pre-selected Carrier (Cheapest)
POST https://live.machship.com/apiv2/consignments/createConsignment HTTP/1.1
token: <api_token>{
//the MachShip entity (warehouse and/or brand) to allocate the consignment to
//only required if you have more than one entity
"companyId":"1234",
//a stored address in MachShip
"fromCompanyLocationId": "1638944",
"customerReference":"8855292845",
"customerReference2":"Test00014",
"specialInstructions": "string",
"toName":"The Company",
"toContact":"Mary Jones",
"toPhone":"0422 222 222",
"toAddressLine1":"1212 SMALL AVENUE",
"toLocation":{
"suburb":"CROYDON",
"postcode":"3136"
},
"questionIds": [7,13], //7 is requires tailgate, 13 is residential delivery
"items": [
{
"itemType": "Carton",
"name": "Box 1",
"quantity": 1,
"height": 10,
"weight": 20,
"length": 30,
"width": 40,
}
],
}Example 3 - Route Request, Then Create Request
In this example, we will conduct a two step process:
- Route request - this will return pricing options and validate your create consignment payload
- Create consignment request - this will create the consignment for your pre-determined carrier.
The primary fields on these endpoints are aligned to facilitate easier integration, or sending a similar payload to both - just like in the example below.
POST https://live.machship.com//apiv2/routes/returnroutes HTTP/1.1
token: <api_token>{
//the MachShip entity (warehouse and/or brand) to allocate the consignment to
//only required if you have more than one entity
"companyId":"1234",
//a stored address in MachShip
"fromCompanyLocationId": "1638944",
"customerReference":"8855292845",
"customerReference2":"Test00014",
"specialInstructions": "string",
"toName":"The Company",
"toContact":"Mary Jones",
"toPhone":"0422 222 222",
"toAddressLine1":"1212 SMALL AVENUE",
"toLocation":{
"suburb":"CROYDON",
"postcode":"3136"
},
"questionIds": [7,13], //7 is requires tailgate, 13 is residential delivery
"items": [
{
"itemType": "Carton",
"name": "Box 1",
"quantity": 1,
"height": 10,
"weight": 20,
"length": 30,
"width": 40,
}
],
}Response (abbreviated):
{
"object": {
"routes": [
{
"carrier": {
"id": 11,
"name": "TNT Express",
"abbreviation": "TNT",
"displayName": "TNT Express (TNT)"
},
"carrierService": {
"id": 31678,
"name": "Technology Express",
"abbreviation": "717B",
"displayName": "Technology Express (717B)"
},
"carrierAccount": {
"id": 2139,
"name": "TNT_ADS",
},
"companyCarrierAccountId": 142544,
"consignmentTotal": {
"totalSellPrice": 491.42,
"totalBaseSellPrice": 397.95,
"totalSellBeforeTax": 446.75
},
"despatchOptions": [
{
"despatchDateLocal": "2024-12-20T13:51:57.1909171",
"despatchDateUtc": "2024-12-20T03:51:57.1909171Z",
"etaLocal": "2024-12-23T17:00:00",
"etaUtc": "2024-12-23T07:00:00Z",
}
]
},
{
"carrier": {
"id": 1080,
"name": "Bonds Transport",
"abbreviation": "BONDS",
"displayName": "Bonds Transport (BONDS)"
},
"carrierService": {
"id": 6866,
"name": "Express 4 Tonne Tautliner - Tail Lift",
"abbreviation": "E4TATL",
"displayName": "Express 4 Tonne Tautliner - Tail Lift (E4TATL)"
},
"carrierAccount": {
"id": 81174,
"name": "Bonds Transport",
"carrierId": 1080,
"displayName": "Bonds Transport (Bonds)"
},
"companyCarrierAccountId": 23381,
"consignmentTotal": {
"totalSellPrice": 1157.44,
"totalBaseSellPrice": 865.31,
"totalSellBeforeTax": 1052.22
},
"despatchOptions": [
{
"despatchDateLocal": "2024-12-20T13:51:57.1909171",
"despatchDateUtc": "2024-12-20T03:51:57.1909171Z",
"etaLocal": "2024-12-20T15:51:57.1909171",
"etaUtc": "2024-12-20T05:51:57.1909171Z",
}
]
}
],
"results": null
},
"errors": null
}Based on this response you can present the options to a user to choose from, or apply logic to filter the available options.
From this payload, you will need to note the following values based on the user selection:
- carrier.id
- carrierService.id
- carrierAccount.id
Then, you will proceed to send the same payload to the createConsignment endpoint, but with these values appended.
In this example, I'm going to select the TNT Express - Technology Express service.
POST https://live.machship.com/apiv2/consignments/createConsignment HTTP/1.1
token: <api_token>{
"companyId":"1234",
//a stored address in MachShip
"fromCompanyLocationId": "1638944",
//values taken from route request
"carrierId": 11,
"carrierServiceId": 31678,
"carrierAccountId": 2139,
"customerReference":"8855292845",
"customerReference2":"Test00014",
"specialInstructions": "string",
"toName":"The Company",
"toContact":"Mary Jones",
"toPhone":"0422 222 222",
"toAddressLine1":"1212 SMALL AVENUE",
"toLocation":{
"suburb":"CROYDON",
"postcode":"3136"
},
"questionIds": [7,13], //7 is requires tailgate, 13 is residential delivery
"items": [
{
"itemType": "Carton",
"name": "Box 1",
"quantity": 1,
"height": 10,
"weight": 20,
"length": 30,
"width": 40,
}
],
}The response will include all the details about your newly created consignment, including a carrier consignment id.
Further documentation on the fields available can be found in our documentation here and our full API specification here.
Workflow FAQs
How does label printing work? Typically a printing rule is setup based on a "printerToken" that you would add to your request.
You can setup a rule that says "if the printer token is X, then send the labels to printer Y".
If you have only have one printer in each warehouse, you don't need to use printer tokens, instead you can have a more simplistic printer rule such as: "If the from suburb is X, then send to printer Y".
Please read our guide on label printing here.
How does sending dangerous goods work? If you're sending dangerous goods, you will need to build an API integration, or contact us to build a custom flat file integration.
You can't use the printer app or importer for dangerous goods.
Dangerous goods consignments require the use of the complex consignment endpoint instead of our standard endpoint - along with the addition of DG data.
For details on how to create dangerous goods, read our documentation on the topic here.
How does sending international consignments work? If you're sending international consignments, you will need to include extra information in your payloads around the products inside your packages.
This data is used for duties declartions and related documentation.
For details on how to create international consignments, read our documentation on the topic here.
If I create two consignments for the same customer, can MachShip merge them? In MachShip we refer to this as consolidation - and it can be enabled on a per carrier basis.
For further details on how consolidation works, read our guide on consolidation here.