API reference

Quotes

Request route and parcel data; select a returned quote ID. Quotes expose only customer price. Sandbox estimates and prices are synthetic, valid for 15 minutes.

Local sandbox only

Set PX_BASE_URL to http://127.0.0.1:4010/v1. Intended live host: https://api.parcelxpert.com/v1. Live requests are not released. Set PX_IDEMPOTENCY_KEY to one stored unique value per write; replace all example quote and shipment IDs with returned IDs.

Get quotes

POST/v1/quotes

Local sandbox returns synthetic retail offers for domestic, international and multi-parcel requests. 15 minute enforced quote expiry. These prices are fixtures and cannot be used for live shipping. Live pricing adapter remains a launch gap. Production access remains disabled. Unreleased server adapters and database controls are under certification; hosted test credentials are unavailable.

Required scope: quotes:read

Request body

Field	Type	Description
`collection_country` required	string	ISO 3166-1 alpha-2 uppercase country code. Pattern: ^[A-Z]{2}$
`collection_postcode` required	string	Collection postcode; UK postcodes must have valid format.
`delivery_country` required	string	ISO 3166-1 alpha-2 uppercase country code. Pattern: ^[A-Z]{2}$
`delivery_postcode` required	string	Delivery postcode.
`parcels` required	array	Total consignment weight cannot exceed 1000 kg. Individual services may impose lower limits. Max items: 100
`parcels[].weight` required	number	Weight in kilograms.
`parcels[].length` required	number	Dimension in centimetres.
`parcels[].width` required	number	Dimension in centimetres.
`parcels[].height` required	number	Dimension in centimetres.

Response schema

Field	Type	Description
`data` required	array
`data[].id` required	string	PX quote identifier.
`data[].service_id` required	string	Opaque PX service identifier; does not identify a supplier account.
`data[].courier` required	string	Customer-facing courier.
`data[].service` required	string	Customer-facing service name.
`data[].handover` required	string	Values: collection, drop_off
`data[].price` required	object
`data[].price.total` required	number	Total retail customer price inclusive of applicable VAT. Minimum: 0
`data[].price.net` required	number	Minimum: 0
`data[].price.vat` required	number	Minimum: 0
`data[].price.currency` required	string	ISO 4217 currency. Pattern: ^[A-Z]{3}$
`data[].estimated_transit_days` required	integer \| null	Estimate, not a guarantee. Minimum: 1
`data[].expires_at` required	string	ISO 8601 timestamp with timezone. Responses use UTC Z.
`data[].capabilities` required	object
`data[].capabilities.collection` required	boolean
`data[].capabilities.label_formats` required	array
`data[].capabilities.customs_terms` required	array

HTTP responses and errors

200	Success.
400	Malformed JSON, cursor or idempotency header.
401	Missing, invalid, expired or revoked key.
403	Required scope not granted.
404	Resource unavailable in this account and environment, or label format unavailable.
405	Method not supported.
409	Idempotency conflict, request in progress, expired/mismatched quote or cancellation unavailable.
413	Body exceeds 256 KiB.
422	Schema or capability validation failure.
429	Enforced sandbox rate limit reached.
500	Unexpected PX failure.
502	Provider operation not confirmed. No blind booking retry.
503	Provider unavailable or live API not released.

Request example

curl --request POST \
  --url "$PX_BASE_URL/quotes" \
  --header "Authorization: Bearer $PX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "collection_country": "GB",
  "collection_postcode": "NN1 1AA",
  "delivery_country": "GB",
  "delivery_postcode": "SW1A 1AA",
  "parcels": [
    {
      "weight": 2,
      "length": 30,
      "width": 20,
      "height": 15
    }
  ]
}'

Response example

{
  "data": [
    {
      "id": "qt_00000000-0000-4000-8000-000000000001",
      "service_id": "svc_test_drop_off",
      "courier": "PX Sandbox Courier",
      "service": "Test drop-off",
      "handover": "drop_off",
      "price": {
        "total": 6,
        "net": 5,
        "vat": 1,
        "currency": "GBP"
      },
      "estimated_transit_days": 3,
      "expires_at": "2026-10-04T10:40:00Z",
      "capabilities": {
        "collection": false,
        "label_formats": [
          "a4"
        ],
        "customs_terms": [
          "DAP"
        ]
      }
    }
  ]
}