What is a quote?

The Shipments quotes API enables you to manually get delivery quotes for a shipment. This section explains the various ways in which you can get delivery quotes for a shipment.

In the Shipments platform, delivery quotes are generally used outside of a “regular” shipment allocation workflow, as a means of managing shipments that require manual intervention. For example, your customer service teams might want to get quotes for an expedited delivery on a shipment that was missed by a carrier and so did not meet its delivery promise.

Shipment’s Quotes API enables you to get delivery quotes for as-yet uncreated shipments. All Quotes endpoints return one or more quote objects, of which each represents an offer for carriage of a shipment with a specific carrier service. Each quote can be uniquely identified by a reference.

Quote endpoints

The Shipments platform has two endpoints that take the details of an as-yet uncreated shipment and return quotes:

  • Create Quote can return quotes from any suitable carrier service. To call Create Quote, send a POST request to https://api.sorted.com/pro/shipments/quote.
  • Create Quote by Service Group returns quotes from eligible services in the specified carrier service group. To call Create Quote by Service Group, send a POST request to https://api.sorted.com/pro/shipments/quote/service_group/{group_ref}, where {group_ref} is the unique reference of the service group you want to get quotes within.

For both endpoints, the request body should use the same structure as a Create Shipment request.

Create quotes

As a minimum, the Create Quote and Create Quote by Service Group endpoints require you to send the following information in the request body:

  • shipment_type - Specifies whether the shipment will be on_demand (i.e. will require an ad-hoc carrier collection to be booked) or scheduled (i.e. will be picked up as part of a regularly scheduled carrier collection ).
  • contents - The contents of the shipment itself.
  • addresses - All shipments require both origin and destination addresses.

However, there are lots of optional properties you can send when requesting quotes for a potential shipment, including:

  • Your own custom reference for the shipment.
  • Required shipping and delivery dates.
  • The order date.
  • Customs documentation for international shipments. For more information on using customs documentation in Shipments, see the Get Shipment Documents page.
  • Shipment direction.
  • Custom label properties.
  • Tenant and channel.
  • Metadata. Enables you to use custom fields to record additional data about a shipment.
  • Tags. Allocation tags enable you to filter the list of carrier services that a particular shipment could be allocated to. For more information on allocation tags, see the Shipment Tags page.

Adding optional properties when you request quotes for a shipment can help you to filter the list of quotes you receive down to the most appropriate carrier services.

The quote result

Once it has received a request from either the Create Quote endpoint or the Create Quote by Service Group endpoint, Shipments API returns a quote result. The quote result object includes a summary of the shipment details submitted, a list of quote objects, and a list of excluded_services (that is, eligible services for which it was not possible to obtain a delivery quote).

Each quote object contains the following information:

  • A unique reference for the quote in the format qu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
  • Creation and expiry dates.
  • Details of the relevant carrier and carrier service.
  • Confirmation of collection and delivery dates.
  • Pricing information.

At this point, you would be able to display the relevant quote information to your customer service operative.

Example quote

The example below shows a Create Quote request for a shipment. Note that Shipments API has returned two quotes, with a further service excluded as it cannot meet the delivery promise.

Quote request

POST https://api.sorted.com/pro/shipments/quote

  {
    "custom_reference": "0af07451-cf80-43cb-af24-acdfdbd41a14",
    "required_shipping_date": {
        "start": "2020-04-26T00:00:00+01:00",
        "end": "2020-04-26T23:59:59+01:00"
    },
    "tags": [
        "b&w",
        "T2"
    ],
    "order_date": "2020-04-05T09:34:55+01:00",
    "metadata": [
        {
            "key": "warehouse_id",
            "value": "WHF-0098762345D",
            "type": "string"
        },
        {
            "key": "refundable",
            "value": "false",
            "type": "bool"
        }
    ],
    "direction": "outbound",
    "shipment_type": "on_demand",
    "contents": [
        {
            "custom_reference": "b9fa91b0-0dd0-4dd5-986f-363fa8cb2386",
            "package_size_reference": null,
            "weight": {
                "value": 2.40,
                "unit": "Kg"
            },
            "dimensions": {
                "unit": "Cm",
                "width": 15.0,
                "height": 15.5,
                "length": 20.0
            },
            "description": "Jeans",
            "value": {
                "amount": 8.99,
                "currency": "GBP"
            },
            "sku": "SKU09876",
            "model": "MOD-009",
            "country_of_origin": "PT",
            "harmonisation_code": "09021000",
            "shipping_terms": "fca",
            "quantity": 2,
            "unit": "Box",
            "dangerous_goods": {
                "class_division": "2",
                "class_sub_divisions": [
                    "1"
                ],
                "packing_group": "iii",
                "id_number": "UN2202",
                "proper_shipping_name": "Hydrogen selenide, anhydrous",
                "technical_name": null,
                "physical_form": "gas",
                "radioactivity": "surface_reading",
                "accessibility": "accessible",
                "custom_label_text": null
            },
            "metadata": [
                {
                    "key": "Category",
                    "value": "Menswear",
                    "type": "string"
                }
            ],
            "label_properties": null,
            "Contents": null
        }
    ],
    "addresses": [
        {
            "address_type": "origin",
            "shipping_location_reference": "SLOC001"
        },
        {
            "address_type": "destination",
            "custom_reference": "21bbd58a-6dec-4097-9106-17501ddca38d",
            "contact": {
                "reference": "co_9953035290535460865",
                "title": "Mr",
                "first_name": "Steve",
                "last_name": "Kingston",
                "middle_name": null,
                "position": null,
                "contact_details": {
                    "landline": null,
                    "mobile": "+447495747987",
                    "email": "steve@kingston.com"
                }
            },
            "property_number": "8",
            "property_name": null,
            "address_line1": "Norbert Road",
            "address_line2": "Bertwistle",
            "address_line3": null,
            "locality": "Preston",
            "region": "Lancashire",
            "postal_code": "PR4 5LE",
            "country_iso_code": "GB",
            "lat_long": null
        }
    ],
    "label_properties": [
        {
            "key": "chute",
            "value": "9D"
        }
    ],
    "source": "WMS"
}

Quote response

  {
  "reference": "qc_00660740195638722361142689923072",
  "message": "2 quotes generated successfully",
  "shipment": {
    "addresses": [
      {
        "address_type": "origin",
        "shipping_location_reference": "SLOC001"
      },
      {
        "address_type": "destination",
        "custom_reference": "21bbd58a-6dec-4097-9106-17501ddca38d",
        "contact": {
          "reference": "co_9953035290535460865",
          "title": "Mr",
          "first_name": "Steve",
          "last_name": "Kingston",
          "contact_details": {
            "mobile": "+447495747987",
            "email": "steve@kingston.com"
          }
        },
        "property_number": "8",
        "address_line1": "Norbert Road",
        "address_line2": "Bertwistle",
        "locality": "Preston",
        "region": "Lancashire",
        "postal_code": "PR4 5LE",
        "country_iso_code": "GB"
      }
    ],
    "custom_reference": "0af07451-cf80-43cb-af24-acdfdbd41a14"
  },
  "quotes": [
    {
      "reference": "qu_00660740195620275617068980371456",
      "carrier": {
        "reference": "PCLYINTL",
        "name": "Parcelly International",
        "service_reference": "PCLYINTLISF",
        "service_name": "International Superfast"
      },
      "collection_date": {
        "start": "2020-07-16T00:00:00+00:00",
        "end": "2020-07-16T20:00:00+00:00",
        "has_value": true
      },
      "delivery_date": {
        "start": "2020-07-17T09:00:00+00:00",
        "end": "2020-07-17T12:00:00+00:00",
        "has_value": true
      },
      "price": {
        "net": 20.0,
        "gross": 20.0,
        "taxes": [
          {
            "rate": {
              "reference": "zero_rated",
              "country_iso_code": "PT",
              "type": "zero_rated",
              "value": 0.0
            },
            "amount": 0.0
          }
        ],
        "currency": "EUR"
      },
      "created": "2020-07-15T13:39:57.7777258+00:00",
      "expires": "2020-07-15T23:59:00+00:00",
      "_links": [
        {
          "href": "https://beta.sorted.com/pro/quotes/qu_00660740195620275617068980371456",
          "rel": "self",
          "reference": "qu_00660740195620275617068980371456",
          "type": "quote"
        }
      ]
    },
    {
      "reference": "qu_00660740195620275617068980371457",
      "carrier": {
        "reference": "QSDOM",
        "name": "QuickStep Domestic",
        "service_reference": "QSDOMLOC",
        "service_name": "QS Domestic Local"
      },
      "collection_date": {
        "start": "2020-07-16T00:00:00+00:00",
        "end": "2020-07-16T19:30:00+00:00",
        "has_value": true
      },
      "delivery_date": {
        "start": "2020-07-17T08:00:00+00:00",
        "end": "2020-07-17T15:45:00+00:00",
        "has_value": true
      },
      "price": {
        "net": 10.0,
        "gross": 12.0,
        "taxes": [
          {
            "rate": {
              "reference": "standard",
              "country_iso_code": "GB",
              "type": "VAT Standard",
              "value": 0.2
            },
            "amount": 2.0
          }
        ],
        "currency": "EUR"
      },
      "created": "2020-07-15T13:39:57.7779745+00:00",
      "expires": "2020-07-15T23:59:00+00:00",
      "_links": [
        {
          "href": "https://beta.sorted.com/pro/quotes/qu_00660740195620275617068980371457",
          "rel": "self",
          "reference": "qu_00660740195620275617068980371457",
          "type": "quote"
        }
      ]
    }
  ],
  "excluded_services": [
    {
      "carrier": {
        "reference": "DNT",
        "name": "DNT Express",
        "service_reference": "DNTEXPOD",
        "service_name": "DNT ExpressPack On Demand"
      },
      "exclusion": {
        "reason": "Carrier does not have availability for this shipment for the given date(s)",
        "code": "ex_availability"
      }
    }
  ]
}

Next steps