> ## Documentation Index
> Fetch the complete documentation index at: https://developer.firstbasedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modify an inventory order

> Partially update an inventory order. Field writability depends on order status — see request body schema.



## OpenAPI

````yaml /openapi.json patch /api/v1/inventory-orders/{inventoryOrderId}
openapi: 3.1.0
info:
  title: Firstbase API Specification Beta
  description: Integration endpoints for Firstbase
  version: 0.1.0
servers:
  - url: /
    description: Default
security:
  - ApiKey: []
tags:
  - name: Inventory Orders
    description: Create and manage inventory orders
  - name: Shipment Notices V1
    description: 'Query shipment notice orders (V1: package items expose `inventories` list)'
  - name: Packages
    description: ''
  - name: Categories
    description: Query available categories for asset creation
  - name: Catalog
    description: ''
  - name: New Joiners
    description: New joiner provisioning pipeline for the organization
  - name: Orders
    description: ''
  - name: People
    description: >-
      Manage the users of Firstbase for your organization. API follows the SCIM
      standard.
    externalDocs:
      url: https://scim.cloud/
  - name: People — Lifecycle
    description: Offboard and reactivate users.
  - name: Assets
    description: Manage inventory assets
  - name: Regions V1
    description: Query regions (V1)
  - name: Warehouses V1
    description: Query warehouses (V1)
  - name: Brands
    description: Query available brands for asset creation
  - name: Inventory
    description: ''
  - name: Replacements
    description: Create and manage equipment replacements
  - name: Offices
    description: Manage and query office locations for the authenticated organization
  - name: Returns
    description: Return and Replacements
paths:
  /api/v1/inventory-orders/{inventoryOrderId}:
    patch:
      tags:
        - Inventory Orders
      summary: Modify an inventory order
      description: >-
        Partially update an inventory order. Field writability depends on order
        status — see request body schema.
      operationId: patchInventoryOrder
      parameters:
        - name: inventoryOrderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicAPIPatchInventoryOrderRequest'
        required: true
      responses:
        '200':
          description: Inventory order updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryOrderResponse'
        '400':
          description: Bad request (empty body, validation error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '403':
          description: Endpoint not available for this org
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '404':
          description: Inventory order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '409':
          description: Order status forbids this modification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
components:
  schemas:
    PublicAPIPatchInventoryOrderRequest:
      type: object
      description: >-
        Request body for modifying an inventory order. All five top-level fields
        are optional. Omit a field to leave it unchanged. Behaviour depends on
        the order's current status:

          - SUBMITTED: all five fields are writable.
          - PROCESSING or SHIPPED: only `customerPoNumber` may be present in the body. Sending any other field (even with a value equal to the current one) returns 409 Conflict.
          - Any other status (ORDERED, RECEIVED, PARTIALLY_RECEIVED, COMPLETE, CANCELLED): the endpoint returns 409 Conflict.

        Sending `{}` (no fields) returns 400 Bad Request.

        Items semantics: if `items` is omitted entirely, the existing lines are
        left unchanged. If `items` is sent as `[]`, the request is rejected (an
        order must have at least one active line). Per entry: omit `id` to add a
        new line; include `id` (with any subset of other fields) to update —
        server prefills skuId, pricingId, discountedPrice, warrantyPricingId,
        and type from the existing row. Send `{"id": "...", "delete": true}` to
        cancel a specific line. Existing lines whose id is not mentioned are
        left alone.
      properties:
        warehouseId:
          $ref: '#/components/schemas/JsonNullableUUID'
          description: New warehouse for the order. Writable only when status is SUBMITTED.
        regionId:
          $ref: '#/components/schemas/JsonNullableUUID'
          description: New region. Writable only when status is SUBMITTED.
        customerPoNumber:
          $ref: '#/components/schemas/JsonNullableString'
          description: >-
            Customer PO number. Writable when status is SUBMITTED, PROCESSING,
            or SHIPPED. Send an explicit JSON null to clear the existing value;
            omit the key to leave it unchanged.
        billingType:
          $ref: '#/components/schemas/JsonNullableProductPriceBillingType'
          description: Billing type. Writable only when status is SUBMITTED.
        items:
          type: array
          description: >-
            Optional list of item changes. Omit the key to leave items
            unchanged. Sending an empty array returns 409 (orders must keep at
            least one active line).
          items:
            $ref: '#/components/schemas/PublicAPIPatchInventoryOrderItem'
      required:
        - billingType
        - customerPoNumber
        - regionId
        - warehouseId
    InventoryOrderResponse:
      type: object
      description: Inventory order information
      properties:
        id:
          type: string
          format: uuid
          description: Order ID
          example: 123E4567-E89B-12D3-A456-426614174000
        friendlyOrderId:
          type: string
          description: >-
            Human-readable friendly order ID (order number shown to customers).
            Null for orders created before this field was populated.
          example: ORD-000123
        status:
          type: string
          description: Order status
          enum:
            - CANCELLED
            - COMPLETE
            - ORDERED
            - PARTIALLY_RECEIVED
            - PROCESSING
            - RECEIVED
            - SHIPPED
            - SUBMITTED
          example: PROCESSING
        warehouse:
          $ref: '#/components/schemas/WarehouseReference'
          description: Warehouse information
        customerPoNumber:
          type: string
          description: Customer PO number
          example: PO-12345
        reason:
          type: string
          description: Order reason
          enum:
            - ONE_OFF
            - RESTOCK
          example: ONE_OFF
        billingType:
          type: string
          description: Billing type
          enum:
            - SUBSCRIPTION
            - PURCHASED
          example: SUBSCRIPTION
        submittedBy:
          $ref: '#/components/schemas/PersonReference'
          description: Person who submitted the order
        inventoryOrderItems:
          type: array
          description: Inventory order items
          items:
            $ref: '#/components/schemas/InventoryOrderItemResponse'
        inventoryOrderShipments:
          type: array
          description: Inventory order shipments
          items:
            $ref: '#/components/schemas/InventoryOrderShipmentResponse'
        createdAt:
          type: string
          format: date-time
          description: UTC ISO-8601 timestamp when the inventory order was created.
          example: '2026-02-26T14:15:22.123Z'
        updatedAt:
          type: string
          format: date-time
          description: UTC ISO-8601 timestamp when the inventory order was last updated.
          example: '2026-03-15T09:00:00.000Z'
        expectedShipDate:
          type: string
          format: date
          description: >-
            Date by which the inventory order is expected to ship (calendar
            date, no time component).
          example: '2026-03-10'
      required:
        - id
        - inventoryOrderItems
        - inventoryOrderShipments
        - reason
        - status
        - warehouse
    PublicApiHttpErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiError'
      required:
        - errors
    JsonNullableUUID:
      type: object
      properties:
        present:
          type: boolean
    JsonNullableString:
      type: object
      properties:
        present:
          type: boolean
    JsonNullableProductPriceBillingType:
      type: object
      properties:
        present:
          type: boolean
    PublicAPIPatchInventoryOrderItem:
      type: object
      description: |-
        Inventory-order line patch entry. Three modes:
          - Add: omit `id`. Require `skuId`, `pricingId`, `quantity`.
          - Update: include `id` plus any subset of {quantity, discountedPrice, warrantyPricingId, inventoryOrderItemType}. Server prefills `skuId`, `pricingId`, `discountedPrice`, `warrantyPricingId`, and `inventoryOrderItemType` from the existing row when omitted.
          - Delete: send `{"id": "...", "delete": true}`. All other fields ignored.
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Existing line id. Omit to add a new line; include to update or
            delete.
        skuId:
          $ref: '#/components/schemas/JsonNullableUUID'
          description: SKU id. Required when adding.
        pricingId:
          $ref: '#/components/schemas/JsonNullableUUID'
          description: Pricing id. Required when adding.
        quantity:
          $ref: '#/components/schemas/JsonNullableInteger'
          description: Quantity (>= 1). Required when adding.
        discountedPrice:
          $ref: '#/components/schemas/JsonNullableBigDecimal'
          description: Discounted unit price. Optional; defaults to pricing's discount.
        warrantyPricingId:
          $ref: '#/components/schemas/JsonNullableUUID'
          description: Warranty pricing id, if applicable.
        inventoryOrderItemType:
          $ref: '#/components/schemas/JsonNullableInventoryOrderItemType'
          description: Item type. Defaults to PHYSICAL.
        delete:
          type: boolean
          description: If true, cancel this line. Requires `id`.
      required:
        - discountedPrice
        - inventoryOrderItemType
        - pricingId
        - quantity
        - skuId
        - warrantyPricingId
    WarehouseReference:
      type: object
      description: Reference to warehouse
      properties:
        id:
          type: string
          format: uuid
          description: Warehouse ID
          example: 123E4567-E89B-12D3-A456-426614174000
        name:
          type: string
          description: Warehouse display name.
          example: SF Main Warehouse
      required:
        - id
    PersonReference:
      type: object
      description: Reference to person
      properties:
        id:
          type: string
          format: uuid
          description: Person ID
          example: 123E4567-E89B-12D3-A456-426614174000
        forename:
          type: string
          description: Person's given/first name.
          example: Jane
        surname:
          type: string
          description: Person's surname/last name.
          example: Doe
      required:
        - id
    InventoryOrderItemResponse:
      type: object
      description: Inventory order item information
      properties:
        id:
          type: string
          format: uuid
          description: Order item ID
          example: 123E4567-E89B-12D3-A456-426614174000
        status:
          type: string
          description: Order item status
          enum:
            - ACTIVATED
            - ARRIVED_AT_PROCESSING_FACILITY
            - CANCELLED
            - DELIVERY_EXCEPTION
            - ORDERED
            - OUT_FOR_DELIVERY
            - PARTIALLY_ACTIVATED
            - PARTIALLY_RECEIVED
            - PARTIALLY_SHIPPED
            - PENDING
            - RECEIVED
            - SHIPPED
          example: RECEIVED
        sku:
          $ref: '#/components/schemas/SkuReference'
          description: SKU ID
          example: 123E4567-E89B-12D3-A456-426614174000
        pricing:
          $ref: '#/components/schemas/PricingInfo'
          description: Pricing information
        quantity:
          type: integer
          format: int32
          description: Quantity
          example: 2
        discountedPrice:
          type: number
          description: Discounted price
          example: 999
        warranty:
          description: Warranty item if this is a physical item with warranty
          required:
            - id
            - pricing
            - quantity
            - sku
            - status
        type:
          type: string
          description: Item type
          enum:
            - PHYSICAL
            - SERVICE
          example: PHYSICAL
        expectedShipDate:
          type: string
          format: date
          description: Expected ship date
          example: '2026-01-20'
      required:
        - id
        - pricing
        - quantity
        - sku
        - status
        - type
    InventoryOrderShipmentResponse:
      type: object
      description: Shipment information for an inventory order
      properties:
        id:
          type: string
          format: uuid
          description: Shipment ID
          example: 123E4567-E89B-12D3-A456-426614174000
        status:
          type: string
          description: Shipment status
          enum:
            - ARRIVED_AT_PROCESSING_FACILITY
            - CANCELLED
            - DELIVERY_EXCEPTION
            - OUT_FOR_DELIVERY
            - PARTIALLY_RECEIVED
            - PENDING
            - RECEIVED
            - SHIPPED
          example: SHIPPED
        shippingCarrier:
          type: string
          description: Shipping carrier
          example: UPS
        trackingCode:
          type: string
          description: Tracking code
          example: 1Z00000000
        trackingUrl:
          type: string
          description: Tracking URL
          example: https://tracking.example.com/1Z00000000
        trackingStatus:
          type: string
          description: Tracking status
          enum:
            - DELIVERED
            - EXCEPTION
            - IN_TRANSIT
            - OUT_FOR_DELIVERY
            - PRE_TRANSIT
          example: IN_TRANSIT
        trackingShipmentId:
          type: string
          format: uuid
          description: Tracking shipment ID
          example: 123E4567-E89B-12D3-A456-426614174000
        estimatedDeliveryDate:
          type: string
          format: date
          description: Estimated delivery date
          example: '2024-01-15'
        etaStart:
          type: string
          format: date
          description: Estimated delivery start date from tracking provider
          example: '2024-01-14'
        etaEnd:
          type: string
          format: date
          description: Estimated delivery end date from tracking provider
          example: '2024-01-16'
        inventoryOrderShipmentItems:
          type: array
          description: Shipment items
          items:
            $ref: '#/components/schemas/InventoryOrderShipmentItemResponse'
      required:
        - id
        - inventoryOrderShipmentItems
        - status
    PublicApiError:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable description of the error
          example: Invalid request
        source:
          type: string
          description: >-
            Entity or field path that caused the error (for example order,
            shipmentNotice, or person:email)
          example: request
      required:
        - detail
        - source
    JsonNullableInteger:
      type: object
      properties:
        present:
          type: boolean
    JsonNullableBigDecimal:
      type: object
      properties:
        present:
          type: boolean
    JsonNullableInventoryOrderItemType:
      type: object
      properties:
        present:
          type: boolean
    SkuReference:
      type: object
      description: Reference to SKU
      properties:
        id:
          type: string
          format: uuid
          description: SKU ID
          example: 123E4567-E89B-12D3-A456-426614174000
        vendorSku:
          type: string
          description: >-
            Vendor's own SKU identifier. Populated only when the SKU has a
            vendor SKU on file.
          example: APL-MK183LL/A
        vendorCode:
          type: string
          description: >-
            Vendor code of the SKU's vendor. Populated only when the SKU's
            vendor is known.
          example: APPLE
        categoryCode:
          type: string
          description: >-
            Category code of the SKU's category. Populated only when the SKU's
            category is known.
          example: LAPTOP
        productTitle:
          type: string
          description: Product title from the SKU's embedded SKU information.
          example: MacBook Pro 14-inch
      required:
        - id
    PricingInfo:
      type: object
      description: Pricing information for an inventory order item
      properties:
        id:
          type: string
          format: uuid
          description: Pricing ID
          example: 123E4567-E89B-12D3-A456-426614174000
        price:
          type: integer
          format: int64
          deprecated: true
          description: Price in cents (deprecated, use unitPrice)
          example: 99900
        unitPrice:
          type: number
          description: Unit price in major currency units
          example: 999
    InventoryOrderShipmentItemResponse:
      type: object
      description: Shipment item information
      properties:
        id:
          type: string
          format: uuid
          description: Shipment item ID
          example: 123E4567-E89B-12D3-A456-426614174000
        inventoryOrderItem:
          $ref: '#/components/schemas/InventoryOrderItemReference'
          description: Inventory order item ID
          example: 123E4567-E89B-12D3-A456-426614174000
        quantity:
          type: integer
          format: int32
          description: Quantity
          example: 2
        status:
          type: string
          description: Shipment item status
          enum:
            - ARRIVED_AT_PROCESSING_FACILITY
            - CANCELLED
            - DELIVERY_EXCEPTION
            - ORDERED
            - OUT_FOR_DELIVERY
            - RECEIVED
            - SHIPPED
          example: RECEIVED
        inventories:
          type: array
          description: Inventories associated with this shipment item
          items:
            $ref: '#/components/schemas/InventoryOrderInventoryResponse'
      required:
        - id
        - inventories
        - inventoryOrderItem
        - quantity
        - status
    InventoryOrderItemReference:
      type: object
      description: Reference to inventory order item
      properties:
        id:
          type: string
          format: uuid
          description: Inventory order item ID
          example: 123E4567-E89B-12D3-A456-426614174000
      required:
        - id
    InventoryOrderInventoryResponse:
      type: object
      description: Inventory information for a shipment item
      properties:
        id:
          type: string
          format: uuid
          description: Inventory ID
          example: 123E4567-E89B-12D3-A456-426614174000
        serialNumber:
          type: string
          description: Serial number
          example: SN123456789
        deployStatus:
          type: string
          description: Deploy status
          enum:
            - ARCHIVED
            - AVAILABLE
            - AWAITING_ARRIVAL
            - DEPLOYED
            - GIFTED
            - LOCKED
            - ON_HOLD
            - OUT_FOR_REPAIR
            - UNAVAILABLE
            - VOIDED
          example: DEPLOYED
        warehouse:
          $ref: '#/components/schemas/WarehouseInfo'
          description: Warehouse name
          example: Main Warehouse
      required:
        - deployStatus
        - id
    WarehouseInfo:
      type: object
      description: Warehouse information
      properties:
        name:
          type: string
          description: Warehouse name
          example: Main Warehouse
      required:
        - name
  securitySchemes:
    ApiKey:
      type: apiKey
      description: Prefix the value with "ApiKey" to indicate the custom authorization type
      name: Authorization
      in: header

````