A consignment is a comprehensive description of a shipping job, including:
What a consignment is not:
A pending consignment is a draft consignment that is partially completed, does not yet have a consignment id and is likely missing some key information.
For information about pending consignments, including creation and management, see our Pending Consignments Guide.
Note: The fields described in this article apply to both full and pending consignments, but are optional for pending consignments. This allows you to create draft shipments with partial information that can be completed later.
When creating a consignment via the API, you would be implementing one of two standard workflows:
Workflow #1: Routes Request, Then Create
/apiv2/routes/returnRoutes endpoint to display to your user, or your system to handleWorkflow #2: Direct Creation
To create a consignment, you'll need to send a POST request to:
POST /apiv2/consignments/createConsignmentIf you're sending dangerous goods, international consignments or will be providing your own barcodes, you would use:
POST /apiv2/consignments/createConsignmentwithComplexItemsNote, you do not have to use both endpoints if you're sending both dangerous goods and regular consignments - you can use the complex endpoint for both.
A company in MachShip refers to a business unit that has been setup inside your MachShip account and typically relates to a warehouse. If you're working with multiple companies in MachShip, you can specify which company this consignment should be associated with:
{
"companyId": 9999
}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 consignment will be associated with the company of the user making the API request. A list of company ids can be obtained from /apiv2/companies/getAll.
For further information regarding company ids, refer to our fundamentals article here.
When creating a consignment, you must provide full address details for both pickup and delivery locations. MachShip offers several ways to specify these locations:
Full Address Details Provide complete address information directly in the request:
{
"fromName": "My Warehouse",
"fromContact": "John Doe",
"fromPhone": "1234567890",
"fromEmail": "john@example.com",
"fromAddressLine1": "123 Warehouse St",
"fromAddressLine2": "Unit 4",
"fromLocation": {
"suburb": "Melbourne",
"postcode": "3000"
},
"toName": "Customer's House",
"toContact": "Jane Smith",
"toPhone": "9876543210",
"toEmail": "jane@customer.com",
"toAddressLine1": "456 Customer Ave",
"toAddressLine2": "Apt 7",
"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 by providing the id of the appropriate saved company location:
{
"fromCompanyLocationId": 1234,
"toCompanyLocationId": 5678
}Note that fromCompanyLocationId and toCompanyLocationId represent full addresses, not just suburb and postcode. Saved company location IDs can be retrieved via our /apiv2/companyLocations endpoint.
{
"fromCompanyLocationId": 1234,
"toName": "Customer's House",
"toContact": "Jane Smith",
"toPhone": "9876543210",
"toEmail": "jane@customer.com",
"toAddressLine1": "456 Customer Ave",
"toAddressLine2": "Apt 7",
"toLocation": {
"suburb": "Sydney",
"postcode": "2000"
}
}This field allows you to provide any specific instructions for the carrier regarding the delivery. For example, you might include instructions like "leave at front door" or "call before delivery".
You can specify which carrier, carrier account, and service should be used for this consignment. These details are typically taken from the route you selected in step 2 of the standard workflow.
The default behaviour is for MachShip to choose the cheapest available carrier and service given the goods being sent.
In practice this means:
The account fields are typically not required unless you've got multiple rate cards linked to your company.
{
"carrierId": 11,
"carrierAccountId": 456,
"companyCarrierAccountId": 789,
"carrierServiceId": 123
}If you'd like to get a list of the carrier and service Ids on your account, you can do so using GET /apiv2/companies/getAvailableCarriersAccountsAndServices.
If you don't know which carrier to use, you can let MachShip select either the "cheapest" or the "fastest" option:
{
"defaultRouteSelection": "cheapest"
}Note: You must either provide the Default Route Selection or at minimum the CarrierId when creating a consignment.
You can provide up to 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": "PO-12345",
"customerReference2": "INT-67890"
}MachShip allows you to specify when the consignment should be dispatched. This is particularly useful for planning future shipments. 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 shipping options 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.
There are several other optional parameters you can include in your request:
questionIds: Flags that will include groups of surcharges, or trigger carrier restrictions.Common questionIds: 7 - Hydraulic Tailgate required 8 - Crane Truck required 13 - Is residential delivery 14 - Authorised to leave - note, additional options required for ATL documented here. 36 - Hand unload required
//for residential
"questionIds": [
"13"
]
//for residential AND tailgate
"questionIds": [
"13",
"7",
]printerToken: For use with the MachShip Printing Application, allowing you to target a specific printer with your request.Printer tokens are discuss//TBD
sendingTrackingEmail: Set to true if you want to send a tracking email (ASN) to the clientcustomValues: For carrier-specific integration optionsreceiverAccountCode or receiverAccountId: For receiver-pays consignmentsstaffMemberName: To record which team member generated the consignmentdgsDeclaration: Set to true if the consignment contains dangerous goodsWhen it comes to creating consignments or generating routes, one of the most crucial pieces of information you'll need to provide is the details of the items being shipped. Let's dive into how you can work with items in MachShip.
The size, weight, and type of your items can affect which carriers are available, what services can be used, and of course, the price of shipping.
MachShip offers you flexibility in how you specify items. You have two main options:
Let's look at each of these methods in more detail.
When you're specifying item details directly, you'll need to provide several pieces of information for each item. Here's what you need to know:
Item Type (required): This describes the kind of packaging you're using. MachShip supports a wide range of item types, including 'Carton', 'Skid', 'Pallet', 'Crate', 'Satchel', and many more. Choose the one that best describes your item.
Name (required): This is a brief description of the item. It helps you and others quickly identify what's being shipped.
SKU (optional): If you use Stock Keeping Units in your system, you can include them here for easy reference.
Quantity (required): This is how many of this particular item you're shipping. For example, if you're sending 5 identical cartons, you'd set the quantity to 5.
Weight (required): The weight of the item in kilograms.
Dimensions (required): You'll need to provide the length, width, and height of the item, all in centimeters.
Pallet Spaces (optional): This is only relevant if you have pricing related to pallet spaces. It indicates how many pallet spaces this item occupies. If it's not supplied, we simply count the pallets based on the quantity and the item type.
Here's an example of how you might specify an item in your JSON request:
{
"items": [
{
"itemType": "Carton",
"name": "test",
"sku": "test",
"quantity": 1,
"height": 10,
"weight": 10,
"length": 10,
"width": 10
}
]
}If you frequently ship the same types of items, or your system allows you to specify standard packages, MachShip allows you to save these items for easy reuse. This can save you time and reduce errors when creating consignments. You can reference a saved item in two ways:
Here are examples of each:
// Accessing a saved item by ID (not very common)
"items": [
{
"companyItemId":999
}
]
// Accessing a saved item by SKU (most common)
"items": [
{
"sku":"test"
}
]One of the great features of using saved items is that you can still override specific properties if needed. For example, if you want to use a saved item but change the quantity and weight for this particular consignment, you can do so like this:
"items": [
{
"sku":"BIG-CHAIR",
"quantity":5,
"weight":15
}
]In this case, the quantity will be set to 5 and the weight to 15kg, while all other properties will be taken from the saved item.
Let's look at a couple of examples to see how you might use items when requesting routes or creating consignments.
Example 1: Providing all item details
{
"fromCompanyLocationId": 1234,
"toName": "Customer's House",
"toContact": "Jane Smith",
"toPhone": "9876543210",
"toEmail": "jane@customer.com",
"toAddressLine1": "456 Customer Ave",
"toAddressLine2": "Apt 7",
"toLocation": {
"suburb": "Sydney",
"postcode": "2000"
},
"items": [
{
"itemType": "Carton",
"name": "test",
"quantity": 1,
"height": 10,
"weight": 10,
"length": 10,
"width": 10
}
]
}Example 2: Using saved items
{
"fromCompanyLocationId": 1234,
"toName": "Customer's House",
"toContact": "Jane Smith",
"toPhone": "9876543210",
"toEmail": "jane@customer.com",
"toAddressLine1": "456 Customer Ave",
"toAddressLine2": "Apt 7",
"toLocation": {
"suburb": "Sydney",
"postcode": "2000"
},
"items": [
{
"sku":"BIG-CHAIR",
"quantity":5,
"weight":15
},
{
"companyItemId":999
}
]
}In this example, we're using two different saved items, each referenced in a different way (by SKU, and by ID).
Remember, whether you're specifying items directly or using saved items, the goal is to provide MachShip with accurate information about what you're shipping. This ensures you get the most accurate pricing and routing options for your consignment.
Once you've prepared all the necessary information, including your items, you're ready to send your request. Here some examples of what a complete request might look like
Carrier pre-selected, full carton details, full from and to locations
{
"items": [
{
"itemType": "Carton",
"name": "test",
"quantity": 1,
"height": 10,
"weight": 10,
"length": 10,
"width": 10
}
],
"dgsDeclaration": false,
//carrier and service pre-selected
"carrierId": 11,
"carrierServiceId": 123,
"carrierAccountId": 456,
"companyCarrierAccountId": 789,
"customerReference": "PO-12345",
"customerReference2": "INT-67890"
"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"
}Cheapest option, using saved item details, stored from location and full to locations
{
"items": [
{
"sku": "STANDARD-120-PALLET",
"quantity": 1,
"weight": 150,
}
],
"dgsDeclaration": false,
"fromCompanyLocationId": 123,
"customerReference": "PO-12345",
"customerReference2": "INT-67890",
"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"
}For complex consignments involving dangerous goods or international shipments, you would use the complex items endpoint. The structure remains largely the same, but with additional fields for dangerous goods declarations or customs information.
For further information on these, see:
DG Consignment, cheapest option, using saved item details, stored from location and full to locations
{
"items": [
{
"itemType": "Carton",
"name": "Test Carton",
"sku": "CART",
"quantity": 1,
"standardItem": {
"height": 25,
"weight": 5,
"length": 20,
"width": 20
},
"consignmentItemDgItems": [
{
"unNumber": 1263,
"packingGroup": 3,
"containerType": 1,
"aggregateQuantity": 20,
"isAggregateQuantityWeight": false,
"numberOfContainers": 1,
"isMarinePollutant": true,
"isTemperatureControlled": false,
"dgClassType": 5
}
]
}
],
"dgsDeclaration": true,
"fromCompanyLocationId": 123,
"customerReference": "PO-12345",
"customerReference2": "INT-67890",
"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"
}If your consignment is created successfully, MachShip will return a response containing key information about the new consignment. Here's what you can expect to receive:
id: A unique identifier for the consignment. Store this in your system for future API calls related to this consignment.consignmentNumber: This is the id with an "MS" prefix. It's used in MachShip's UI and is the main reference sent to the carrier.carrierConsignmentId: This is the reference used by the carrier.status: Most new consignments will have a status of "Unmanifested", meaning they exist in MachShip but haven't been transmitted to the carrier yet. Some carriers and accounts are configured to automatically manifest on creation, in which case the status would be "Manifested".consignmentTotal: This provides a breakdown of the consignment's pricing, including surcharges.items: This section provides details about the items in the consignment, including dimensions, weights, references (barcode data), and item contents.Here's an example of what the response might look like:
{
"object": {
"carrierConsignmentId": "ABC000123456",
"status": {
"id": 2,
"name": "Unmanifested",
"description": "Unmanifested"
},
"trackingPageAccessToken": "<tracking page token>",
"consignmentTotal": {
"totalSellPrice": 20.30691,
"totalCostPrice": 0.00000,
"totalBaseSellPrice": 16.78257,
"totalBaseCostPrice": 0.00000,
"totalTaxSellPrice": 1.84608,
"totalTaxCostPrice": 0.00000,
"sellFuelLevyPrice": 1.6782,
"consignmentRouteSellPrice": 16.78257,
"totalSellBeforeTax": 18.46083
},
"items": [
{
"itemType": "Carton",
"name": "test",
"quantity": 1,
"height": 10.00000,
"weight": 10.00000,
"length": 10.00000,
"width": 10.00000,
"references": [
"ABC000123456001"
]
}
],
"id": 123456,
"consignmentNumber": "MS00123456",
"despatchDateLocal": "2018-07-02T09:00:00",
"despatchDateUtc": "2018-07-01T23:00:00",
"etaLocal": "2018-07-04T17:00:00",
"etaUtc": "2018-07-04T07:00:00",
"carrier": {
"id": 11,
"name": "TNT Express",
"abbreviation": "TNT",
"displayName": "TNT Express (TNT)"
},
"carrierService": {
"id": 123,
"name": "Road Express",
"abbreviation": "76",
"displayName": "Road Express (76)"
},
"isTest": false
},
"errors": []
}When working with any API, encountering errors is a natural part of the development process. MachShip's API is designed to provide clear, meaningful error messages to help you quickly identify and resolve issues. Let's dive into how MachShip handles errors and some common error messages you might encounter.
When something goes wrong with your API call, MachShip will return a response that looks like this:
{
"object": null,
"errors": [
{
"validationType": "Error",
"memberNames": [
],
"errorMessage": "ConsignmentIds are required"
}
]
}The errors array contains one or more error objects, each with a validationType, memberNames (which is often empty), and an errorMessage. The errorMessage is the key piece of information that will help you understand what went wrong.
For documentation on the potential errors responses and their meaning, see this article - Common API Error Responses.
When you encounter an error:
Read the error message carefully: MachShip tries to make error messages as descriptive as possible to point you in the right direction.
Check your request data: Many errors are caused by missing or invalid data. Double-check that you're providing all required fields and that the data formats are correct.
Verify your permissions: If you're getting access errors, make sure your API key has the necessary permissions for the operation you're trying to perform.
Consult the documentation: If you're unsure about a particular field or parameter, refer back to the API documentation for clarification.
Test in smaller steps: If you're having trouble with a complex request, try breaking it down into smaller parts to isolate the issue.
Remember, encountering errors is a normal part of working with any API. By understanding these common error messages and following good troubleshooting practices, you'll be well-equipped to handle any issues that arise when working with the MachShip API.
For more information about working with consignments in MachShip, check out these related articles: