What is a Pending Consignment?

A pending consignment is a draft shipping job that that can be completed and converted into a consignment by warehouse staff using the MachShip interface:

A typical pending consignment will contain

  • Pick-up location
  • Delivery location
  • Optional carrier selection
  • Optional service selection
  • Optional package details

What a pending consignment is not:

  1. Not a Price Quote - If you're looking to generate prices for different shipping options, you should use the routing API endpoints instead.
  2. Not a Full Consignment - If you have all necessary information and are ready to ship, you should create a full consignment instead.
  3. Not Immediately Shippable - A pending consignment must be converted to a full consignment before it can be manifested and shipped.

Pending Consignment Workflow

When creating a pending consignment via the API, you would typically be implementing the following workflow:

  1. You create a pending consignment with known information (addresses, references)
  2. Warehouse team pick/pack the order or shipment
  3. Warehouse team scan or input the order number into MachShip to bring p the prefilled consignment
  4. Allow warehouse staff to complete package details and carrier selection through MachShip interface
  5. Labels print out and consignment is created

API Endpoints

To create a pending consignment, you'll need to send a POST request to:

POST /apiv2/pendingConsignments/createPendingConsignment

Pending Consignment Fields

Companies

A company in MachShip refers to a business unit that has been setup inside your MachShip account. When creating a pending consignment, you can specify which company it should be associated with:

{
  "companyId": 9999
}

If no company ID is provided, the pending consignment will be associated with the company of the user making the API request. A list of company ids can be obtained from /apiv2/companies/getAll.

Locations & Addresses

When creating a pending consignment, you can provide address details for both pickup and delivery locations. MachShip offers several ways to specify these locations:

  1. Full Address Details
{
  "fromName": "My Warehouse",
  "fromContact": "John Doe",
  "fromPhone": "1234567890",
  "fromEmail": "john@example.com",
  "fromAddressLine1": "123 Warehouse St",
  "fromAddressLine2": "Unit 4",
  "fromLocation": {
    "suburb": "Melbourne",
    "postcode": "3000"
  },
  "toName": "Customer's House",
  "toContact": "Jane Smith",
  "toPhone": "9876543210",
  "toEmail": "jane@customer.com",
  "toAddressLine1": "456 Customer Ave",
  "toAddressLine2": "Apt 7",
  "toLocation": {
    "suburb": "Sydney",
    "postcode": "2000"
  }
}
  1. Saved Company Location ID
{
  "fromCompanyLocationId": 1234,
  "toCompanyLocationId": 5678
}
  1. International Addresses For international shipments, additional fields are required:
{
  "fromCompanyLocationId": 1234,

  "toName": "International Customer",
  "toContact": "Bob Smith",
  "toPhone": "1234567890",
  "toEmail": "bob@customer.com",
  "toAddressLine1": "789 Customer St",

  "isInternational": true,
  "internationalToCity": "Los Angeles",
  "internationalToPostcode": "90001",
  "internationalToProvince": "CA",
  "toCountryCode": "US"
}

Carriers & Services (Optional)

You can optionally specify carrier details for the pending consignment:

{
  "carrierId": 11,
  "carrierAccountId": 456,
  "companyCarrierAccountId": 789,
  "carrierServiceId": 123
}

Dispatch DateTime (Optional)

Specify when the consignment should be dispatched using either UTC or local time:

{
  "despatchDateTimeLocal": "2024-12-12T03:06:41.360Z"
}

Additional Options

Optional parameters include:

  • questionIds: For special handling requirements
"questionIds": [
    "13",  // Residential delivery
    "7"    // Tailgate required
]
  • staffMemberName: To record which team member created the pending consignment
  • sendTrackingEmail: Set to true to send tracking emails when converted to full consignment
  • customValues: For carrier-specific options
"customValues": [
    {
      "propertyName": "palletSpaces",
      "value": "27"
    }
]

Items & Packages

For pending consignments, item details are optional but can be provided if known. You can specify items in several ways:

  1. Basic Item Details
{
  "items": [
    {
      "itemType": "Carton",
      "name": "Standard Box",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10
    }
  ]
}
  1. Using Saved Items
{
  "items": [
    {
      "companyItemId": 999
    }
  ]
}
  1. Items with Dangerous Goods
{
  "items": [
    {
      "itemType": "Carton",
      "name": "Standard Box",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10,
      "pendingConsignmentItemDgItems": [
        {
          "unNumber": 1234,
          "packingGroup": 1,
          "containerType": 1,
          "aggregateQuantity": 10,
          "isAggregateQuantityWeight": true,
          "numberOfContainers": 1,
          "dgClassType": 1,
          "properShippingName": "FLAMMABLE LIQUID"
        }
      ]
    }
  ]
}
  1. Items with Contents (for International)
{
  "items": [
    {
      "itemType": "Carton",
      "name": "Standard Box",
      "quantity": 1,
      "height": 10,
      "weight": 10,
      "length": 10,
      "width": 10,
      "pendingConsignmentItemContents": [
        {
          "description": "Electronics",
          "quantity": 5,
          "dollarValue": 500,
          "harmonizedCode": "851712",
          "countryOfManufactureCode": "CN"
        }
      ]
    }
  ]
}

Examples

Basic Pending Consignment

{
  "fromName": "My Warehouse",
  "fromContact": "John Doe",
  "fromPhone": "1234567890",
  "fromEmail": "john@example.com",
  "fromAddressLine1": "123 Warehouse St",
  "fromLocation": {
    "suburb": "Melbourne",
    "postcode": "3000"
  },
  "toName": "Customer's House",
  "toContact": "Jane Smith",
  "toPhone": "9876543210",
  "toAddressLine1": "456 Customer Ave",
  "toLocation": {
    "suburb": "Sydney",
    "postcode": "2000"
  },
  "customerReference": "ORDER-123",
  "specialInstructions": "Call on arrival"
}

Complex Pending Consignment

{
  "companyId": 9999,
  "despatchDateTimeLocal": "2024-12-12T03:06:41.360Z",
  "customerReference": "ORDER-123",
  "customerReference2": "PO-456",
  "carrierId": 11,
  "carrierServiceId": 123,
  "fromCompanyLocationId": 1234,
  "toName": "International Customer",
  "toContact": "Bob Smith",
  "toPhone": "1234567890",
  "toEmail": "bob@customer.com",
  "toAddressLine1": "789 Customer St",
  "isInternational": true,
  "internationalToCity": "Los Angeles",
  "internationalToPostcode": "90001",
  "internationalToProvince": "CA",
  "toCountryCode": "US,
  "items": [
    {
      "itemType": 1,
      "name": "Export Package",
      "quantity": 2,
      "height": 20,
      "weight": 15,
      "length": 30,
      "width": 25,
      "pendingConsignmentItemContents": [
        {
          "description": "Electronics",
          "quantity": 10,
          "dollarValue": 1000,
          "harmonizedCode": "851712",
          "countryOfManufactureCode": "AU"
        }
      ]
    }
  ],
  "questionIds": ["13"],
  "sendTrackingEmail": true
}

Response Format

When a pending consignment is created successfully, MachShip returns:

{
  "object": {
    "id": 123456,
    "consignmentNumber": "PC123456"
  },
  "errors": []
}

Key response fields:

  • id: Unique identifier for the pending consignment
  • consignmentNumber: The pending consignment number with "PC" prefix
  • errors: Array of any validation errors encountered

Common Errors

Here are common errors you might encounter when creating pending consignments:

  1. Invalid Address
{
  "object": null,
  "errors": [
    {
      "memberNames": ["fromLocation"],
      "errorMessage": "From location suburb and postcode combination is invalid",
      "validationType": 1
    }
  ]
}
  1. Missing Required Fields
{
  "object": null,
  "errors": [
    {
      "memberNames": ["toContact"],
      "errorMessage": "To contact is required",
      "validationType": 1
    }
  ]
  1. Invalid Carrier Selection
{
  "object": null,
  "errors": [
    {
      "memberNames": ["carrierId"],
      "errorMessage": "Selected carrier is not available for this company",
      "validationType": 1
    }
  ]
}

Best practices for handling errors:

  1. Always check the response's errors array
  2. Log error messages for troubleshooting
  3. Implement appropriate error handling in your integration
  4. Consider implementing retry logic for transient errors