Overview

This guide outlines how to manually manifest shipments using three different endpoints in the Shipments API: individual shipment manifesting, query-based batch manifesting, and group-based manifesting. Use this document to determine the most suitable method for finalising your shipments for carrier collection.

Manifest an individual shipment manually

The Manifest Shipment endpoint enables you to manifest an individual shipment. To call Manifest Shipment, send a PUT request to https://api.sorted.com/pro/shipments/{reference}/manifest, where {reference} is the unique reference for the shipment you want to manifest.

Once our Shipments API has received the request, it attempts to manifest the specified shipment and returns a manifest_result containing the following information:

  • A unique reference for the manifest item.
  • Details of the carrier and service that the shipment was manifested with.
  • A message providing details of the result.
  • The current state of the shipment as a result of the manifest operation. Ordinarily, this would be manifesting.
  • A link to the generated manifest.

Manifest shipment example

The example shows a successful request to manifest shipment sp_00673267200365953327505217421312.

Manifest shipment request

  `PUT https://api.sorted.com/pro/shipments/sp_00673267200365953327505217421312/manifest`

Manifest shipment response

  {
  "results": [
    {
      "reference": "ma_00673536672211162995858760007680",
      "carrier": {
        "reference": "XPDI",
        "name": "XPD International",
        "service_reference": "XPDISU",
        "service_name": "XPD International Supreme"
      },
      "message": "Shipment sp_00673267200365953327505217421312 manifested with XDP Worldwide successfully",
      "state": "manifested",
      "shipment_count": 1,
      "_links": [
        {
          "href": "https://beta.sorted.com/pro/shipments/sp_00673267200365953327505217421312",
          "rel": "shipment",
          "reference": "sp_00673267200365953327505217421312",
          "type": "shipment"
        }
      ]
    }
  ]
}

The manifest shipments by query endpoint

The Manifest Shipments by Query endpoint enables you to manifest shipments using a query, rather than by providing shipment references directly. To call Manifest Shipments by Query, send a POST request to https://api.sorted.com/pro/shipments/manifest/query.

The body of the request should contain shipment search criteria. All properties are optional. You can use the following query fields:

  • shipping_locations - A list of shipping location references. Only shipments originating from these locations will be selected.
  • address_custom_reference - A specific address reference used to identify shipments. You can specify address custom_reference properties when creating a shipment.
  • shipment_states - Shipments API will only select shipments in the specified state.
  • labels_retrieved - A boolean value. If provided as true, Shipments API will only manifests those shipments for which labels have already been retrieved.
  • required_shipping_date - Shipments API only matches those shipments shipping within the specified date range.
  • carrier_reference - Shipments API only manifests those shipments bound for the specified carrier.
  • carrier_service_reference - Shipments API only manifests those shipments bound for the specified carrier service.

Once the request is received, Shipments attempts to manifest any shipments that meet the specified criteria. The system then returns a Manifest Response.

All of the Shipments API manifest endpoints return a Manifest Response detailing the outcome of the manifest request. The Manifest Response contains one or more manifest_result objects, of which each represents a manifest item and contains the following information:

  • A unique reference for the manifest item.
  • Details of the carrier and service that the shipment(s) were manifested or queued to be manifested with.
  • A message providing details of the result.
  • The current state of the shipment as a result of the manifest operation. Ordinarily, this would be manifesting.
  • The number of shipments that was attempted to manifest.
  • A link to the generated manifest.

Each manifest item in the response contains shipments for a single carrier. If your request causes shipments to be queued for manifest with multiple carriers then the Shipments platform returns one manifest_result per carrier.

Manifest shipments by query example

The example shows a request to manifest all allocated shipments that have had their labels retrieved and are shipping from an address with the address_custom_reference 76dc0fd4-1788-48bf-978c-f8601411f9b1 on 23-07-2020.

In this case, the query has returned four shipments. The Shipments platform has successfully queued all of these shipments for allocation.

Manifest shipments by query request

  {
    "shipping_locations": null,
    "address_custom_reference": "76dc0fd4-1788-48bf-978c-f8601411f9b1",
    "shipment_states": [
        "allocated"
    ],
    "labels_retrieved": true,
    "required_shipping_date": "2020-07-23T00:00:00+00:00"
}

Manifest shipments by query response

  {
  "results": [
    {
      "reference": "ma_00673542211491707169731467018240",
      "carrier": {
        "reference": "XPDI",
        "name": "XPD International",
        "service_reference": "XPDISU",
        "service_name": "XPD International Supreme"
      },
      "message": "4 shipments have been queued for manifest with XDP Worldwide successfully",
      "state": "manifesting",
      "shipment_count": 4,
      "_links": [
        {
          "href": "https://beta.sorted.com/pro/shipments/manifest/ma_00673542211491707169731467018240",
          "rel": "self",
          "reference": "ma_00673542211491707169731467018240",
          "type": "manifest"
        }
      ]
    }
  ]
}

The manifest shipments by shipment group endpoint

The Manifest Shipments by Shipment Group endpoint manifests all unmanifested shipments in a particular shipment group. It is designed to be used alongside other Shipment API’s other manifest endpoints as a means of “scooping up” any shipments in the group that were not manifested by other methods.

To call Manifest Shipments by Shipment Group, send a POST request to https://api.sorted.com/pro/shipment_groups/{reference}/manifest, where {reference} is the unique reference of the shipment group you want to manifest.

Once the request is received, Shipments API attempts to manifest any unmanifested shipments in the selected shipment group, and returns a Manifest Response.

All of Shipment API’s manifest endpoints return a Manifest Response detailing the outcome of the manifest request. The Manifest Response contains one or more manifest_result objects, of which each represents a manifest item and contains the following information:

  • A unique reference for the manifest item.
  • Details of the carrier and service that the shipment(s) were manifested or queued to be manifested with.
  • A message providing details of the result.
  • The current state of the shipment as a result of the manifest operation. Ordinarily, this would be manifesting.
  • The number of shipments that Ship attempted to manifest.
  • A link to the generated manifest.

Each manifest item in the response contains shipments for a single carrier. If your request causes shipments to be queued for manifest with multiple carriers then Ship returns one manifest_result per carrier.

Manifest shipments by shipment group example

The example shows a request to manifest shipments belonging to shipment group example123. Shipments has identified four unmanifested shipments within that group, and has successfully queued them all for manifest.

Manifest shipments by shipment group request

  `POST https://api.sorted.com/pro/shipment_groups/example123/manifest`

Manifest shipments by shipment group response

  {
  "results": [
    {
      "reference": "ma_00673542211491707169731467018240",
      "carrier": {
        "reference": "XPDI",
        "name": "XPD International",
        "service_reference": "XPDISU",
        "service_name": "XPD International Supreme"
      },
      "message": "4 shipments have been queued for manifest with XDP Worldwide successfully",
      "state": "manifesting",
      "shipment_count": 4,
      "_links": [
        {
          "href": "https://beta.sorted.com/pro/shipments/manifest/ma_00673542211491707169731467018240",
          "rel": "self",
          "reference": "ma_00673542211491707169731467018240",
          "type": "manifest"
        }
      ]
    }
  ]
}

Next steps