Creating a Consignment via API with Your Own Carrier Consignment ID and Item References/Barcodes

The following article covers how to create a consignment via the API when you are delegating your own carrier consignment numbers and/or item references/barcodes.

Terms

Carrier Consignment ID - is the consignment reference that is passed to the carrier as the identifier for the shipment

Also known as: connote, carrier consignment number.

Item Reference - is the barcode that appears on the label that will be used by the carrier to identify a specific package

Also known as: item barcode, SSCC

Important Information

This is an advanced topic, and requires the generation of fully compliant carrier consignment ids and item references - something which Machship typically generates for a consignment.

  1. Not all carriers accept external allocated consignment numbers and/or item references - please verify with your carriers and the MachShip team if this is feasible prior to implementing.
  2. You do not have to allocate both the carrier consignment ID and item references - You may opt to delegate a consignment ID, but have us generate the barcodes that appear on the labels. If you're delegating an SSCC as the barcode, you may opt for us to delegate a consignment ID, while you delegate the item references
  3. All generated references should be approved by carriers - some require the item references to include the connote, while others do not. It's important you communicate with your carriers regarding their requirements prior to implementing.

{primary} This article will not cover the basics of creating consignments. An article covering consignment creation in depth can be found here:
A guide to creating Consignments via the API

Endpoint

When you are looking to generate your own consignment numbers and item references/barcodes and pass them into Machship you must use the following endpoint to create consignments:

POST https://live.machship.com/apiv2/consignments/createConsignmentwithComplexItems HTTP/1.1
Host: live.machship.com
token: <api_token>

The full schema of this endpoint is available in our swagger documentation here.

Allocating Consignment ID & Barcodes

When using this endpoint, we have two undocumented fields you will need to add to your payload:

  1. carrierConsignmentId - sitting at the parent level, this value is the carrier consignment ID, which must follow the carrier specifications including any relevant prefixes that you have generated for this consignment.
  2. items.consignmentItemReferences.carrierItemReference - This field sits inside an array on the items object, inside the consignmentItemReferences array object and is the barcode that will be used on the label. This barcode must follow the carrier specifications.
    1. You must set one reference for every quantity on the given line.

An example of how these would be set is:

{
  "carrierConsignmentId": "2657628002",
  "carrierId": "446",
  //all other consignment data as per schema
  "items": [
    {
      "name": "Pallet",
      "quantity": 2,
      "itemType": "Pallet",
      "standardItem": {
        "weight": 270,
        "length": "117",
        "height": "110",
        "width": "117"
      },
      "consignmentItemReferences": [
        {
          "carrierItemReference": "(00)393168610029113320"
        },
        {
          "carrierItemReference": "(00)393168610029113321"
        }
      ]
    },
    {
      "name": "Pallet",
      "quantity": 1,
      "itemType": "Pallet",
      "standardItem": {
        "weight": 170,
        "length": "110",
        "height": "110",
        "width": "110"
      },
      "consignmentItemReferences": [
        {
          "carrierItemReference": "(00)393168610029113322"
        }
      ]
    }
  ]
}

After you POST this data to the specified endpoint, check the response.

If your carrierConsignmentId and carrierItemReference match what you sent in, you've successfully delegated the references.

That's it - you're done!