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
        consigneeName:
          type: string
        consigneePhoneNumber:
          type: string
        bolNumber:
          type: string
        expectedQuantity:
          type: integer
        carrier:
          type: string
        sealNumber:
          type: string
        supplier:
          type: string
        client:
          type: string
        destination:
          type: string
        orderItemUpdateStrategy:
          allOf:
          - $ref: '#/components/schemas/OrderItemUpdateStrategy'
          default: OVERWRITE
          description: 'Shipment level default item update strategy. In multi order mode, this value applies to each order unless that order provides its own `orderItemUpdateStrategy`.

            '
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItemInput'
        orders:
          type: array
          minItems: 1
          description: 'Multi order mode list. Each entry is processed as one order on the same shipment. Do not include top level `orderNumber` when using this field.

            '
          items:
            $ref: '#/components/schemas/BatchOrderInput'
      allOf:
      - if:
          required:
          - items
          not:
            required:
            - orderItemUpdateStrategy
        then:
          properties:
            items:
              items:
                required:
                - lpn
                - sku
                - quantity
                - quantityUnit
      - 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
    OrderItemUpdateStrategy:
      type: string
      description: "How the incoming `items` reconcile with items already on the matched order:\nIf omitted and `items` are provided, defaults to `OVERWRITE`. If no\n`items` are provided, existing order items are unchanged.\n\n  - `APPEND`    — add incoming items to the order and keep existing items. Each incoming item requires `lpn`, `sku`, `quantity`, and `quantityUnit`. Duplicate `lpn` + `sku` pairs are rejected with `409 Conflict`; use `MERGE` to update existing items or `OVERWRITE` to replace the full item list.\n  - `OVERWRITE` — replace all existing order items with the incoming items. If multiple orders have the same order number, the most recently created order is updated. Each incoming item requires `lpn`, `sku`, `quantity`, and `quantityUnit`.\n  - `MERGE`     — update existing items matched by `lpn` + `sku`; non-matching incoming items are added. Each incoming item requires `lpn` and `sku`.\n  - `DELETE`    — remove existing order items matched by `lpn` + `sku`. Each incoming item requires `lpn` and `sku`.\n"
      enum:
      - APPEND
      - OVERWRITE
      - MERGE
      - DELETE
    Shipment:
      type: object
      description: The resulting shipment after the document is processed.
      properties:
        id:
          type: integer
        status:
          type: string
        expectedArrivalAt:
          type: string
          format: date-time
        carrier:
          type: string
        purchaseOrder:
          type: string
        facility:
          type: object
          properties:
            slug:
              type: string
            name:
              type: string
        statusEvents:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              displayName:
                type: string
              completed:
                type: boolean
              completedAt:
                type: string
                format: date-time
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    EntityRef:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          enum:
          - SHIPMENT
          - ORDER
          - ORDER_ITEM
        id:
          type: string
          description: 'Kargo identifier of the affected entity: shipment id, order externalId, or order item id.

            '
        reference:
          type: string
          description: 'Human-facing key where one exists, such as `shipmentNumber` for a shipment, `orderNumber` for an order, or `lpn` + `sku` information for an order item.

            '
    OrderItemInput:
      type: object
      additionalProperties: false
      properties:
        identifier:
          type: string
          description: 'Customer supplied identifier for the item. Optional. This field is not used to match items for `MERGE` or `DELETE`; item matching uses `lpn` + `sku`.

            '
        lpn:
          type: string
          description: License plate number. Used together with `sku` as the item key for MERGE and DELETE.
        sku:
          type: string
          description: SKU. Used together with `lpn` as the item key for MERGE and DELETE.
        quantity:
          type: integer
        quantityUnit:
          type: string
          description: ShipperUnitType enum.
        purchaseOrder:
          type: string
        description:
          type: string
        upc:
          type: string
        weightPerUnit:
          type: number
        weightUnit:
          type: string
          description: WeightUnit enum.
        height:
          type: number
        length:
          type: number
        dimensionUnit:
          type: string
          description: DimensionUnit enum.
        isDangerousGood:
          type: boolean
        lot:
          type: string
        expirationDate:
          type: string
          format: date
        manufacturingDate:
          type: string
          format: date
        caseSerials:
          type: array
          description: 'Case-level serials for this order item. Clients provide only `id` and `quantity`; Kargo stores these as order_item.sub_units with unit_type set to "case".

            '
          items:
            $ref: '#/components/schemas/CaseSerial'
    Problem:
      type: object
      description: RFC 9457 problem detail.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              detail:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer