Editing Consignments via the API

• Overview
• Prerequisites
• Edit Workflow
  • Step 1: Create Consignment
  • Step 2: Retrieve Consignment
  • Step 3: Make Edits
  • Step 4: Submit Changes
• Examples
  • Adding Items
  • Editing Items
• Important Notes

Overview

This guide explains how to edit existing consignments using the MachShip API. Common edit operations include:

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

This guide covers standard editing workflows where MachShip manages carrier consignment IDs and item references/barcodes. For editing consignments when delegating your own item references, see our Delegated References Guide.

Prerequisites

Before editing a consignment, you'll need:

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

Edit Workflow

Step 1: Create Consignment

First, create your consignment using one of these endpoints:

POST /apiv2/consignments/createConsignment

For standard items, or:

POST /apiv2/consignments/createConsignmentwithComplexItems

For consignments with dangerous goods.

Important: Store the returned id value from the response. You'll need this MachShip consignment ID for subsequent steps.

If you only have the carrier's consignment ID, you can retrieve the MachShip ID using:

GET /apiv2/consignments/returnConsignmentsByCarrierConsignmentId

Step 2: Retrieve Consignment

To edit a consignment, first retrieve its current state:

GET /apiv2/consignments/getUnmanifestedConsignmentForEdit

Required parameter:

• id: The MachShip consignment ID from step 1

This endpoint returns the full consignment data in an editable format.

Step 3: Make Edits

Take the response from step 2 and modify the data as needed. You can:

• Add new items
• Remove existing items
• Modify item properties
• Update consignment details

Step 4: Submit Changes

Send your modified payload to:

POST /apiv2/consignments/editUnmanifestedConsignment

The response will contain your updated consignment. Verify that the item references and consignment ID match your expectations.

Examples

Adding Items

To add a new item, include it in the items array:

{
    "itemType": "Carton",
    "name": "Test Item",
    "quantity": 1,
    "standardItem": {
        "height": 20.00000,
        "weight": 1.00000,
        "length": 20.00000,
        "width": 20.00000
    }
}

Editing Items

When editing existing items, you can modify any of these properties:

• Dimensions (height, width, length)
• Weight
• Quantity
• Item type
• Name

Important Notes

1. Label Implications:

   • Adding or removing items can reset item references for some carriers
   • Wait until editing is complete before printing labels if possible
   • Some carriers require sequential label barcodes - removing a middle label can invalidate the set
   • Simple edits to weights and dimensions typically don't affect labels

2. Timing:

   • Only unmanifested consignments can be edited
   • Complete all edits before manifesting

3. Validation:

   • Changes may affect pricing
   • Some edits might make a consignment invalid for the selected service
   • Always verify the response after editing