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

# Create an inventory order

> Creates an inventory order to ship equipment from a supplier or customer to a Firstbase warehouse. Specify the destination warehouse and the items (SKUs with quantities) to be stocked. The created order begins in SUBMITTED status and will be processed by the Firstbase logistics team.



## OpenAPI

````yaml /openapi.json post /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:
    post:
      tags:
        - Inventory Orders
      summary: Create an inventory order
      description: >-
        Creates an inventory order to ship equipment from a supplier or customer
        to a Firstbase warehouse. Specify the destination warehouse and the
        items (SKUs with quantities) to be stocked. The created order begins in
        SUBMITTED status and will be processed by the Firstbase logistics team.
      operationId: createInventoryOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInventoryOrderRequest'
        required: true
      responses:
        '201':
          description: Inventory order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryOrderResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
components:
  schemas:
    CreateInventoryOrderRequest:
      type: object
      description: Request to create an inventory order
      properties:
        warehouseId:
          type: string
          format: uuid
          description: Warehouse ID where the inventory will be sent
        regionId:
          type: string
          format: uuid
          description: Region ID. Required when the organization uses multi-entity
        items:
          type: array
          description: Items to include in the inventory order
          items:
            $ref: '#/components/schemas/CreateInventoryOrderItemRequest'
          maxItems: 100
          minItems: 0
        billingType:
          type: string
          description: >-
            Billing type. Required for HAAS organizations (SUBSCRIPTION or
            PURCHASED). Non-HAAS organizations default to PURCHASED and cannot
            use SUBSCRIPTION
          enum:
            - SUBSCRIPTION
            - PURCHASED
        firstbaseSupplied:
          type: boolean
          description: Whether Firstbase supplies the equipment. Defaults to true
          example: true
        trackingNumber:
          type: string
          description: Tracking number for the shipment
          maxLength: 255
          minLength: 0
        notes:
          type: string
          description: Additional notes for the order
          maxLength: 1000
          minLength: 0
        expectedShipDate:
          type: string
          format: date
          description: Expected ship date (ISO-8601)
          example: '2026-04-01'
        customerPoNumber:
          type: string
          description: Customer PO number
          maxLength: 255
          minLength: 0
      required:
        - items
        - 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
    CreateInventoryOrderItemRequest:
      type: object
      description: An item to include in an inventory order
      properties:
        skuId:
          type: string
          format: uuid
          description: SKU ID of the product to order
        quantity:
          type: integer
          format: int32
          description: Quantity to order
          example: 1
          minimum: 1
      required:
        - quantity
        - skuId
    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

````