Create new consignments

Create a consignment link

The simplest way to record consignment details in the Consignments platform is to use the Create Consignment API endpoint. Create Consignment allows you to send package details directly to Consignments, where the platform returns a unique {consignmentReference}.

Send the request link

To create a consignment, send a POST request to https://api.electioapp.com/consignments. The body of the request should contain the consignment details, structured as per the Consignments data contract.

As a minimum, the Create Consignments endpoint requires you to send package weights and dimensions, origin address, and destination address data. You can either specify package weights and dimension via the Weight and Dimensions properties, or by supplying a PackageSizeReference.

There are lots of optional properties you can send when creating a consignment, including:

• Your own consignment reference
• Details of the specific items inside the consignment’s packages
• The consignment’s source
• Shipping and delivery dates
• The consignment’s direction of travel
• Metadata - Consignments metadata allows you to use custom fields to record additional data about a package. For more information on using metadata in Consignments, see the metadata guide
• Tags - Allocation tags enable you to filter the list of carrier services that a particular consignment could be allocated to. For more information on allocation tags, see the allocation tags guide.

Adding optional properties when you create a consignment can help you to get more out of the Consignments product. For example, recording your own consignment reference enables you to search for consignments by those references in the user-interface and via the Search Consignments endpoint.

Example: Create consignments request link

The example below shows a simple Create Consignments request containing just package and address details. For an example of a full Create Consignment request, see the Create Consignment API reference.

Create Consignments Request

POST https://api.electioapp.com/consignments

  {
  "Packages": [
    {
      "Weight": {
        "Value": 0.5,
        "Unit": "Kg"
      },
      "Dimensions": {
        "Unit": "Cm",
        "Width": 10.0,
        "Length": 10.0,
        "Height": 10.0
      },
      "Description": "Socks",
      "Value": {
        "Amount": 5.99,
        "Currency": {
          "IsoCode": "GBP"
        }
      }
    }  
  ],
  "Addresses": [
    {
      "AddressType": "Origin",
      "ShippingLocationReference": "Sorted1",
      "IsCached": false
    },
    {
      "AddressType": "Destination",
      "Contact": {
        "Title": "Mr",
        "FirstName": "Peter",
        "LastName": "McPetersson",
        "Telephone": "07702123456",
        "Mobile": "07702123456",
        "LandLine": "0161544123",
        "Email": "peter.mcpetersson@test.com"
      },
      "AddressLine1": "13 Porter Street",
      "Region": "Greater Manchester",
      "Postcode": "M1 5WG",
      "Country": {
        "Name": "Great Britain",
        "IsoCode": {
          "TwoLetterCode": "GB"
        }
      },
      "IsCached": false
    }
  ]
}
  

The create consignments response link

Once it has received the consignment information, The Consignments platform creates the consignment record and returns a link to the newly-created consignment, including its {consignmentReference}.

The {consignmentReference} is a unique identifier for the consignment, and is a required parameter for many of Consignments API requests. Each package {consignmentReference} takes the format EC-xxx-xxx-xxx, where x is an alphanumeric character. Many of PRO’s endpoints take {consignmentReference} as a parameter.

In the example below, Consignments has returned a {consignmentReference} of EC-000-05B-MMA.

Create Consignments Response

  [
  {
    "Rel": "Link",
    "Href": "https://api.electioapp.com/consignments/EC-000-05B-MMA"
  }
]
  

All Consignments have a {consignmentState}, indicating the point in the delivery process that that particular consignment is at. Newly-created consignments have an initial state of Unallocated. For more information on consignment states, see the Consignment States page.

Create consignments from delivery options link

The Create Consignments endpoint isn’t the only endpoint that can generate consignments. You can also create consignments via the Delivery Options API, which enables you to get a list of delivery options for a potential consignment that you can present to your customer at checkout. When you select the required option, Consignments automatically creates and allocates a new consignment without requiring you to make additional API requests.

To create a consignment in this way, you’ll need to make two API requests:

1. Call the Delivery Options endpoint. The structure of the Delivery Options request is very similar to that of the Create Consignment request. However, rather than simply creating a consignment from the information, Consignments instead returns a list of potential delivery options for the (as yet uncreated) consignment. Each delivery option represents a delivery date and time, and a carrier services that can fulfil the delivery of the consignment in line with that date and time.

2. To select the option that the customer chooses, send the relevant deliveryOptionReference to Consignments via the Select Option endpoint. Consignments uses the information that you provided when making the Delivery Options request to create a new consignment and allocate it to the relevant carrier service for the selected delivery option. It then returns a link to the created consignment.

You can also generate consignments from pickup options. The process is the same as that used for delivery options - make a Pickup Options call and then select the required option via the Select Option endpoint.