API reference

Orders

Generic imported-order resources exclude marketplace tokens and raw data. The sandbox contains a synthetic Shopify order. Link one order with order_id during creation; duplicate links return a conflict.

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.

List imported orders

GET/v1/orders

Local sandbox seeds a synthetic Shopify order; no marketplace OAuth or credentials. The unreleased current-domain read adapter returns tenant-owned marketplace order fields only; test credentials cannot read live orders. Hosted access remains disabled. OAuth integration setup is separate from REST V1.

Required scope: orders:read

Parameters

Name	Location	Meaning
limit optional	query	Page size. Default 20; maximum 100.
cursor optional	query	Opaque signed next_cursor. Preserve filters between pages.
status optional	query	Exact normalized status.
created_from optional	query	Inclusive creation timestamp.
created_to optional	query	Inclusive creation timestamp.

Response schema

Field	Type	Description
`data` required	array
`data[].id` required	string	PX imported order ID.
`data[].merchant_reference` required	string	Merchant order reference.
`data[].platform` required	string	Values: shopify, ebay, woocommerce, square, big_cartel
`data[].status` required	string	Normalized fulfilment state.
`data[].shipment_id` required	string \| null
`data[].created_at` required	string	ISO 8601 timestamp with timezone. Responses use UTC Z.
`pagination` required	object
`pagination.limit` required	integer	Minimum: 1
`pagination.next_cursor` required	string \| null
`pagination.has_more` required	boolean

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/orders" \
  --header "Authorization: Bearer $PX_API_KEY"

Response example

{
  "data": [
    {
      "id": "ord_test_1",
      "merchant_reference": "ORDER-1001",
      "platform": "shopify",
      "status": "unfulfilled",
      "shipment_id": null,
      "created_at": "2026-10-04T10:25:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "next_cursor": null,
    "has_more": false
  }
}

Retrieve imported order

GET/v1/orders/{id}

Local sandbox supports order_id linkage during shipment creation. The unreleased domain adapter reads tenant-owned imported orders but rejects imported-order booking until fulfilment/linkage authority is certified. OAuth integration setup is separate. Production and hosted test access remain disabled.