The objective of this getting started guide is to provide you a quick summary of key knowledge you will need to build a successful integration with MachShip and understand the options available.
The target for this guide is developers and IT teams that are looking to create consignments, generate prices and integrate their internal systems with MachShip - this guide is NOT for carriers looking to be integrated with MachShip.
If you are a carrier looking to be integrated, or have questions about our integration with your platform, please reach out to carriers@support.machship.com for further information.
An organisation in MachShip is the billable account that all companies exist under.
Any consignment created on any company under an organisation is billed to that organisation.
Data, consignments or information is never shared, and cannot be accessed, across organisations.
Organisations are rarely a factor when it comes to your integration as they are typically only connected to a single organisation.
MachShip refers to the different business units that are setup under an organisations account in our platform as companies, and these companies exist in a tree structure with multiple levels.
Companies are very imporant to integrations, as the company allocated to a consignment affects who can and cannot see that consignment.
A common tree structure for a MachShip account would be:
In this structure, Surefoot enterprises is the parent company, and Surefoot Melbourne and Sydney would be child companies.
There are no limitations to the number of levels you have in the tree structure.
When being used by brokers, it's not uncommon for accounts to have 4-5 levels of depth in the tree structure.
The reason for using the tree structure on a MachShip account is that it allows the account holder to control:
Based on this, while the companies that are setup tend to be represent locations or warehouses, they are not always so.
For example, another common account structure is:
In this case, the example company trades as multiple brands, that are dispatched out of two warehouse locations.
The above setup would allow users added to the VIC and NSW companies to dispatch for both of the brands (Big Widget and Sallys Flowers) underneath them, while not being able to access the other warehouse consignments.
From an integration perspective, companies are important when:
How companies are allocated when creating or routing consignments differs based on integration method.
For further info, see our specific API and flat file documentation.
Inheritance is a time-saving feature used throughout MachShip that allows you to make addresses, items, dangerous goods and carrier accounts visible to child companies of the company they are setup on.
Let's say you have an address book for all of your customers delivery addresses - and you have the following account setup:
If you were to upload this address book under Surefoot enterprises, by default, your two warehouses would not be able to see or access the addresses in that address book. It's locked so only users logged into Surefoot Enterprises (the parent and owner of the addresses) could see them.
Normally this would mean you would need to upload the address book to both of these locations - which is time consuming, and they could quickly become mis-aligned.
Instead, on the "Surefoot Enterprises" company, you can enable "Inherit Locations".
With this enabled, the children underneath can access the parents locations.
{danger.fa-close} Do not enable inheritance without first considering what the child will be able to see. For example, if you have setup 3PLs as child companies so they can dispatch on your behalf, you likely do NOT want them to see your entire customer address book. In those instances, you would not enable inheritance, but simply upload or create a few addresses on the child company instead.
When a user is created in MachShip, they are allocated to a company and they can see all consignments on their company and below in the structure.
Let's use this structure as an example:
Based on this:
Each user has a role, and that role has certain permissions attached to it that controls what a user can see and do inside the MachShip platform.
Here are two example roles to demonstrate:
Users have a "test mode setting" field which controls whether a user creates or can view test consignments.
This field has the following options:
If this setting is set to "User is in test mode", then the user, and any attached API keys should be considered as the "sandbox".
A test mode user will only ever create test consignments, which are not billed, and never go through to the carrier when manifested.
This is the setting that is used when building your integration to ensure the consignments you create are not sent to carriers.
API keys are created on users in MachShip, and inherit that users company access, permissions (role) and test mode setting.
A user can have multiple keys created against them, and tokens can also be revoked.
For the steps to create an API key, view our guide here.
In the context of integrations, users and their roles are applicable as your API key is linked to a user and that users test mode and permissions affect what your token is able to see and do via our API.
It is common for a developer to be given a token with more restricted permissions than are required, or for the token to be linked to a company that is not the target company for the integration. If you try and query a listed endpoint and get a permissions issue, it is likely related to the users role, or company.
A carrier in MachShip refers to a shipping provider, for example Australia Post.
Carriers offer different services for different types of freight, with different delivery speeds.
These services are unique for every carrier, with common descriptions being "Express", "Overnight", "Same Day" or "Tailgate Delivery".
Other services are referred to by the size of the vehicle, for example, "1 Tonne Truck".
When a MachShip customer wants to connect their MachShip account to a given carrier, they use a "Carrier Account."
The carrier account contains details such as a customer's account number with that carrier, shipping rates, usernames and passwords, carrier reference pools, and other essential data we need to store to create and price a shipment with that carrier.
Without a carrier account, Machship would be unable to create consignments for a carrier or price those consignments.
Carrier accounts are typically setup against the top most level company inside MachShip, then a company Carrier Account is created which links the carrier account to a given company.
This linkage, known as a company carrier account, allows a MachShip customer to create several carrier accounts once, then link specific accounts to specific dispatch companies where they want to use that carrier, and provide some company specific configuration as required.
This objective of this primary carrier account setup, with multiple linked company carrier accounts, prevents duplication of carrier account setup and carrier account configuration and doubling up of key references with that carrier.
When MachShip integrates with a carrier, there are two areas of integration:
For carriers that do not have programmatic routing & pricing options available, we load those carriers rate cards and consignment pricing methods into MachShip, and the pricing is generated inside the MachShip platform against the carrier account.
We have three different integration types with carriers:
The majority of carriers in MachShip are integrated, with a smaller selection being generic.
Common considerations relating to carriers and integrations are:
The MachShip platform has 3 types of consignments that you may opt to create.
Pending consignments are draft consignments that are partially completed and not yet allocated a carrier consignment ID.
The primary use of a pending consignment is to speed up despatch and prevent data entry issues by providing a dispatcher with a mostly filled-out consignment, where they only have to add a few final details before creating the consignment.
While a full consignment in MachShip must be 100% complete with a valid from and to address, all of the package details and a carrier and service selected - a pending consignment is not fully validated and can be partially completed or filled out, ready for a despatcher to finalise.
The primary reasons you would create a pending consignment over a regular consignment are:
By using a pending consignment, you can prefill most of the information and then have the user do the last part before getting the labels.
A consignment is a finalised shipment with a carrier, service, packages and a carrier consignment id allocated.
A consignment is created in an "unmanifested" status, which means it exists, but the carrier has not yet notified of the job.
Consignments are typically manifested in bulk to the carrier by a user in MachShip, notifying the carrier about the consignments and their details.
A benign consignment is a consignment that is created in MachShip purely for billing or consignment tracking purposes.
The consignment is not passed to the carrier from our system - it's purely there for tracking and reconciliation reasosn.
No labels are created or generated for these types of consignments.
These types of consignments are created relatively rarely.
Consignments in MachShip have 3 key stages, with one optional proceeding stage:
Manifesting is the critical step in the consignment lifecycle where the data is sent from MachShip to the carrier.
Manifesting is typically done once per day, per carrier, per warehouse via the MachShip UI by selecting a group of unmanifested consignments and clicking "manifest", triggering a data send to a carrier.
Once manifesting has been done, the carriers consignment status will begin to reflect in MachShip, and the labels will be scannable by the carrier.
Once a consignment has been manifested, it is no longer editable - any cancellations need to be processed directly with the carrier.
On manifest, a manifest document can be sent to an A4 printer that contains details of all consignments manifested.
MachShip has the capability to "auto-manifest" consignments the instant they are created.
Typically this method is only used in two instances:
The downside of auto-manifesting is that consignments cannot be merged together or editted in anyway once manifesting has occured.
This can be enabled on a per carrier and per service basis.
Below is a current list of status in the MachShip system, followed by their status ID in MachShip.
Note, not all status are used by all carriers, and carriers do sometimes "skip" statuses in the process of delivering consignments.
Most Common Status Flow
Remaining Less Common Statuses
Here we will outline the key identifiers that you can use to identify consignments in our platform.
id - example: 543210
The pending consignment id is a unique identifier for a pending consignment, with no two pending consignments having the same id.
This id is useful to store if:
Note, this id is not the same as a consignment ID, and if a pending consignment is turned into a consignment, the id will be different on the consignment than it was on the pending as they are different entities.
consignmentNumber - example: PC543210
The pending consignment consignmentNumber is the consignment ID with a PC prefix.
This is used to display in the MachShip UI.
CustomerReference - example: SO-12345
The first reference field on a consignment, that can be used to store any ID or value you require.
The field displays on most screens in MachShip, is searchable across the platform and shows in all reports and on most carrier labels.
Customer reference carries over to a consignment when it is created from a pending.
CustomerReference2 - example: PO-54321
The second reference field on a consignment, that can be used to store any ID or value you require.
Displays on some screens in MachShip, and all reports. Does not typically show on labels.
Customer reference 2 carries over to a consignment when it is created from a pending.
id - example: 12345678
The consignment id is a unique number used to identify a consignment in our database. No two records would ever have the same id.
This id is useful when interacting with our API, as most endpoints for create, edit, update and manifest require this value.
consignmentNumber - example: MS12345678
The consignments id, with an MS prefix.
carrierConsignmentId - example: ACME1234567
The carrier consignment id is the unique identifier that an allocated carrier would use to reference this consignment once it has been manifested with them.
Carrier consignment ids are typically managed in MachShip on a per carrier account basis based on the carriers preference.
They are typically made up of a prefix for that account (ABC), and a carrier reference pull, or series of numbers such us 000000 to 999999.
The end outcome is a carrier consignment id like ABC000123.
Given multiple carriers could have the same prefix and carrier pools, it is possible, and not unusual for two different consignments to have the same Carrier Consignment Id.
In addition, some carriers do not have MachShip manage the carrier consignment id, and instead they are allocated to the consignment from the carrier programtically at the point the consignment is created.
trackingPageAccessToken - example: ji342oi3jcnoiew
The unique token is allocated to a consignment when it is created, and can be used to generate a unique tracking link for the consignment.
To generate a tracking url from this, you simply append it to our standard base URL https://mship.io/v2/.
For example, https://mship.io/v2/ji342oi3jcnoiew
Note, a carrier consignment ID cannot be used to generate a tracking page link, as they are not always unique across carriers in our system.
consignmentItemReferences - example: ACME12345670001
The consignment item references are the unique strings that are to be applied as barcodes on each label inside a consignment.
Typically consignment item references contain the carrier consignment id, followed by a count or increment for each label.
For example, a consignment (ACME1234567) with 3 items would need 3 labels, and the following consignment item references may be generated: ACME12345670001 ACME12345670002 ACME12345670003
Consignment item references tend to be generated by MachShip, provided MachShip is going to be generating the labels.
Clients that want to use SSCCs can apply them as the consignment item references during consignment creation via our API - provided the carrier can accept SSCCs or externally provided barcodes (not all do).
CustomerReference - example: SO-12345
The first reference field on a consignment, that can be used to store any ID or value you require.
The field displays on most screens in MachShip, is searchable across the platform and shows in all reports and on most carrier labels.
CustomerReference2 - example: PO-54321
The second reference field on a consignment, that can be used to store any ID or value you require.
Displays on some screens in MachShip, and all reports. Does not typically show on labels.
When creating a consignment in MachShip for either dispatch or pricing, MachShip requires the items (packages) that will be sent for that consignment in order to price it and select an appropriate carrier.
A consignment can have multiple items (packages) going to the same receiver on the same consignment, and one label is printed per item.
While a consignments items are occassionally the same as the products being shipped to a customer, it is not common, and generally products should not be mapped as items.
This is because when a customer orders multiple products, most customers tend to pack those products down into a satchel, carton or pallet prior to shipping.
When we refer to items in MachShip, we are talking about the final shippable items - not the contents of those packages, or the products being purchased.
It is the final shippable units weights and dimensions that affect the price and carrier service availability - and that is the information we need.
For example:
The only time this is not the case is if your goods are pre-packaged, and sent as they are. This is common in a 3PL environment.
In that case, then the product package weights and dimensions are you shipping weights and dimensions.
All items (packages) in MachShip must be allocated a length, width and height in CM.
We cannot use volume as the basis for items as some carriers have length based surcharges, and service restrictions based on item dimensions.
If you are forced to use volume, please read this article here on best practice when converting that to package dimensions.
Item type refers to the type of packaging that applies to this given item.
Common item types are Carton, Satchel, Pallet, Skid - but there are 30 plus item types available.
When creating items, you need to specify how many of this item you are going to send - this is the item quantity.
If you have multiple items of the same size and type, you can simply increment this value to get an additional label for each item.
If you have multiple items of different types or sizes, they would be different lines with their own quantity.
For example, if you have the following items:
These could be applied as follows:
When creating a consignment in MachShip, and adding an item (package), you can specify the contents of that package as "Item Contents".
This set of fields allows you to specify the skus, names, quantity and dollar value of the products or goods inside that package.
When shipping internationally, these fields are requried for customs declaration. They are not required for domestic shipping.
MachShip has an area that allows you to create, edit, upload and manage your commonly used package sizes.
In this area, you can create a record of the following information:
Then, when creating a consignment, you can simply apply the SKU and a qty and it will prefill out the missing information.
These items can be used when interacting with the MachShip UI, and when creating consignments via our API.
It is common to use this area to store your most frequently used packages, and set the qty and weight values when creating a consignment.
For example, you could specify these in your item master:
You could then send a request to apply these items to your consignment as follows:
And it would prefill the consignment as:
MachShip has several types of documents available in our platform that relate to consignments and manifests.
The most commonly used documents in our platform are:
Less commonly used documents in the platform include:
Item labels are the most commonly interacted with via our API, and are available once a consignment is created as a multi-page PDF.
MachShip also has the ability to send the labels for a given consignment directly to a targetting printer using our printer application.
This avoids the requirement for you to get the labels from us, and send them to the printer yourself and is lower latency.
Here is a glossary of key terms you may read in this documentation and what they mean: