API reference

Collections

The local endpoint confirms the schedule already attached at booking. It does not modify or cancel collection. Live carrier-specific scheduling needs a separate reviewed adapter.

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.

Confirm collection schedule

POST/v1/shipments/{id}/collection

Sandbox only confirms the original schedule attached to creation. Changes and cancellation of collections are unsupported. Live carrier-specific collection creation remains a gap; do not treat this endpoint as universal modification. Production access remains disabled. Unreleased server adapters and database controls are under certification; hosted test credentials are unavailable.

Required scope: collections:write

Parameters

Name	Location	Meaning
id required	path	PX resource ID, scoped to account and environment.
Idempotency-Key required	header	8–128 ASCII letters, digits, underscore, dot, colon or hyphen. Account/environment/operation scoped; never reuse for a different request. Sandbox retains keys until reset.

Request body

Field	Type	Description
`date` required	string	Collection date in origin local calendar.
`ready_time` required	string	Origin local time HH:mm. Pattern: ^([01]\d\|2[0-3]):[0-5]\d$
`close_time` required	string	Origin local closing time HH:mm, later than ready_time. Pattern: ^([01]\d\|2[0-3]):[0-5]\d$

Response schema

Field	Type	Description
`shipment_id` required	string	PX shipment ID.
`date` required	string	Local date.
`ready_time` required	string	HH:mm
`close_time` required	string	HH:mm
`status` required	string	Schedule state.

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/shipments/$PX_SHIPMENT_ID/collection" \
  --header "Authorization: Bearer $PX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $PX_IDEMPOTENCY_KEY" \
  --data '{
  "date": "2026-10-05",
  "ready_time": "09:00",
  "close_time": "17:00"
}'

Response example

{
  "shipment_id": "shp_00000000-0000-4000-8000-000000000002",
  "date": "2026-10-05",
  "ready_time": "09:00",
  "close_time": "17:00",
  "status": "scheduled"
}