How to Create Consignments Via The API With Your Own Consignment Ids and Item References

How to Create Consignments Via The API With Your Own Consignment Ids and Item References

The following article will cover how to create a consignment via the API when you are delegating your own carrier consignment numbers and item references/barcodes.
This is an advanced topic, and requires the generation of fully compliant carrier consignment ids and item references - something which Machship typically generates for a consignment.
Note:
  1. This article will not cover the basics of creating consignments. An article covering consignment creation in depth can be found here: A guide to creating Consignments via the API
  2. There is a difference in the item object on the endpoint in that article and that discussed below - this is the difference between the createConsignment and the createConsignmentwithComplexItems endpoints, with the latter allowing the setting of additional fields including item references.

Creating Your Consignment

When you are looking to generate your own consignment numbers and item references/barcodes and pass them into Machship you must use the following endpoint to create consignments:
POST /apiv2/consignments/createConsignmentwithComplexItems
The full schema of this endpoint is available in our swagger documentation here.
When using this endpoint, we have two undocumented fields you will need to add to your payload:
  1. carrierConsignmentId - sitting at the parent level, this value is the carrier consignment ID, which must follow the carrier specifications including any relevant prefixes that you have generated for this consignment.
  2. items.consignmentItemReferences.carrierItemReference - This field sits inside an array on the items object, inside the consignmentItemReferences array object and is the barcode that will be used on the label. This barcode must follow the carrier specifications.
    1. You must set one reference for every quantity on the given line.
    An example of how these would be set is:
    2. {
    3.   "carrierConsignmentId": "2657628002",
    4.   "carrierId": "446",
    5.   //all other consignment data as per schema
    6.   "items": [
    7.     {
    8.       "name": "Pallet",
    9.       "quantity": 2,
    10.       "itemType": "Pallet",
    11.       "standardItem": {
    12.         "weight": 270,
    13.         "length": "117",
    14.         "height": "110",
    15.         "width": "117"
    16.       },
    17.       "consignmentItemReferences": [
    18.         {
    19.           "carrierItemReference": "(00)393168610029113320"
    20.         },
    21.         {
    22.           "carrierItemReference": "(00)393168610029113321"
    23.         }
    24.       ]
    25.     },
    26.     {
    27.       "name": "Pallet",
    28.       "quantity": 1,
    29.       "itemType": "Pallet",
    30.       "standardItem": {
    31.         "weight": 170,
    32.         "length": "110",
    33.         "height": "110",
    34.         "width": "110"
    35.       },
    36.       "consignmentItemReferences": [
    37.         {
    38.           "carrierItemReference": "(00)393168610029113322"
    39.         }
    40.       ]
    41.     }
    42.   ]
    43. }
    After you POST this data to the specified endpoint, check the response.
    If you're carrierConsignmentId and carrierItemReference match what you sent in, you've successfully delegated the references.
    That's it - you're done!

      • Related Articles

      • A guide to editing Complex Consignments Via The API when setting Item References

        The following article will cover how to edit a consignment via the API when you are delegating your own carrier consignment numbers and item references/barcodes. The main use cases for an edit workflow include: Adjusting item weights/dimensions ...

      • How to Edit Consignments Via The API

        The following article will cover how to edit a consignment via the API. The main use cases for an edit workflow include: Adjusting item weights/dimensions Adding new items Removing items Note: This article will not cover the basics of creating ...

      • A guide to creating Consignments via the API

        Creating consignments is at the core of MachShip's functionality. Consignments describe everything related to a job that needs to travel including the pick-up location, delivery location and the individual items themselves. On top of this, a ...

      • A guide to creating Dangerous Goods Consignments via the API

        Creating consignments is at the core of MachShip's functionality. Consignments describe everything related to a job that needs to travel including the pick-up location, delivery location and the individual items themselves. On top of this, a ...

      • Creating Pending Consignments using the MachShip API

        One of the key efficiency targets for any business is to cut out manual tasks and automate as many processes as possible. In the Supply Chain and Logistics sector, a key blocker to this achievement is having prior knowledge of the final shipping ...