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

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:
  1. Adjusting item weights/dimensions
  2. Adding new items and references
  3. Removing items and references
Note:
  1. This article will not cover the basics of creating consignments.
    1. An article covering consignment creation in depth can be found here: A guide to creating Consignments via the API
  2. This article is specific to workflows where the user is delegating their own carrier consignment ID and item references/barcodes. A simpler guide on editing consignments via the API where you are NOT allocating carrier consignment IDs and item references/barcodes can be found here: How to Edit Consignments Via The API

Edit Consignment Workflow

Step 1: Create 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:
/apiv2/consignments/createConsignmentwithComplexItems

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.
An example of how these would be set is:

  1. {
      "carrierConsignmentId": "2657628002",
      "carrierId": "446",
      //all other consignment data
      "items": [
        {
          "name": "Pallet",
          "quantity": 2,
          "itemType": "Pallet",
          "standardItem": {
            "weight": 270,
            "length": "117",
            "height": "110",
            "width": "117"
          },
          "consignmentItemReferences": [
            {
              "carrierItemReference": "(00)393168610029113320"
            },
            {
              "carrierItemReference": "(00)393168610029113321"
            }
          ]
        }
      ]
    }
The response you get on a successful consignment create will include an "id" value - which is the Machship consignment ID.
You will need to store this returned "id" value so you are able to retrieve and modify the consignment in the following steps.
NOTE: If you are unable to store the returned id value, then prior to calling the GET endpoint mentioned in the next step, you will first need to call /apiv2/consignments/returnConsignmentsByCarrierConsignmentId using the consignment ID you delegated earlier, then get the ID from that, before you proceed with step 2 as it is required for the next endpoints.

Step 2: Get Your Consignment

To edit a consignment, you would first call:
GET /apiv2/consignments/getUnmanifestedConsignmentForEdit
The only key value pair required is:
id = the consignment ID stored from previous step.
This endpoint returns the full schema of data about the consignment in the format required for editing.

Step 3: Edit Your Consignment

Now that you have your response, take everything from inside the object section, and start making your edits.
You can add new items, remove them, or edit them.
To add an item with a barcode you would add a new item in the following format:
  1.             {
  2.                 "itemType": "Carton",
  3.                 "name": "Test Item",
  4.                 "quantity": 1,
  5.                 "standardItem": {
  6.                     "height": 20.00000,
  7.                     "weight": 1.00000,
  8.                     "length": 20.00000,
  9.                     "width": 20.00000
  10.                 },
  11.                 "consignmentItemReferences": [
  12.                     {
  13.                         "carrierItemReference": "642000123456780000299006",
  14.                     }
  15.                 ]
  16.             }
If you are adding barcodes or removing non-sequential barcodes you need to edit this value, setting it to TRUE:
  1. { "id": 26848234, "setItemReferences": true, //ALL RETURNED CONSIGNMENT DATA HERE "items": [ { "itemType": "Carton", "name": "Test Item", "quantity": 1, "standardItem": { "height": 20.00000, "weight": 1.00000, "length": 20.00000, "width": 20.00000 }, "consignmentItemReferences": [ { "carrierItemReference": "642000123456780000299006", "printed": false, "printedDateUtc": null } ] } ], //ANY & ALL REMAINING CONSIGNMENT DATA HERE }
This instructs us to read the barcodes from the lines, rather than generating our own.
If you note that we are ignoring the barcodes you have set, and are setting our own, it is likely either that you forgot this value, or the carrier doesn't support allocating barcodes from outside of Machship.

Step 4: POST Your Edit

Send this edited payload to POST /apiv2/consignments/editUnmanifestedConsignment

The response from this will be your edited payload - check it and ensure the item references and consignment Id is what you expect.

That's it - you're done!

Understanding carrierItemReference in getConsignment Responses

When working with delegated custom barcodes and item references, it is important to understand what the carrierItemReference field returns when you retrieve a consignment via the API.

Setting vs. Retrieving carrierItemReference

When you create a consignment using createConsignmentwithComplexItems, you set the carrierItemReference field to the barcode string you want displayed on the label. However, when you retrieve that consignment later via getConsignment, the carrierItemReference field in the itemReferences section returns the carrier item reference value IF the carrier provides it.

Barcode vs. carrierItemReference

The full 2D barcode string visible on physical labels is different from carrierItemReference. The barcode on the label is the encoded barcode content that includes zone, volume, service code, and other data points specific to the carrier's system. The carrierItemReference is a separate identifier that the carrier may return in their response to Machship.

Carrier-Specific Limitations

Some carriers only provide barcode data and do not return an item reference value. For example, carriers such as Kiwi Express and Kiwi Oversize return barcode data but not an item reference. For these carriers, the carrierItemReference field will not be populated in the getConsignment response, even though the barcode is present on the physical label.

Test Account Limitation

Consignments created on test accounts do not trigger requests to the carrier's live system, so no carrier response data (including barcode or item reference) is received. Once your account transitions to live status, carrier response data will be available in the getConsignment response.

Example: For Kiwi Express, the carrier returns barcode data but not an item reference. Therefore, the carrierItemReference field will be empty in the itemReferences section of the getConsignment response, even though the barcode is present on the physical label.