How to Edit Consignments Via The API

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:
  1. Adjusting item weights/dimensions
  2. Adding new items
  3. Removing items
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 NOT delegating their own carrier consignment ID and item references/barcodes. A more complex guide on editing consignments via the API where you are allocating carrier consignment IDs and item references/barcodes can be found here: A guide to editing consignments via the API when delegating item references

Edit Consignment Workflow

Step 1: Create Your Consignment

The following endpoints can be used to create consignments:
POST /apiv2/consignments/createConsignment - for standard items
POST /apiv2/consignments/createConsignmentwithComplexItems - when setting DG contents
A full guide to creating consignment can be found here, this guide will simply cover the edit part of the workflow.
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 Machship id value, and you need to store the carrier consignment ID, then prior to calling the GET endpoint mentioned in the next step, you will first need to call /apiv2/consignments/returnConsignmentsByCarrierConsignmentId 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 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.             }
Note, if you are editing items (adding or removing entire lines, or changing quantities) this can cause a reset in the item references for some carriers, so it's best that you hold off printing labels till editing is completed to prevent relabelling. This is because some carriers require sequential labels - so if you were to remove label 2 in a set of 3, the labels would become invalid.

Simply editing weights and dimensions should not result in any line reference and label changes and is relatively safe.

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

    • 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 Manifest via the MachShip API

      The manifesting of a consignment or a series of consignments in MachShip will finalise that consignment in the MachShip system and send through the consignment data to the transport provider. This data transfer will take place via the preferred ...

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

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