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!

      • Related Articles

      • 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 ...

      • 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 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 ...

      • 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 ...

      • Machship API Integration Workflow Guide

        The objective of this article is to give you a quick-start guide in working with our API to achieve common integration workflows, and how that affects which API endpoints you wish to use. API Authentication & Documentation Our API accepts and returns ...