Contract
- shape
- collection
- authority
- read
- evidence
- none
- subscription
- false
- permission
- any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- list_purchase_orders
- REST
- POST https://api.containertradehq.com/v1/cap/list_purchase_orders
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| org_id | org_id | required | tradehq-org-id; 1 to 20 characters The org whose purchase orders they are. |
| filters | filters | optional | Purchase orders matching every term given. |
| q | text | optional | 1 to 64 characters The start of a purchase order number, a unit number on it or a supplier bill on it, case ignored. |
| sort | sort | optional | 1 to 1 items; default [{"key":"created_at","dir":"desc"}] One sort key and its direction. Newest purchase order first when left out. |
| fields | fields | optional | 1 to any number of items; unique; default ["booking_number","vendor","purchase_order_type","acquisition_channel","status","expires_at","created_at","updated_at","origin_market","origin_depot","origin_depot_name","pickup_date","destination_market","destination_depot","destination_depot_name","vendor_eta","transit_days","container_count","landed_count"] The fields to answer, from the field groups. All three groups when left out. |
| limit | integer | optional | 1 to 500; default 100 The page size. |
| after | cursor | optional | tradehq-keyset-cursor; up to 1024 characters The previous page's next_after. |
Paginated: cursor_input after · next next_after · page_max 500 · walk_max 10000 · ceiling declared
Response
items· object[]next_after· stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"intake_id": {
"type": "string",
"description": "The purchase order's id.",
"x-data-class": "operational"
},
"booking_number": {
"type": "string",
"description": "The purchase order number.",
"x-data-class": "operational"
},
"vendor": {
"type": [
"string",
"null"
],
"description": "The supplier contact.",
"x-data-class": "operational"
},
"purchase_order_type": {
"type": "string",
"description": "The inventory type, as recorded.",
"x-data-class": "operational"
},
"acquisition_channel": {
"type": [
"string",
"null"
],
"enum": [
"direct",
"gate-buy",
"yard-buy",
"consignment",
"factory-direct",
"inland-transfer",
"open-inventory",
null
],
"description": "How it sources its units; null for a lease or sublease.",
"x-data-class": "operational"
},
"status": {
"type": "string",
"enum": [
"pending",
"in-progress",
"completed",
"cancelled"
],
"description": "Where it stands.",
"x-data-class": "operational"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When its still-pending units are discarded as cancelled.",
"x-data-class": "operational"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When it was created.",
"x-data-class": "operational"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When it last changed.",
"x-data-class": "operational"
},
"origin_market": {
"type": [
"string",
"null"
],
"description": "The market its containers come from.",
"x-data-class": "operational"
},
"origin_depot": {
"type": [
"string",
"null"
],
"description": "The depot they are picked up at.",
"x-data-class": "operational"
},
"origin_depot_name": {
"type": [
"string",
"null"
],
"description": "That depot's name.",
"x-data-class": "operational"
},
"pickup_date": {
"type": [
"string",
"null"
],
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
"format": "date",
"description": "The day they are picked up (P/U Date).",
"x-data-class": "operational"
},
"destination_market": {
"type": [
"string",
"null"
],
"description": "The market they are delivered to.",
"x-data-class": "operational"
},
"destination_depot": {
"type": [
"string",
"null"
],
"description": "The depot they are delivered to.",
"x-data-class": "operational"
},
"destination_depot_name": {
"type": [
"string",
"null"
],
"description": "That depot's name.",
"x-data-class": "operational"
},
"vendor_eta": {
"type": [
"string",
"null"
],
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
"format": "date",
"description": "The day the supplier expects them at the destination (ETA).",
"x-data-class": "operational"
},
"transit_days": {
"type": [
"integer",
"null"
],
"description": "Days from P/U Date to ETA; null unless both are known.",
"x-data-class": "operational"
},
"container_count": {
"type": "integer",
"minimum": 0,
"description": "Its containers, not counting cancelled ones.",
"x-data-class": "operational"
},
"landed_count": {
"type": "integer",
"minimum": 0,
"description": "Of those, the ones no longer pending.",
"x-data-class": "operational"
}
},
"required": [
"intake_id"
],
"additionalProperties": false
},
"maxItems": 500
},
"next_after": {
"type": [
"string",
"null"
],
"description": "Pass as `after` for the next page; null on the last one."
}
},
"required": [
"items",
"next_after"
],
"additionalProperties": false
} Refusals
walk_ceiling_reached· 422 · the cursor walk has answered 10,000 rows, the most one walk answers
The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.
Surfaces
DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
- Voice: degraded: visualization
- Push: emits nothing
- OneBox: no document originates a purchase-order listing
- Outbound: a read emits nothing
Events
None emitted.