> ## 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.

# List all inventory orders for the authenticated organization

> Returns a paginated list of inventory orders (warehouse stock replenishment requests) for the caller's organization. Supports filtering by status and date range, and sorting by creation date. Each result includes the ordered items and their shipment details.



## OpenAPI

````yaml /openapi.json get /api/v1/inventory-orders
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:
    get:
      tags:
        - Inventory Orders
      summary: List all inventory orders for the authenticated organization
      description: >-
        Returns a paginated list of inventory orders (warehouse stock
        replenishment requests) for the caller's organization. Supports
        filtering by status and date range, and sorting by creation date. Each
        result includes the ordered items and their shipment details.
      operationId: listInventoryOrders
      parameters:
        - name: page
          in: query
          description: The page number to request (1 based)
          required: false
          schema:
            type: integer
            format: int32
            description: The page number to request (1 based)
            example: 1
          example: 1
        - name: size
          in: query
          description: The number of results to return in a page
          required: false
          schema:
            type: integer
            format: int32
            description: The number of results to return in a page
            example: 100
          example: 100
        - name: ids
          in: query
          description: Filter by inventory order IDs
          required: false
          schema:
            type: array
            description: Filter by inventory order IDs
            items:
              type: string
              format: uuid
              description: Filter by inventory order IDs
        - name: statuses
          in: query
          description: Filter by order statuses (e.g. SUBMITTED, PROCESSING)
          required: false
          schema:
            type: array
            description: Filter by order statuses (e.g. SUBMITTED, PROCESSING)
            items:
              type: string
              description: Filter by order statuses (e.g. SUBMITTED, PROCESSING)
              enum:
                - CANCELLED
                - COMPLETE
                - ORDERED
                - PARTIALLY_RECEIVED
                - PROCESSING
                - RECEIVED
                - SHIPPED
                - SUBMITTED
        - name: warehouseIds
          in: query
          description: Filter by warehouse IDs
          required: false
          schema:
            type: array
            description: Filter by warehouse IDs
            items:
              type: string
              format: uuid
              description: Filter by warehouse IDs
        - name: categories
          in: query
          description: Filter by product categories (e.g. COMPUTER)
          required: false
          schema:
            type: array
            description: Filter by product categories (e.g. COMPUTER)
            items:
              type: string
              description: Filter by product categories (e.g. COMPUTER)
        - name: brands
          in: query
          description: Filter by product brands
          required: false
          schema:
            type: array
            description: Filter by product brands
            items:
              type: string
              description: Filter by product brands
        - name: customerPoNumbers
          in: query
          description: Filter by customer PO numbers
          required: false
          schema:
            type: array
            description: Filter by customer PO numbers
            items:
              type: string
              description: Filter by customer PO numbers
        - name: friendlyOrderIds
          in: query
          description: Filter by exact friendly order IDs (case-insensitive)
          required: false
          schema:
            type: array
            description: Filter by exact friendly order IDs (case-insensitive)
            example: ORD-000123
            items:
              type: string
              description: Filter by exact friendly order IDs (case-insensitive)
              example: ORD-000123
          example: ORD-000123
        - name: submittedBy
          in: query
          description: Filter by person IDs who submitted the order
          required: false
          schema:
            type: array
            description: Filter by person IDs who submitted the order
            items:
              type: string
              format: uuid
              description: Filter by person IDs who submitted the order
        - name: includeOrdersWithoutSubmitter
          in: query
          description: >-
            When true, includes orders without a submitter (system-generated).
            OR'd with submittedBy if both are provided.
          required: false
          schema:
            type: boolean
            description: >-
              When true, includes orders without a submitter (system-generated).
              OR'd with submittedBy if both are provided.
        - name: reasons
          in: query
          description: Filter by order reasons (e.g. ONE_OFF, RESTOCK)
          required: false
          schema:
            type: array
            description: Filter by order reasons (e.g. ONE_OFF, RESTOCK)
            items:
              type: string
              description: Filter by order reasons (e.g. ONE_OFF, RESTOCK)
              enum:
                - ONE_OFF
                - RESTOCK
        - name: createdDateFrom
          in: query
          description: >-
            Filter orders created on or after this date (ISO-8601). If provided,
            createdDateTo must also be provided.
          required: false
          schema:
            type: string
            format: date
            description: >-
              Filter orders created on or after this date (ISO-8601). If
              provided, createdDateTo must also be provided.
            example: '2024-01-01'
          example: '2024-01-01'
        - name: createdDateTo
          in: query
          description: >-
            Filter orders created on or before this date (ISO-8601). If
            provided, createdDateFrom must also be provided.
          required: false
          schema:
            type: string
            format: date
            description: >-
              Filter orders created on or before this date (ISO-8601). If
              provided, createdDateFrom must also be provided.
            example: '2024-12-31'
          example: '2024-12-31'
        - name: expectedShipDateFrom
          in: query
          description: >-
            Filter orders with expected ship date on or after this date
            (ISO-8601). If provided, expectedShipDateTo must also be provided.
          required: false
          schema:
            type: string
            format: date
            description: >-
              Filter orders with expected ship date on or after this date
              (ISO-8601). If provided, expectedShipDateTo must also be provided.
            example: '2024-01-01'
          example: '2024-01-01'
        - name: expectedShipDateTo
          in: query
          description: >-
            Filter orders with expected ship date on or before this date
            (ISO-8601). If provided, expectedShipDateFrom must also be provided.
          required: false
          schema:
            type: string
            format: date
            description: >-
              Filter orders with expected ship date on or before this date
              (ISO-8601). If provided, expectedShipDateFrom must also be
              provided.
            example: '2024-12-31'
          example: '2024-12-31'
        - name: searchString
          in: query
          description: Search string to filter orders
          required: false
          schema:
            type: string
            description: Search string to filter orders
            example: laptop
          example: laptop
        - name: vendorSku
          in: query
          description: Filter by SKU vendor SKUs (MPN).
          required: false
          schema:
            type: array
            description: Filter by SKU vendor SKUs (MPN).
            items:
              type: string
              description: Filter by SKU vendor SKUs (MPN).
        - name: skuId
          in: query
          description: Filter by SKU IDs.
          required: false
          schema:
            type: array
            description: Filter by SKU IDs.
            items:
              type: string
              format: uuid
              description: Filter by SKU IDs.
        - name: serialNumber
          in: query
          description: Filter by inventory serial numbers.
          required: false
          schema:
            type: array
            description: Filter by inventory serial numbers.
            items:
              type: string
              description: Filter by inventory serial numbers.
        - name: sortBy
          in: query
          description: >-
            Field to sort by (createdAt, updatedAt, warehouse, status,
            submittedBy).
          required: false
          schema:
            type: string
            description: >-
              Field to sort by (createdAt, updatedAt, warehouse, status,
              submittedBy).
            example: createdAt
          example: createdAt
        - name: sortDirection
          in: query
          description: Sort direction (ASC, DESC).
          required: false
          schema:
            type: string
            description: Sort direction (ASC, DESC).
            example: DESC
          example: DESC
      responses:
        '200':
          description: Paginated list of inventory orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryOrderResponse'
        '400':
          description: Bad request — invalid filter or pagination parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
components:
  schemas:
    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
    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
    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

````