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!