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

# Get a single order by ID

> Returns full details for a single order belonging to the caller's organization, including order items, current status, and shipping address.



## OpenAPI

````yaml /openapi.json get /api/v1/orders/{orderId}
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/orders/{orderId}:
    get:
      tags:
        - Orders
      summary: Get a single order by ID
      description: >-
        Returns full details for a single order belonging to the caller's
        organization, including order items, current status, and shipping
        address.
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIGetOrderResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '404':
          description: Order not found or does not belong to the caller's organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
components:
  schemas:
    PublicAPIGetOrderResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Order's ID
          example: 123E4567-E89B-12D3-A456-426614174000
        personId:
          type: string
          format: uuid
          description: The ID of the Person
          example: d7d0d906-425f-402f-bde1-39031c67c40b
        officeId:
          type: string
          format: uuid
          description: The ID of the Office
          example: d7d0d906-425f-402f-bde1-39031c67c40b
        status:
          type: string
          description: Order's status
          enum:
            - AWAITING_APPROVAL
            - ORDERED
            - PROCESSING
            - ORDERED_NOT_SHIPPED
            - SHIPPED
            - COMPLETED
            - PARTIALLY_SHIPPED
            - DECLINED
            - AWAITING_DELIVERY_SCHEDULING
            - DELIVERY_SCHEDULED
            - DELIVERED
            - NONE
            - APPROVED
            - AWAITING_FULFILLMENT
            - PENDING
            - RETURN_KIT_SENT
            - RETURN_KIT_DELIVERED
            - RETURN_KIT_SENT_BACK
            - RECEIVED_IN_WAREHOUSE
            - RETURNED
            - NOT_RETURNED
            - OUT_FOR_DELIVERY
            - DELIVERY_EXCEPTION
            - SUBMITTED
            - CANCELLED
            - CONFIRMED
            - NOT_COMPLETED
            - PARTIALLY_COMPLETED
          example: COMPLETED
        orderItems:
          type: array
          description: >-
            All order item rows on the order, including lines in terminal states
            such as CANCELLED. Replacing products via PATCH cancels superseded
            rows rather than deleting them, so consumers should filter by each
            item's `status` when they care only about active lines.
          items:
            $ref: '#/components/schemas/PublicAPIOrderItemResponse'
        statusHistory:
          type: array
          description: Chronological history of status changes
          items:
            $ref: '#/components/schemas/StatusHistoryEntry'
        shippingAddress:
          $ref: '#/components/schemas/AddressInfo'
          description: Order item's shipping address
        orderType:
          type: string
          description: Type of order based on lifecycle context
          enum:
            - ONE_OFF
            - ONBOARDING
            - REPLACEMENT
        submittedBy:
          type: string
          description: Name of the person who submitted the order
          example: John S. (Firstbase)
        approvedBy:
          type: string
          description: Name of the person who approved the order
          example: Jane Smith
        approvedAt:
          type: string
          format: date
          description: Date when the order was approved
          example: '2026-02-26'
        deliverToOffice:
          $ref: '#/components/schemas/DeliverToOfficeInfo'
          description: >-
            Office to which the order is delivered, when different from the
            assigned office
        deliverToPerson:
          $ref: '#/components/schemas/DeliverToPersonInfo'
          description: >-
            Person to whom the order is delivered, when different from the
            assigned person
        createdAt:
          type: string
          format: date-time
          description: UTC ISO-8601 timestamp when the order was created.
          example: '2026-02-26T14:15:22.123Z'
        updatedAt:
          type: string
          format: date-time
          description: UTC ISO-8601 timestamp when the order was last updated.
          example: '2026-03-15T09:00:00.000Z'
        expectedBy:
          type: string
          format: date
          description: >-
            Date by which the order is expected to be delivered (calendar date,
            no time component).
          example: '2026-03-10'
        packageSlug:
          type: string
          description: Slug of the product package this order was created from, if any.
          example: engineering-onboarding
        deliveryLocation:
          type: string
          description: >-
            The order's delivery location type (mirrors the FE Orders 'Delivery
            location' column, where PERSON is shown as 'Employee'). Derived from
            `deliverToOffice` / `deliverToPerson`: OFFICE when `deliverToOffice`
            is set, otherwise PERSON when `deliverToPerson` is set.
          enum:
            - PERSON
            - OFFICE
      required:
        - id
        - orderItems
        - orderType
        - status
        - statusHistory
    PublicApiHttpErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiError'
      required:
        - errors
    PublicAPIOrderItemResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Order item's ID
          example: 123E4567-E89B-12D3-A456-426614174000
        skuId:
          type: string
          format: uuid
          description: SKU ID
          example: 123E4567-E89B-12D3-A456-426614174000
        title:
          type: string
          description: Product title
          example: iPad Air - Silver, 64GB, WiFi
        categoryCode:
          type: string
          description: Product category code
          example: COMPUTER
        status:
          type: string
          description: Order item's status
          enum:
            - AWAITING_APPROVAL
            - ORDERED
            - PROCESSING
            - ORDERED_NOT_SHIPPED
            - SHIPPED
            - COMPLETED
            - PARTIALLY_SHIPPED
            - DECLINED
            - AWAITING_DELIVERY_SCHEDULING
            - DELIVERY_SCHEDULED
            - DELIVERED
            - NONE
            - APPROVED
            - AWAITING_FULFILLMENT
            - PENDING
            - RETURN_KIT_SENT
            - RETURN_KIT_DELIVERED
            - RETURN_KIT_SENT_BACK
            - RECEIVED_IN_WAREHOUSE
            - RETURNED
            - NOT_RETURNED
            - OUT_FOR_DELIVERY
            - DELIVERY_EXCEPTION
            - SUBMITTED
            - CANCELLED
            - CONFIRMED
            - NOT_COMPLETED
            - PARTIALLY_COMPLETED
          example: PROCESSING
        shipment:
          $ref: '#/components/schemas/PublicAPIOrderItemShipmentResponse'
          description: Order item's shipment details
        statusHistory:
          type: array
          description: Chronological history of status changes
          items:
            $ref: '#/components/schemas/StatusHistoryEntry'
        fulfillmentMethod:
          type: string
          description: Order item's fulfillment method
          enum:
            - WAREHOUSE
            - DROPSHIP
        vendorSku:
          type: string
          description: >-
            Vendor's own SKU identifier. Populated only when the underlying 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
        serialNumber:
          type: string
          description: Serial number assigned to this order item, if any.
          example: C02XL0AAJG5L
        justification:
          type: string
          description: Justification text recorded for this order item, if any.
          example: Need higher RAM for local development workflows
        purchaseOrderNumber:
          type: string
          description: >-
            Regional purchase order number stamped on this order item when
            applicable.
          example: PO-US-LAPTOPS-001
      required:
        - categoryCode
        - id
        - skuId
        - status
        - statusHistory
        - title
    StatusHistoryEntry:
      type: object
      properties:
        status:
          type: string
          description: Order status at time of change
          enum:
            - AWAITING_APPROVAL
            - ORDERED
            - PROCESSING
            - ORDERED_NOT_SHIPPED
            - SHIPPED
            - COMPLETED
            - PARTIALLY_SHIPPED
            - DECLINED
            - AWAITING_DELIVERY_SCHEDULING
            - DELIVERY_SCHEDULED
            - DELIVERED
            - NONE
            - APPROVED
            - AWAITING_FULFILLMENT
            - PENDING
            - RETURN_KIT_SENT
            - RETURN_KIT_DELIVERED
            - RETURN_KIT_SENT_BACK
            - RECEIVED_IN_WAREHOUSE
            - RETURNED
            - NOT_RETURNED
            - OUT_FOR_DELIVERY
            - DELIVERY_EXCEPTION
            - SUBMITTED
            - CANCELLED
            - CONFIRMED
            - NOT_COMPLETED
            - PARTIALLY_COMPLETED
          example: APPROVED
        timestamp:
          type: string
          format: date-time
          description: Timestamp of status change in UTC
          example: '2023-01-01T12:00:00Z'
      required:
        - status
        - timestamp
    AddressInfo:
      type: object
      properties:
        addressLine1:
          type: string
          example: 123
        addressLine2:
          type: string
          example: Suite 103
        administrativeArea:
          type: string
          description: the state or county
          example: NY
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        locality:
          type: string
          description: the city
          example: New York City
        postalCode:
          type: string
          description: the postal code or zip code
          example: 10123
      required:
        - countryCode
    DeliverToOfficeInfo:
      type: object
      description: Office to which the order is delivered
      properties:
        id:
          type: string
          format: uuid
          description: Office ID
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Office name
          example: NYC HQ
        address:
          $ref: '#/components/schemas/AddressInfo'
          description: Office address
      required:
        - id
    DeliverToPersonInfo:
      type: object
      description: Person to whom the order is delivered
      properties:
        id:
          type: string
          format: uuid
          description: Person ID
          example: 123e4567-e89b-12d3-a456-426614174000
        firstName:
          type: string
          description: First name
          example: Jane
        lastName:
          type: string
          description: Last name
          example: Smith
        email:
          type: string
          description: Email address
          example: jane.smith@example.com
      required:
        - email
        - firstName
        - id
        - lastName
    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
    PublicAPIOrderItemShipmentResponse:
      type: object
      properties:
        trackingUrl:
          type: string
          description: >-
            The carrier's tracking URL for this shipment. Open in a browser to
            view live shipment status.
        trackingCode:
          type: string
          description: Tracking code
          example: 1Z00000000
        carrier:
          type: string
          description: The carrier name
          example: UPS
        status:
          type: string
          description: The current status of the shipment
          example: DELIVERED
        trackingHistory:
          type: array
          description: >-
            A history of recorded shipment status updates in order of date
            received
          items:
            $ref: '#/components/schemas/PublicAPIOrderItemShipmentStatusDTO'
    PublicAPIOrderItemShipmentStatusDTO:
      type: object
      properties:
        status:
          type: string
          description: The status of the shipment
          example: IN_TRANSIT
        timestamp:
          type: string
          format: date-time
          description: Timestamp at which the event was received
      required:
        - status
        - timestamp
  securitySchemes:
    ApiKey:
      type: apiKey
      description: Prefix the value with "ApiKey" to indicate the custom authorization type
      name: Authorization
      in: header

````