Kargo Documents API
The Documents API from Kargo — 1 operation(s) for documents.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/kargo-documents-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Kargo Document Intake Documents 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
security:
- bearerAuth: []
tags:
- name: Documents
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>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU123</sku>\n <quantity>10</quantity>\n <quantityUnit>CASE</quantityUnit>\n <caseSerials>\n <id>00000000000379386070</id>\n <quantity>10</quantity>\n </caseSerials>\n </items>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU456</sku>\n <quantity>8</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n <items>\n <lpn>LPNDEF</lpn>\n <sku>SKU789</sku>\n <quantity>12</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n <items>\n <lpn>LPNGHI</lpn>\n <sku>SKU123</sku>\n <quantity>6</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n <items>\n <lpn>LPNJKL</lpn>\n <sku>SKU999</sku>\n <quantity>15</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n</Document>\n"
appendOrderItem:
summary: Append an order item
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>\n <items>\n <lpn>LPNNEW</lpn>\n <sku>SKUAPPEND</sku>\n <quantity>1</quantity>\n <quantityUnit>UNIT</quantityUnit>\n </items>\n</Document>\n"
mergeOrderItemByLpnAndSku:
summary: Update or add an order item by LPN + SKU
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU123</sku>\n <quantity>5</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n</Document>\n"
deleteOrderItemByLpnAndSku:
summary: Delete an order item by LPN + SKU
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU123</sku>\n </items>\n</Document>\n"
overwriteOrderItems:
summary: Replace all order items
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>OVERWRITE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNREPLACE001</lpn>\n <sku>SKUREPLACE001</sku>\n <quantity>2</quantity>\n <quantityUnit>UNIT</quantityUnit>\n </items>\n <items>\n <lpn>LPNREPLACE002</lpn>\n <sku>SKUREPLACE002</sku>\n <quantity>3</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n</Document>\n"
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>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <items>\n <lpn>LPNMULTI001</lpn>\n <sku>SKUMULTI001</sku>\n <quantity>10</quantity>\n <quantityUnit>CASE</quantityUnit>\n <caseSerials>\n <id>00000000000379386070</id>\n <quantity>10</quantity>\n </caseSerials>\n </items>\n </orders>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>\n <items>\n <lpn>LPNMULTI002</lpn>\n <sku>SKUMULTI002</sku>\n <quantity>8</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n</Document>\n"
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>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <items>\n <lpn>LPNMULTI101</lpn>\n <sku>SKUMULTI101</sku>\n <quantity>10</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>\n <items>\n <lpn>LPNMULTI102</lpn>\n <sku>SKUMULTI102</sku>\n <quantity>8</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n</Document>\n"
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>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>\n <items>\n <lpn>LPNMULTI201</lpn>\n <sku>SKUMULTI201</sku>\n <quantity>4</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>\n <orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNMULTI202</lpn>\n <sku>SKUMULTI202</sku>\n </items>\n </orders>\n</Document>\n"
text/xml:
schema:
$ref: '#/components/schemas/Document'
examples:
orderWithFivePallets:
summary: Create an outbound XML order with five pallet items
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU123</sku>\n <quantity>10</quantity>\n <quantityUnit>CASE</quantityUnit>\n <caseSerials>\n <id>00000000000379386070</id>\n <quantity>10</quantity>\n </caseSerials>\n </items>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU456</sku>\n <quantity>8</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n <items>\n <lpn>LPNDEF</lpn>\n <sku>SKU789</sku>\n <quantity>12</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n <items>\n <lpn>LPNGHI</lpn>\n <sku>SKU123</sku>\n <quantity>6</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n <items>\n <lpn>LPNJKL</lpn>\n <sku>SKU999</sku>\n <quantity>15</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n</Document>\n"
appendOrderItem:
summary: Append an order item
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>\n <items>\n <lpn>LPNNEW</lpn>\n <sku>SKUAPPEND</sku>\n <quantity>1</quantity>\n <quantityUnit>UNIT</quantityUnit>\n </items>\n</Document>\n"
mergeOrderItemByLpnAndSku:
summary: Update or add an order item by LPN + SKU
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU123</sku>\n <quantity>5</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n</Document>\n"
deleteOrderItemByLpnAndSku:
summary: Delete an order item by LPN + SKU
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNABC</lpn>\n <sku>SKU123</sku>\n </items>\n</Document>\n"
overwriteOrderItems:
summary: Replace all order items
value: "<Document>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>OVERWRITE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNREPLACE001</lpn>\n <sku>SKUREPLACE001</sku>\n <quantity>2</quantity>\n <quantityUnit>UNIT</quantityUnit>\n </items>\n <items>\n <lpn>LPNREPLACE002</lpn>\n <sku>SKUREPLACE002</sku>\n <quantity>3</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n</Document>\n"
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>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <items>\n <lpn>LPNMULTI001</lpn>\n <sku>SKUMULTI001</sku>\n <quantity>10</quantity>\n <quantityUnit>CASE</quantityUnit>\n <caseSerials>\n <id>00000000000379386070</id>\n <quantity>10</quantity>\n </caseSerials>\n </items>\n </orders>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>\n <items>\n <lpn>LPNMULTI002</lpn>\n <sku>SKUMULTI002</sku>\n <quantity>8</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n</Document>\n"
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>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orderItemUpdateStrategy>MERGE</orderItemUpdateStrategy>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <items>\n <lpn>LPNMULTI101</lpn>\n <sku>SKUMULTI101</sku>\n <quantity>10</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>\n <items>\n <lpn>LPNMULTI102</lpn>\n <sku>SKUMULTI102</sku>\n <quantity>8</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n</Document>\n"
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>\n <business>kargo</business>\n <facility>sf</facility>\n <direction>OUTBOUND</direction>\n <shipmentNumber>TEST-EXAMPLE-SHIPMENT-001</shipmentNumber>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-001</orderNumber>\n <orderItemUpdateStrategy>APPEND</orderItemUpdateStrategy>\n <items>\n <lpn>LPNMULTI201</lpn>\n <sku>SKUMULTI201</sku>\n <quantity>4</quantity>\n <quantityUnit>CASE</quantityUnit>\n </items>\n </orders>\n <orders>\n <orderNumber>TEST-EXAMPLE-ORDER-002</orderNumber>\n <orderItemUpdateStrategy>DELETE</orderItemUpdateStrategy>\n <items>\n <lpn>LPNMULTI202</lpn>\n <sku>SKUMULTI202</sku>\n </items>\n </orders>\n</Document>\n"
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 / facility / direction.
'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
BatchOrderInput:
type: object
additionalProperties: false
required:
- orderNumber
description: 'One order inside a shipment level multi order document. `orderNumber` identifies the order. Each order can provide its own `orderItemUpdateStrategy`, so different orders in the same shipment can use different strategies. If `orderItemUpdateStrategy` is omitted for this order, the top level `orderItemUpdateStrategy` is used. If neither value is provided, Kargo treats the order item update strategy as `OVERWRITE`.
'
properties:
orderNumber:
type: string
description: 'Upsert key for this order. This is the Kargo order identifier.
'
orderType:
type: string
purchaseOrder:
type: string
consigneeName:
type: string
consigneePhoneNumber:
type: string
bolNumber:
type: string
expectedQuantity:
type: integer
sealNumber:
type: string
supplier:
type: string
client:
type: string
destination:
type: string
orderItemUpdateStrategy:
allOf:
- $ref: '#/components/schemas/OrderItemUpdateStrategy'
description: 'Optional order level item update strategy. When provided, this overrides the top level `orderItemUpdateStrategy` for this order.
'
items:
type: array
items:
$ref: '#/components/schemas/OrderItemInput'
allOf:
- if:
required:
- orderItemUpdateStrategy
properties:
orderItemUpdateStrategy:
enum:
- APPEND
- OVERWRITE
then:
properties:
items:
items:
required:
- lpn
- sku
- quantity
- quantityUnit
- if:
required:
- orderItemUpdateStrategy
properties:
orderItemUpdateStrategy:
enum:
- MERGE
- DELETE
then:
properties:
items:
items:
required:
- lpn
- sku
Order:
type: object
properties:
externalId:
type: string
orderNumber:
type: string
status:
type: string
enum:
- CREATED
- SCHEDULED
- COMPLETED
items:
type: array
items:
allOf:
- $ref: '#/components/schemas/OrderItemInput'
- type: object
properties:
id:
type: string
CaseSerial:
type: object
additionalProperties: false
required:
- id
- quantity
properties:
id:
type: string
description: Case serial identifier.
quantity:
type: integer
description: Quantity represented by this case serial.
ShipmentAdditionalField:
type: object
additionalProperties: false
required:
- name
- value
properties:
name:
type: string
value:
type: string
DocumentResult:
type: object
required:
- created
- updated
- removed
properties:
shipment:
$ref: '#/components/schemas/Shipment'
created:
type: array
items:
$ref: '#/components/schemas/EntityRef'
updated:
type: array
items:
$ref: '#/components/schemas/EntityRef'
removed:
type: array
description: 'Entities removed by reconciliation, e.g. order items dropped when orderItemUpdateStrategy is `OVERWRITE`.
'
items:
$ref: '#/components/schemas/EntityRef'
OrderDirection:
type: string
enum:
- OUTBOUND
- INBOUND
Document:
type: object
additionalProperties: false
required:
- business
- facility
- direction
oneOf:
- required:
- orderNumber
not:
required:
- orders
- required:
- orders
- shipmentNumber
not:
required:
- orderNumber
description: 'Flattened shipment + order + order-item document. This schema supports two formats: the existing single order format with top level `orderNumber`, and a shipment level multi order format with `orders`. In single order mode, `orderNumber` is required at the top level. In multi order mode, `shipmentNumber` and `orders` are required and each order entry must include `orderNumber`.
`business`, `facility`, and `direction` are required. Item field requirements depend on `orderItemUpdateStrategy`: `APPEND` and `OVERWRITE` require each item to include `lpn`, `sku`, `quantity`, and `quantityUnit`; `MERGE` and `DELETE` require each item to include `lpn` and `sku`. If `orderItemUpdateStrategy` is omitted and `items` are provided, Kargo treats the request as `OVERWRITE`.
'
properties:
orderNumber:
type: string
description: 'Single order mode upsert key. If an order with this number exists, the document is applied to the most recently created matching order; otherwise a new order and shipment are created. Do not include this field when using `orders`.
'
business:
type: string
description: Short name / slug of the business, e.g. "kargo".
facility:
type: string
description: Short name / slug of the facility, e.g. "sf".
direction:
$ref: '#/components/schemas/OrderDirection'
description: Canonical direction of the order.
shipmentNumber:
type: string
description: "Facility provided unique shipment identifier. \n"
expectedArrivalAt:
type: string
format: date-time
trailerNumber:
type: string
dockSlug:
type: string
description: Short name of the dock, e.g. "D11".
driverName:
type: string
driverLicenseNumber:
type: string
driverLicensePlate:
type: string
additionalFields:
type: array
items:
$ref: '#/components/schemas/ShipmentAdditionalField'
orderType:
type: string
purchaseOrder:
type: string
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kargo/refs/heads/main/openapi/kargo-documents-api-openapi.yml