Overview

This guide explains how to edit consignments when you are setting your own carrier consignment numbers and item references/barcodes. Common edit operations include:

  • Adjusting item weights/dimensions
  • Adding new items and references
  • Removing items and references

This guide is specifically for workflows where you manage carrier consignment IDs and item references/barcodes. For standard editing workflows, see Editing Consignments.

Prerequisites

Before proceeding, ensure you have:

  1. A created, unmanifested consignment
  2. The MachShip consignment ID
  3. Understanding of basic consignment creation

Edit Workflow

Step 1: Create Consignment

When delegating your own consignment numbers and references, use:

POST /apiv2/consignments/createConsignmentwithComplexItems

Required custom fields:

  1. carrierConsignmentId: At the parent level, this is your carrier-specific consignment ID
  2. items.consignmentItemReferences.carrierItemReference: Inside each item's references array, this is your carrier-specific barcode

Example request:

{
  "carrierConsignmentId": "2657628002",
  "carrierId": "446",
  "items": [
    {
      "name": "Pallet",
      "quantity": 2,
      "itemType": "Pallet",
      "standardItem": {
        "weight": 270,
        "length": "117",
        "height": "110",
        "width": "117"
      },
      "consignmentItemReferences": [
        {
          "carrierItemReference": "(00)393168610029113320"
        },
        {
          "carrierItemReference": "(00)393168610029113321"
        }
      ]
    }
  ]
}

Important: Store the returned id value. If you can't store it, you can retrieve it later using /apiv2/consignments/returnConsignmentsByCarrierConsignmentId with your carrier consignment ID.

Step 2: Retrieve Consignment

Get the current consignment state:

GET /apiv2/consignments/getUnmanifestedConsignmentForEdit

Required parameter:

  • id: The MachShip consignment ID from step 1

Step 3: Make Edits

Take the response from step 2 and modify as needed. When working with references:

  1. Set setItemReferences to true at the root level:
{
  "id": 26848234,
  "setItemReferences": true,
  ...
}
  1. Ensure each item has proper references:
{
 "id": 26848234,
  "setItemReferences": true,
  .....
  "items": [
    {
      .....
      "consignmentItemReferences": [
        {
          "carrierItemReference": "642000123456780000299006"
        }
      ]
    }
  ],
  .....
}

Step 4: Submit Changes

Send your modified payload to:

POST /apiv2/consignments/editUnmanifestedConsignment

Working with References

Adding Items with References

When adding a new item, include both standard item details and references:

{
  "itemType": "Carton",
  "name": "Test Item",
  "quantity": 1,
  "standardItem": {
    "height": 20.00000,
    "weight": 1.00000,
    "length": 20.00000,
    "width": 20.00000
  },
  "consignmentItemReferences": [
    {
      "carrierItemReference": "642000123456780000299006"
    }
  ]
}

Managing References

  1. Adding References:

    • Set setItemReferences to true
    • Include complete reference information for each item

  2. Removing References:

    • Remove the entire reference object from the item
    • Ensure setItemReferences is true

  3. Updating References:

    • Modify the carrierItemReference value
    • Keep the reference object structure intact

Important Notes

  1. Reference Management:

    • Always set setItemReferences to true when modifying references
    • If references are being ignored, check this setting or verify carrier support
    • Some carriers don't support external reference allocation

  2. Carrier Support:

    • Not all carriers support delegated references
    • Verify carrier capabilities before implementing this workflow

  3. Validation:

    • References must follow carrier-specific formats
    • Verify all references in the response match your expectations
    • Complete all reference changes before manifesting