list_supplier_posts · List a purchase order's supplier updates

Contract

shape: collection
authority: read
evidence: none
subscription: false
permission: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); 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_supplier_posts
REST: POST https://api.containertradehq.com/v1/cap/list_supplier_posts

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.
document_id	text	required	1 to 64 characters The purchase order's id (an asset_intake). One of another org, or none, lists nothing.
limit	integer	optional	1 to 100; default 50 The page size.
after	text	optional	1 to 20 characters The previous page's next_after. A post id that is not one of this purchase order's ends the listing: an empty page.

Paginated: next next_after · page_max 100 · 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": {
          "post_id": {
            "type": "string",
            "description": "The post.",
            "x-data-class": "operational"
          },
          "kind": {
            "type": "string",
            "enum": [
              "confirmation",
              "production_status",
              "serial_batch"
            ],
            "description": "confirmation, production_status or serial_batch.",
            "x-data-class": "operational"
          },
          "party_name": {
            "type": "string",
            "description": "The supplier party that posted it.",
            "x-data-class": "operational"
          },
          "guest_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The guest who posted it, when a guest did; null for a member of the supplier's own org.",
            "x-data-class": "operational"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "A production status's status (scheduled, in_production, produced, ready_for_pickup, delayed); null for the other kinds.",
            "x-data-class": "operational"
          },
          "vendor_eta": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "format": "date",
            "description": "The ready date given, if any.",
            "x-data-class": "operational"
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "A production status's note, if any.",
            "x-data-class": "operational"
          },
          "unit_count": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "Units confirmed, or unit numbers submitted; null for a production status.",
            "x-data-class": "operational"
          },
          "posted_at": {
            "type": "string",
            "format": "date-time",
            "description": "When.",
            "x-data-class": "operational"
          },
          "ingest_document_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The confirmation's ingest document, which the PO ingest apply takes; null for a production status.",
            "x-data-class": "operational"
          },
          "applied": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "For a confirmation or serial batch, whether the buyer has applied the confirmation; null for a production status.",
            "x-data-class": "operational"
          },
          "applied_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the buyer applied the confirmation, for a confirmation or serial batch it has applied; null otherwise.",
            "x-data-class": "operational"
          },
          "pro_forma": {
            "type": [
              "string",
              "null"
            ],
            "description": "A confirmation's pro forma number, if the supplier gave one; null for the other kinds.",
            "x-data-class": "operational"
          },
          "changes": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "For a confirmation, every confirmed line that differs from the ordered line at its position: {line, fields, ordered, confirmed}, fields naming what changed of size, type, condition, color, quantity and unit_price. Empty for the other kinds.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "post_id",
          "kind",
          "party_name",
          "guest_name",
          "status",
          "vendor_eta",
          "note",
          "unit_count",
          "posted_at",
          "ingest_document_id",
          "applied",
          "applied_at",
          "pro_forma",
          "changes"
        ],
        "additionalProperties": false
      },
      "maxItems": 100
    },
    "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

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: the supplier posts these; no inbound document originates one
Outbound: the buyer reads them; nothing is sent

Events

None emitted.

confirm_purchase_order, get_supplier_purchase_order, list_purchase_orders, post_production_status, submit_serial_batch