Creating New Consignments

  • v1
  • consignments
  • pro
  • api
  • EORI number

In order for SortedPRO to manage a consignment, you'll need to record the details of that consignment on the system. This page explains the various ways that you can record consignment information in PRO.

Creating a Consignment Via the Consignments API

Perhaps the simplest way to record consignment details in PRO is to use the Create Consignment API endpoint. Create Consignment enables you to send consignment details directly to PRO, from which PRO creates the consignment record and returns a unique {consignmentReference}.

Sending the Request

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 PRO data contract.

Note

For full reference information on the Create Consignments endpoint, including the properties accepted and the structure required, see the Create Consignment API reference.

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. PRO metadata enables you to use custom fields to record additional data about a consignment. For more information on using metadata in PRO, see the Metadata page.
  • 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 Tags page.

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

Caution

You should exercise caution when using the ShippingDate and RequiredDeliveryDate parameters to specify dates for your consignment. These parameters limit delivery options for the consignment, meaning that the consignment can only be allocated to carrier services that would be able to ship it on the specified ShippingDate and / or deliver it by the RequiredDeliveryDate. If the IsToBeExactlyOnTheDateSpecified flag of the RequiredDeliveryDate is set, then the consignment is further limited, as it can only be allocated to a service that would deliver it on the exact date specified.

If the dates you specify are too restrictive, there may not be any carrier services available to take the consignment, which would result in a failed allocation. As such, you should only specify shipping and delivery dates where it is necessary to do so.

International Shipments

Following the UK's departure from the EU, certain additional consignment properties must be passed in order for PRO to generate customs documentation for UK-originating international consignments. In addition, certain carriers have their own data requirements that UK-originating international consignments must meet in order to be considered for allocation to that carrier.

For an explanation of Brexit-related data requirements, see the Brexit Data Guide page.

For more information on commercial invoices and other customs documents in PRO, see the Getting Customs Docs and Invoices page.

Example Create Consignments Request

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.

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

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

The {consignmentReference} is a unique identifier for that consignment within PRO, and is a required parameter for many of PRO's API requests. Each PRO {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, PRO has returned a {consignmentReference} of EC-000-05B-MMA.

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

All PRO 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 PRO consignment states, see the Consignment States page.

Note

You can also create consignments via the Manual Upload page of the PRO UI. This feature is effectively a front-end for the Create Consignments API, and is most useful for handling exceptions and cases in which your conventional API workflow cannot be used.

For more information on creating consignments via the PRO UI, see the Create a Consignment Manually how-to procedure in the PRO Web Admin Portal User Guide.

Creating Consignments From Delivery Options

The Create Consignments endpoint isn't the only PRO 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, PRO automatically creates and allocates a new consignment without requiring you to make additional API calls.

Note

Access to PRO's delivery and pickup option endpoints requires a SortedHERO license. This component is sold separately to the main SortedPRO product.

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

  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, PRO 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 PRO via the Select Option endpoint. PRO 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.

Note
  • For a full user guide on working with delivery and pickup options, including further information on selecting options, see the Using Delivery and Pickup Options section.
  • For reference information on the Delivery Options and Pickup Options APIs, see the API reference.

Next Steps