Creating Pending Consignments Via The MachShip API

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"
}
}

  2. Saved Company Location ID

    {
"fromCompanyLocationId": 1234,
"toCompanyLocationId": 5678
}

  3. 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
}
]
}

  2. Using Saved Items

    {
"items": [
{
  "companyItemId": 999
}
]
}

  3. 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"
    }
  ]
}
]
}

  4. 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
}
]
}

  2. Missing Required Fields

    
{
"object": null,
"errors": [
{
  "memberNames": ["toContact"],
  "errorMessage": "To contact is required",
  "validationType": 1
}
]

3. **Invalid Carrier Selection**
```json
{
  "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