get_purchase_order_suggestions · Get purchase order suggestions

Contract

shape: entity
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: get_purchase_order_suggestions
REST: POST https://api.containertradehq.com/v1/cap/get_purchase_order_suggestions

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 are read.
supplier_id	text	optional	1 to 20 characters The supplier's contact id, as a purchase order names its supplier. Absent, supplier is null.
origin_market	text	optional	1 to 128 characters The lane's origin market. Absent, lane is null.
destination_market	text	optional	1 to 128 characters The lane's destination market. Absent, lane is null.

Response

supplier · objectnull · {origin_market, origin_yard_id, origin_yard_name, purchase_orders}: the supplier's most frequent origin yard, its market and name, and how many of the org's purchase orders from the supplier name it. Null with no supplier_id or fewer than 3.
lane · objectnull · {median_days, purchase_orders}: the median whole days from P/U Date to the first gate-in at a depot in the destination market, and how many purchase orders on the lane had both. Null without both markets or fewer than 3.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "supplier": {
      "type": [
        "object",
        "null"
      ],
      "description": "{origin_market, origin_yard_id, origin_yard_name, purchase_orders}: the supplier's most frequent origin yard, its market and name, and how many of the org's purchase orders from the supplier name it. Null with no supplier_id or fewer than 3.",
      "x-data-class": "operational"
    },
    "lane": {
      "type": [
        "object",
        "null"
      ],
      "description": "{median_days, purchase_orders}: the median whole days from P/U Date to the first gate-in at a depot in the destination market, and how many purchase orders on the lane had both. Null without both markets or fewer than 3.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "supplier",
    "lane"
  ],
  "additionalProperties": false
}

Refusals

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileF

APIF

MCPF

VoiceF

PushN

OneBoxN

OutboundN

Push: emits nothing
OneBox: a suggestion is read while a purchase order is entered; no document originates it
Outbound: a read emits nothing

Events

None emitted.

None.