REST API for programmatic access to Kargo platform resources. Accepts a single flattened document carrying shipment, order and order-item data, or a shipment-level document with multiple orders, and upserts it against the Kargo platform. Also carries the SKU master surface. JSON and XML request bodies, RFC 9457 problem+json errors, and an interactive Swagger reference.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/kargo-document-intake-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.1.0
info:
title: Kargo Document Intake API
version: 1.0.0
description: >
Accepts either a single flattened "document" that may carry shipment,
order, and order item data, or a shipment level document with multiple
orders in `orders`.
For the existing single order format, the document is upserted against an
existing order by `orderNumber`; if no such order exists a new one is
created, which also creates the associated shipment.
For the multi order format, the API processes every entry in `orders` against
the same shipment level fields, such as `business`, `facility`, `direction`,
and `shipmentNumber`.
`business`, `facility`, and `direction` are always required. Single order
requests require top level `orderNumber`; multi order requests require
`shipmentNumber` and a non-empty `orders` list, and each order in the list
requires `orderNumber`.
For client generation or local tooling, download the [OpenAPI YAML spec](/v1/docs/openapi.yaml).
See the [Document Intake API Handbook](https://docs.kargo.ai/rest-api) for examples and workflow details.
servers:
- url: /v1
tags:
- name: Documents
- name: SKU Master
security:
- bearerAuth: []
paths:
/documents:
post:
operationId: createDocument
summary: Create or update a document (shipment / order / order items)
description: >
Accepts either the existing single order document format or a shipment
level document containing multiple orders in `orders`. In single order
mode, the API upserts an order identified by the top level `orderNumber`.
In multi order mode, the API processes each `orders[]` entry against the
same shipment level fields. For `MERGE` and `DELETE`, order items are
identified by `lpn` + `sku`. Returns a summary of every entity created,
updated, or removed.
tags: [Documents]
parameters:
- name: Correlation-Id
in: header
required: false
description: >
Client provided identifier used for request tracing and logging.
When supplied, Kargo returns the same value in the response.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
examples:
orderWithFivePallets:
summary: Create an outbound order with five pallet items
description: >
This example omits `orderItemUpdateStrategy`; when `items` are provided
without a strategy, Kargo defaults to `OVERWRITE`.
value:
orderNumber: TEST-EXAMPLE-ORDER-001
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
items:
- lpn: LPNABC
sku: SKU123
quantity: 10
quantityUnit: CASE
caseSerials:
- id: "00000000000379386070"
quantity: 10
- lpn: LPNABC
sku: SKU456
quantity: 8
quantityUnit: CASE
- lpn: LPNDEF
sku: SKU789
quantity: 12
quantityUnit: CASE
- lpn: LPNGHI
sku: SKU123
quantity: 6
quantityUnit: CASE
- lpn: LPNJKL
sku: SKU999
quantity: 15
quantityUnit: CASE
appendOrderItem:
summary: Append an order item
value:
orderNumber: TEST-EXAMPLE-ORDER-001
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
orderItemUpdateStrategy: APPEND
items:
- lpn: LPNNEW
sku: SKUAPPEND
quantity: 1
quantityUnit: UNIT
mergeOrderItemByLpnAndSku:
summary: Update or add an order item by LPN + SKU
value:
orderNumber: TEST-EXAMPLE-ORDER-001
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
orderItemUpdateStrategy: MERGE
items:
- lpn: LPNABC
sku: SKU123
quantity: 5
quantityUnit: CASE
deleteOrderItemByLpnAndSku:
summary: Delete an order item by LPN + SKU
value:
orderNumber: TEST-EXAMPLE-ORDER-001
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
orderItemUpdateStrategy: DELETE
items:
- lpn: LPNABC
sku: SKU123
overwriteOrderItems:
summary: Replace all order items
value:
orderNumber: TEST-EXAMPLE-ORDER-001
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
orderItemUpdateStrategy: OVERWRITE
items:
- lpn: LPNREPLACE001
sku: SKUREPLACE001
quantity: 2
quantityUnit: UNIT
- lpn: LPNREPLACE002
sku: SKUREPLACE002
quantity: 3
quantityUnit: CASE
shipmentWithMultipleOrders:
summary: Shipment with multiple orders
description: >
Creates or updates multiple orders on the same shipment. Each
order is identified by `orderNumber`. Because `orderItemUpdateStrategy` is omitted,
the API defaults to `OVERWRITE` when applying the provided items.
value:
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
orders:
- orderNumber: TEST-EXAMPLE-ORDER-001
items:
- lpn: LPNMULTI001
sku: SKUMULTI001
quantity: 10
quantityUnit: CASE
caseSerials:
- id: "00000000000379386070"
quantity: 10
- orderNumber: TEST-EXAMPLE-ORDER-002
items:
- lpn: LPNMULTI002
sku: SKUMULTI002
quantity: 8
quantityUnit: CASE
shipmentWithMultipleOrdersShipmentLevelStrategy:
summary: Shipment with multiple orders using shipment level strategy
description: >
Processes multiple orders on the same shipment. The top level
`orderItemUpdateStrategy` is used as the default strategy for
every order because the orders do not provide their own
strategy.
value:
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
orderItemUpdateStrategy: MERGE
orders:
- orderNumber: TEST-EXAMPLE-ORDER-001
items:
- lpn: LPNMULTI101
sku: SKUMULTI101
quantity: 10
quantityUnit: CASE
- orderNumber: TEST-EXAMPLE-ORDER-002
items:
- lpn: LPNMULTI102
sku: SKUMULTI102
quantity: 8
quantityUnit: CASE
shipmentWithMultipleOrdersOrderLevelStrategies:
summary: Shipment with multiple orders using order level strategies
description: >
Processes multiple orders on the same shipment. Each order
provides its own `orderItemUpdateStrategy`, so no top level
strategy is needed.
value:
business: kargo
facility: sf
direction: OUTBOUND
shipmentNumber: TEST-EXAMPLE-SHIPMENT-001
orders:
- orderNumber: TEST-EXAMPLE-ORDER-001
orderItemUpdateStrategy: APPEND
items:
- lpn: LPNMULTI201
sku: SKUMULTI201
quantity: 4
quantityUnit: CASE
- orderNumber: TEST-EXAMPLE-ORDER-002
orderItemUpdateStrategy: DELETE
items:
- lpn: LPNMULTI202
sku: SKUMULTI202
application/xml:
schema:
$ref: '#/components/schemas/Document'
examples:
orderWithFivePallets:
summary: Create an outbound XML order with five pallet items
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<items>
<lpn>LPNABC</lpn>
<sku>SKU123</sku>
<quantity>10</quantity>
<quantityUnit>CASE</quantityUnit>
<caseSerials>
<id>00000000000379386070</id>
<quantity>10</quantity>
</caseSerials>
</items>
<items>
<lpn>LPNABC</lpn>
<sku>SKU456</sku>
<quantity>8</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
<items>
<lpn>LPNDEF</lpn>
<sku>SKU789</sku>
<quantity>12</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
<items>
<lpn>LPNGHI</lpn>
<sku>SKU123</sku>
<quantity>6</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
<items>
<lpn>LPNJKL</lpn>
<sku>SKU999</sku>
<quantity>15</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</Document>
appendOrderItem:
summary: Append an order item
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>
<items>
<lpn>LPNNEW</lpn>
<sku>SKUAPPEND</sku>
<quantity>1</quantity>
<quantityUnit>UNIT</quantityUnit>
</items>
</Document>
mergeOrderItemByLpnAndSku:
summary: Update or add an order item by LPN + SKU
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>
<items>
<lpn>LPNABC</lpn>
<sku>SKU123</sku>
<quantity>5</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</Document>
deleteOrderItemByLpnAndSku:
summary: Delete an order item by LPN + SKU
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>
<items>
<lpn>LPNABC</lpn>
<sku>SKU123</sku>
</items>
</Document>
overwriteOrderItems:
summary: Replace all order items
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>OVERWRITE</orderItemUpdateStrategy>
<items>
<lpn>LPNREPLACE001</lpn>
<sku>SKUREPLACE001</sku>
<quantity>2</quantity>
<quantityUnit>UNIT</quantityUnit>
</items>
<items>
<lpn>LPNREPLACE002</lpn>
<sku>SKUREPLACE002</sku>
<quantity>3</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</Document>
shipmentWithMultipleOrders:
summary: Shipment with multiple orders
description: >
Creates or updates multiple orders on the same shipment. Each
order is identified by `orderNumber`. Because `orderItemUpdateStrategy` is omitted,
the API defaults to `OVERWRITE` when applying the provided items.
value: |
<Document>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<items>
<lpn>LPNMULTI001</lpn>
<sku>SKUMULTI001</sku>
<quantity>10</quantity>
<quantityUnit>CASE</quantityUnit>
<caseSerials>
<id>00000000000379386070</id>
<quantity>10</quantity>
</caseSerials>
</items>
</orders>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>
<items>
<lpn>LPNMULTI002</lpn>
<sku>SKUMULTI002</sku>
<quantity>8</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
</Document>
shipmentWithMultipleOrdersShipmentLevelStrategy:
summary: Shipment with multiple orders using shipment level strategy
description: >
Processes multiple orders on the same shipment. The top level
`orderItemUpdateStrategy` is used as the default strategy for
every order because the orders do not provide their own
strategy.
value: |
<Document>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<items>
<lpn>LPNMULTI101</lpn>
<sku>SKUMULTI101</sku>
<quantity>10</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>
<items>
<lpn>LPNMULTI102</lpn>
<sku>SKUMULTI102</sku>
<quantity>8</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
</Document>
shipmentWithMultipleOrdersOrderLevelStrategies:
summary: Shipment with multiple orders using order level strategies
description: >
Processes multiple orders on the same shipment. Each order
provides its own `orderItemUpdateStrategy`, so no top level
strategy is needed.
value: |
<Document>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>
<items>
<lpn>LPNMULTI201</lpn>
<sku>SKUMULTI201</sku>
<quantity>4</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>
<orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>
<items>
<lpn>LPNMULTI202</lpn>
<sku>SKUMULTI202</sku>
</items>
</orders>
</Document>
text/xml:
schema:
$ref: '#/components/schemas/Document'
examples:
orderWithFivePallets:
summary: Create an outbound XML order with five pallet items
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<items>
<lpn>LPNABC</lpn>
<sku>SKU123</sku>
<quantity>10</quantity>
<quantityUnit>CASE</quantityUnit>
<caseSerials>
<id>00000000000379386070</id>
<quantity>10</quantity>
</caseSerials>
</items>
<items>
<lpn>LPNABC</lpn>
<sku>SKU456</sku>
<quantity>8</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
<items>
<lpn>LPNDEF</lpn>
<sku>SKU789</sku>
<quantity>12</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
<items>
<lpn>LPNGHI</lpn>
<sku>SKU123</sku>
<quantity>6</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
<items>
<lpn>LPNJKL</lpn>
<sku>SKU999</sku>
<quantity>15</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</Document>
appendOrderItem:
summary: Append an order item
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>
<items>
<lpn>LPNNEW</lpn>
<sku>SKUAPPEND</sku>
<quantity>1</quantity>
<quantityUnit>UNIT</quantityUnit>
</items>
</Document>
mergeOrderItemByLpnAndSku:
summary: Update or add an order item by LPN + SKU
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>
<items>
<lpn>LPNABC</lpn>
<sku>SKU123</sku>
<quantity>5</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</Document>
deleteOrderItemByLpnAndSku:
summary: Delete an order item by LPN + SKU
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>
<items>
<lpn>LPNABC</lpn>
<sku>SKU123</sku>
</items>
</Document>
overwriteOrderItems:
summary: Replace all order items
value: |
<Document>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>OVERWRITE</orderItemUpdateStrategy>
<items>
<lpn>LPNREPLACE001</lpn>
<sku>SKUREPLACE001</sku>
<quantity>2</quantity>
<quantityUnit>UNIT</quantityUnit>
</items>
<items>
<lpn>LPNREPLACE002</lpn>
<sku>SKUREPLACE002</sku>
<quantity>3</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</Document>
shipmentWithMultipleOrders:
summary: Shipment with multiple orders
description: >
Creates or updates multiple orders on the same shipment. Each
order is identified by `orderNumber`. Because `orderItemUpdateStrategy` is omitted,
the API defaults to `OVERWRITE` when applying the provided items.
value: |
<Document>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<items>
<lpn>LPNMULTI001</lpn>
<sku>SKUMULTI001</sku>
<quantity>10</quantity>
<quantityUnit>CASE</quantityUnit>
<caseSerials>
<id>00000000000379386070</id>
<quantity>10</quantity>
</caseSerials>
</items>
</orders>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>
<items>
<lpn>LPNMULTI002</lpn>
<sku>SKUMULTI002</sku>
<quantity>8</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
</Document>
shipmentWithMultipleOrdersShipmentLevelStrategy:
summary: Shipment with multiple orders using shipment level strategy
description: >
Processes multiple orders on the same shipment. The top level
`orderItemUpdateStrategy` is used as the default strategy for
every order because the orders do not provide their own
strategy.
value: |
<Document>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<items>
<lpn>LPNMULTI101</lpn>
<sku>SKUMULTI101</sku>
<quantity>10</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>
<items>
<lpn>LPNMULTI102</lpn>
<sku>SKUMULTI102</sku>
<quantity>8</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
</Document>
shipmentWithMultipleOrdersOrderLevelStrategies:
summary: Shipment with multiple orders using order level strategies
description: >
Processes multiple orders on the same shipment. Each order
provides its own `orderItemUpdateStrategy`, so no top level
strategy is needed.
value: |
<Document>
<business>kargo</business>
<facility>sf</facility>
<direction>OUTBOUND</direction>
<shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>
<orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>
<items>
<lpn>LPNMULTI201</lpn>
<sku>SKUMULTI201</sku>
<quantity>4</quantity>
<quantityUnit>CASE</quantityUnit>
</items>
</orders>
<orders>
<orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>
<orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>
<items>
<lpn>LPNMULTI202</lpn>
<sku>SKUMULTI202</sku>
</items>
</orders>
</Document>
responses:
'200':
description: Document processed; entities updated, nothing newly created.
headers:
Correlation-Id:
description: Same correlation id supplied by the client, when present.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentResult'
'201':
description: Document processed; one or more entities created.
headers:
Location:
description: Canonical URL of the resulting document.
schema:
type: string
format: uri
Correlation-Id:
description: Same correlation id supplied by the client, when present.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentResult'
'400':
description: Malformed JSON or XML request body.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
description: Missing or invalid bearer token.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'403':
description: Token lacks permission for the given business/facility.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: business or facility not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'409':
description: >
Conflict. The document cannot be applied because it would create duplicate
or ambiguous data, such as an `APPEND` request containing an item whose
`lpn` + `sku` already exists on the matched order, duplicate `lpn` + `sku`
pairs in the incoming items, or a shipmentNumber conflict. Use `MERGE` to
update existing items, or `OVERWRITE` to replace the full item list.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'415':
description: Unsupported media type; use application/json, application/xml, or text/xml.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'422':
description: >
Semantically invalid document, such as a bad enum value, invalid
item shape for the chosen `orderItemUpdateStrategy`, or a new order
missing business
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kargo/refs/heads/main/openapi/kargo-document-intake-openapi.yml