get_supplier_purchase_order · Get a purchase order as its supplier

Contract

shape: entity
authority: read
evidence: none
subscription: false
permission: any one of: org.guest (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); counterparty (org.member carried by the caller's role template in an org that holds a seat on the document; it reads its own seat); a deactivated caller is refused first
idempotency: safe
emits: none
MCP tool: get_supplier_purchase_order
REST: POST https://api.containertradehq.com/v1/cap/get_supplier_purchase_order

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 that owns the purchase order: the buyer.
document_kind	one_of	required	one of asset_intake, order asset_intake: a purchase order. An order is refused.
document_id	text	required	1 to 64 characters The purchase order's id.

Response

org_id · string · The buyer.
document_id · string · The purchase order.
reference · string · The purchase order's PO number, else its booking number, else its id.
status · string · pending, in_progress, completed or cancelled.
buyer_name · string · The buyer org's name.
placed_at · string · When the buyer placed it.
delivery_depot · stringnull · The depot the units are delivered to, by name; null when none is set.
purchase_order_type · stringnull · The purchase order's type.
party_id · string · The supplier party the caller reads as.
party_name · string · Its name.
ordered_lines · object[] · The lines as the buyer ordered them, in order: {size, type, condition, color, quantity, unit_price, currency}, unit_price a decimal string or null.
confirmation · objectnull · The confirmation the party posted, or null: {post_id, lines (each {size, type, condition, color, quantity, unit_price}), changes (each {line, fields, ordered, confirmed}: a confirmed line that differs from the ordered line at its position, fields naming what changed), pro_forma, vendor_eta, posted_at, posted_by_name, applied, ingest_document_id}. applied is whether the buyer has taken it up.
posts · object[] · Every post the party made on the purchase order, newest first: {post_id, kind (confirmation, production_status or serial_batch), status (a production status, else null), vendor_eta, note, unit_count, posted_at}.
units · object · {confirmed, submitted, numbers}: the units confirmed, how many have a unit number, and each number as {unit_number, line, size, type, condition, color, submitted_at}, in the order submitted.
next_step · string · What the supplier does next: the capability that does it, or nothing once the purchase order is closed or the buyer has applied the confirmation.
vocabulary · object · The values a confirmed line's size, type, condition and color are held to: {size, type, condition, color}, each a list of {value, label}.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The buyer.",
      "x-data-class": "operational"
    },
    "document_id": {
      "type": "string",
      "description": "The purchase order.",
      "x-data-class": "operational"
    },
    "reference": {
      "type": "string",
      "description": "The purchase order's PO number, else its booking number, else its id.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "description": "pending, in_progress, completed or cancelled.",
      "x-data-class": "operational"
    },
    "buyer_name": {
      "type": "string",
      "description": "The buyer org's name.",
      "x-data-class": "operational"
    },
    "placed_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the buyer placed it.",
      "x-data-class": "operational"
    },
    "delivery_depot": {
      "type": [
        "string",
        "null"
      ],
      "description": "The depot the units are delivered to, by name; null when none is set.",
      "x-data-class": "operational"
    },
    "purchase_order_type": {
      "type": [
        "string",
        "null"
      ],
      "description": "The purchase order's type.",
      "x-data-class": "operational"
    },
    "party_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The supplier party the caller reads as.",
      "x-data-class": "operational"
    },
    "party_name": {
      "type": "string",
      "description": "Its name.",
      "x-data-class": "operational"
    },
    "ordered_lines": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "The lines as the buyer ordered them, in order: {size, type, condition, color, quantity, unit_price, currency}, unit_price a decimal string or null.",
      "x-data-class": "operational"
    },
    "confirmation": {
      "type": [
        "object",
        "null"
      ],
      "description": "The confirmation the party posted, or null: {post_id, lines (each {size, type, condition, color, quantity, unit_price}), changes (each {line, fields, ordered, confirmed}: a confirmed line that differs from the ordered line at its position, fields naming what changed), pro_forma, vendor_eta, posted_at, posted_by_name, applied, ingest_document_id}. applied is whether the buyer has taken it up.",
      "x-data-class": "operational"
    },
    "posts": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Every post the party made on the purchase order, newest first: {post_id, kind (confirmation, production_status or serial_batch), status (a production status, else null), vendor_eta, note, unit_count, posted_at}.",
      "x-data-class": "operational"
    },
    "units": {
      "type": "object",
      "description": "{confirmed, submitted, numbers}: the units confirmed, how many have a unit number, and each number as {unit_number, line, size, type, condition, color, submitted_at}, in the order submitted.",
      "x-data-class": "operational"
    },
    "next_step": {
      "type": "string",
      "enum": [
        "confirm_purchase_order",
        "submit_serial_batch",
        "post_production_status",
        "nothing"
      ],
      "description": "What the supplier does next: the capability that does it, or nothing once the purchase order is closed or the buyer has applied the confirmation.",
      "x-data-class": "operational"
    },
    "vocabulary": {
      "type": "object",
      "description": "The values a confirmed line's size, type, condition and color are held to: {size, type, condition, color}, each a list of {value, label}.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "document_id",
    "reference",
    "status",
    "buyer_name",
    "placed_at",
    "delivery_depot",
    "purchase_order_type",
    "party_id",
    "party_name",
    "ordered_lines",
    "confirmation",
    "posts",
    "units",
    "next_step",
    "vocabulary"
  ],
  "additionalProperties": false
}

Refusals

several_seller_parties · 422 · the caller belongs to more than one org seated as this purchase order's seller; read it from a session in one of them

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: a supplier reads its purchase order here; no inbound document originates it
Outbound: the supplier reads; nothing is sent

Events

None emitted.

confirm_purchase_order, list_supplier_posts, post_production_status, submit_serial_batch