Book a demo

submit_serial_batch

Submit unit numbers against a confirmed purchase order

act collection controlled-share since 2026-10-01

For the supplier of an org's purchase order that it has confirmed: sends the ISO 6346 unit numbers of the containers it is supplying. Every number's check digit is validated before any is accepted. The numbers go onto the confirmation's staged rows in the buyer's PO ingest, filling its lines in order, so the buyer's apply creates each container with its number. Refused once the buyer has applied the confirmation, for a unit already submitted, and for more units than the confirmation has left to number.

Contract

shape
collection
authority
act
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
keyed
emits
po.serials_submitted
MCP tool
submit_serial_batch
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/submit_serial_batch

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org that owns the purchase order: the buyer.
document_kindone_ofrequiredone of asset_intake, order
asset_intake: a purchase order. An order is refused.
document_idtextrequired1 to 64 characters
The purchase order's id.
unit_numbersunit_numbersrequired1 to 500 items; unique
The unit numbers, in the order to fill the confirmation's lines: each ISO 6346, owner code, category, serial and check digit. Either case is accepted and stored upper case; one unit twice, in any case, is refused.

Paginated: next next_after · ceiling not_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 batch.",
            "x-data-class": "operational"
          },
          "unit_number": {
            "type": "string",
            "description": "One unit number, accepted.",
            "x-data-class": "operational"
          },
          "ingest_row_id": {
            "type": "string",
            "description": "The staged ingest_purchase_orders row that now carries it.",
            "x-data-class": "operational"
          },
          "ingest_document_id": {
            "type": "string",
            "description": "The confirmation's ingest document.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "post_id",
          "unit_number",
          "ingest_row_id",
          "ingest_document_id"
        ],
        "additionalProperties": false
      }
    },
    "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

not yet declared

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

Surfaces

DesktopF
MobileN
APIF
MCPF*
VoiceN
PushF
OneBoxN
OutboundN
  • Mobile: a serial batch is a list pasted or exported from the supplier's own system; D1 at best on a phone, and not built
  • MCP: approval required
  • Voice: hundreds of eleven-character unit numbers are not dictated; D1 at best
  • OneBox: a serial list is posted by the supplier, never ingested from an inbound document here
  • Outbound: nothing is sent: the units land on the buyer's staged rows

Events

Related

confirm_purchase_order, get_supplier_purchase_order, list_supplier_posts, post_production_status