API reference

Tracking

Read persisted normalized events. UTC instants are preserved across UK daylight-saving time. Duplicate equivalent instants are suppressed; timezone-naive input is not guessed.

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.

Retrieve tracking

GET/v1/shipments/{id}/tracking

Returns persisted normalized events with UTC ISO 8601 timestamps. No carrier call on GET. Equivalent instants and descriptions are deduplicated; naive timestamps are excluded rather than interpreted as UTC. Production access remains disabled. Unreleased server adapters and database controls are under certification; hosted test credentials are unavailable.

Required scope: tracking:read

Parameters

Name	Location	Meaning
id required	path	PX resource ID, scoped to account and environment.

Response schema

Field	Type	Description
`shipment_id` required	string	PX shipment ID.
`reference` required	string	PX reference.
`tracking_number` required	string \| null
`status` required	string	Current PX status.
`events` required	array
`events[].status` required	string	Normalized PX status.
`events[].description` required	string	Event description.
`events[].timestamp` required	string	ISO 8601 timestamp with timezone. Responses use UTC Z.
`events[].location` required	string	Display location or empty string.

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 GET \
  --url "$PX_BASE_URL/shipments/$PX_SHIPMENT_ID/tracking" \
  --header "Authorization: Bearer $PX_API_KEY"

Response example

{
  "shipment_id": "shp_00000000-0000-4000-8000-000000000002",
  "reference": "PX-TEST-000001",
  "tracking_number": "TEST001",
  "status": "booked",
  "events": [
    {
      "status": "label_ready",
      "description": "Test label created. No carrier purchase.",
      "timestamp": "2026-10-04T10:25:00Z",
      "location": ""
    }
  ]
}

Find tracking by number

GET/v1/tracking/{tracking_number}

Account-scoped primary-number lookup. The local sandbox returns 404 for unknown or ambiguous numbers; the unreleased domain adapter returns 404 for unknown and 409 for ambiguous numbers. Shipment ID lookup is preferred for multi-parcel consignments. Production access remains disabled; hosted test credentials are unavailable.