Quotes

Shipstack asks each enabled courier in parallel under a fixed latency budget and merges the answers. Rates come back sorted cheapest first. A courier that fails or times out is reported in failures, it never fails the request.

Request

Address

Parcel

A domestic quote

curl -X POST https://api.shipstack.example/v1/quotes \
  -H "Authorization: Bearer $SHIPSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "name": "Acme Supplies", "line1": "1 Mill Lane",
      "city": "Leeds", "postcode": "LS1 4DL", "country": "GB"
    },
    "to": {
      "name": "Sam Reed", "line1": "44 Bright Street",
      "city": "Bristol", "postcode": "BS1 5TR", "country": "GB",
      "residential": true
    },
    "parcels": [
      { "weight_g": 1200, "length_mm": 300, "width_mm": 200,
        "height_mm": 100, "reference": "ORDER-10432" }
    ],
    "options": { "signature_required": true }
  }'

Response

Each rate carries the carrier's own service_code, which is what you quote back when buying the label. surcharges itemises what makes up the total beyond the base rate.

{
  "rates": [
    {
      "courier": "royalmail_clickanddrop",
      "service_code": "TPS48",
      "service_name": "Royal Mail Tracked 48 Signature",
      "total": { "amount": 489, "currency": "GBP" },
      "estimated_days": 2
    },
    {
      "courier": "dpd",
      "service_code": "1^12",
      "service_name": "DPD Next Day by 12:00",
      "total": { "amount": 899, "currency": "GBP" },
      "estimated_days": 1,
      "delivery_by": "2026-09-02T12:00:00Z",
      "surcharges": [
        { "code": "FUEL", "name": "Fuel surcharge",
          "amount": { "amount": 74, "currency": "GBP" } }
      ]
    }
  ],
  "failures": [
    { "courier": "ups", "reason": "upstream timeout" }
  ]
}

delivery_by appears only when the carrier gives a firm commitment rather than an estimate. Express services do, economy services usually do not.

Service options

Options are validated against what the chosen carrier actually supports before any network call, so an unsupported combination fails immediately rather than as an opaque carrier error.

International and customs

Crossing a customs border requires a customs object and itemised contents on every parcel. Without them the request is rejected before it reaches a carrier.

{
  "customs": {
    "content_type": "merchandise",
    "incoterm": "DAP",
    "invoice_number": "INV-2026-0912",
    "reason": "sale"
  },
  "parcels": [
    {
      "weight_g": 800, "length_mm": 250, "width_mm": 180, "height_mm": 60,
      "contents": [
        {
          "description": "Cotton t-shirt",
          "quantity": 2,
          "value": { "amount": 1200, "currency": "GBP" },
          "weight_g": 320,
          "hs_code": "610910",
          "origin_country": "GB",
          "sku": "TS-01"
        }
      ]
    }
  ]
}

content_type is one of merchandise, gift, sample, documents or return. incoterm decides who pays duty: DAP means the recipient pays, DDP means you do.

Pickup points

A locker or parcel shop is a destination, not an option. Set deliver_to to route the parcel there, and keep to as the recipient's own address, because carriers still use it for notifications and returns.

{
  "deliver_to": {
    "id": "GB-12345",
    "type": "locker",
    "name": "Bright Street Locker"
  }
}

Types are locker, shop, post_office and depot. A carrier that does not serve the requested type, or a parcel too large for the locker, is rejected before any network call.

Multi-piece consignments

Send several parcels in one parcels array to quote them as a single consignment. Carriers that do not support multi-piece are skipped rather than quoting a wrong price; see the capability matrix for which do.