summarize_inventory · Summarize inventory

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

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 inventory it is.
filters	filters	optional	Units matching every term given. With no acquisition term, units pending or acquired.
q	text	optional	1 to 64 characters The start of a BIC number, booking number, release booking number, intake id, vendor bill id or invoice number.

Response

total · integer · The units matching the filters.
total_cost_min · value · The lowest total cost among them in USD, as a decimal string; null when none carries one.
total_cost_max · value · The highest, as a decimal string.
total_cost_avg · value · The average, to four places, as a decimal string.
lanes · object[] · The units by lane, an origin market and a destination market, most units first and at most 100: each lane's unit count, and the median transit days (P/U Date to vendor ETA) over its purchase orders, null below three purchase orders. A unit with no origin or no destination market is on no lane.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "total": {
      "type": "integer",
      "minimum": 0,
      "description": "The units matching the filters.",
      "x-data-class": "operational"
    },
    "total_cost_min": {
      "anyOf": [
        {
          "type": [
            "string",
            "null"
          ]
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The lowest total cost among them in USD, as a decimal string; null when none carries one.",
      "x-data-class": "commercial"
    },
    "total_cost_max": {
      "anyOf": [
        {
          "type": [
            "string",
            "null"
          ]
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The highest, as a decimal string.",
      "x-data-class": "commercial"
    },
    "total_cost_avg": {
      "anyOf": [
        {
          "type": [
            "string",
            "null"
          ]
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The average, to four places, as a decimal string.",
      "x-data-class": "commercial"
    },
    "lanes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "origin_market": {
            "type": "string",
            "description": "Where the lane's units are picked up."
          },
          "destination_market": {
            "type": "string",
            "description": "The market they are bought into."
          },
          "units": {
            "type": "integer",
            "minimum": 1,
            "description": "The units on the lane."
          },
          "purchase_orders": {
            "type": "integer",
            "minimum": 0,
            "description": "The purchase orders on the lane with a P/U Date and an ETA: the sample the median reads."
          },
          "median_transit_days": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The median of those purchase orders' transit days, in whole days; null below three purchase orders."
          }
        },
        "required": [
          "origin_market",
          "destination_market",
          "units",
          "purchase_orders",
          "median_transit_days"
        ],
        "additionalProperties": false
      },
      "description": "The units by lane, an origin market and a destination market, most units first and at most 100: each lane's unit count, and the median transit days (P/U Date to vendor ETA) over its purchase orders, null below three purchase orders. A unit with no origin or no destination market is on no lane.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "total",
    "total_cost_min",
    "total_cost_max",
    "total_cost_avg",
    "lanes"
  ],
  "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: no document originates an inventory summary
Outbound: a read emits nothing

Events

None emitted.

list_catalog, list_inventory, list_shared_catalog, summarize_catalog