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

> Returns a paginated list of return orders. Each return includes 4 retrieval method types (PL, RETURN_KIT, INBOUND, NOT_MAPPED) with items grouped by method. Empty arrays indicate no items use that method.



## OpenAPI

````yaml /openapi.json get /api/v1/returns
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/returns:
    get:
      tags:
        - Returns
      summary: List all returns
      description: >-
        Returns a paginated list of return orders. Each return includes 4
        retrieval method types (PL, RETURN_KIT, INBOUND, NOT_MAPPED) with items
        grouped by method. Empty arrays indicate no items use that method.
      operationId: listReturns
      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
            minimum: 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: 10
            maximum: 500
          example: 10
        - name: personIDs
          in: query
          description: The list of persons that will be returned
          required: false
          schema:
            type: array
            description: The list of persons that will be returned
            items:
              type: string
              format: uuid
              description: The list of persons that will be returned
        - name: includeShipment
          in: query
          description: Include shipment data in the response
          required: false
          schema:
            type: boolean
            description: Include shipment data in the response
        - name: startDate
          in: query
          description: >-
            UTC Date-time to filter orders created after (ISO-8601 without
            timezone)
          required: false
          schema:
            type: string
            format: date-time
            description: >-
              UTC Date-time to filter orders created after (ISO-8601 without
              timezone)
            example: '2007-12-03T10:15:30'
          example: '2007-12-03T10:15:30'
        - name: endDate
          in: query
          description: >-
            UTC Date-time to filter orders created before (ISO-8601 without
            timezone)
          required: false
          schema:
            type: string
            format: date-time
            description: >-
              UTC Date-time to filter orders created before (ISO-8601 without
              timezone)
            example: '2007-12-03T10:15:30'
          example: '2007-12-03T10:15:30'
        - name: status
          in: query
          description: Filter by the return order's status.
          required: false
          schema:
            type: array
            description: Filter by the return order's status.
            enum:
              - PENDING
              - PROCESSING
              - COMPLETED
              - RETURN_KIT_DELIVERED
              - RETURN_KIT_SENT_BACK
              - RECEIVED_IN_WAREHOUSE
              - RETURNED
              - NOT_RETURNED
              - SUBMITTED
              - CANCELLED
              - NONE
              - CONFIRMED
              - PARTIALLY_COMPLETED
              - NOT_COMPLETED
            items:
              type: string
              description: Filter by the return order's status.
              enum:
                - PENDING
                - PROCESSING
                - COMPLETED
                - RETURN_KIT_SENT
                - RETURN_KIT_DELIVERED
                - RETURN_KIT_SENT_BACK
                - RECEIVED_IN_WAREHOUSE
                - RETURNED
                - NOT_RETURNED
                - SUBMITTED
                - CANCELLED
                - NONE
                - CONFIRMED
                - PARTIALLY_COMPLETED
                - NOT_COMPLETED
                - PENDING
                - PROCESSING
                - COMPLETED
                - RETURN_KIT_DELIVERED
                - RETURN_KIT_SENT_BACK
                - RECEIVED_IN_WAREHOUSE
                - RETURNED
                - NOT_RETURNED
                - SUBMITTED
                - CANCELLED
                - NONE
                - CONFIRMED
                - PARTIALLY_COMPLETED
                - NOT_COMPLETED
        - name: returnKitStatus
          in: query
          description: Filter by retrieval method (return kit) statuses.
          required: false
          schema:
            type: array
            description: Filter by retrieval method (return kit) statuses.
            enum:
              - REQUESTED
              - PROCESSED
              - CANCELLED
              - LABEL_CREATED
              - SHIPPED
              - DELIVERED
              - SENT_BACK
              - ARRIVED_AT_PROCESSING_FACILITY
              - DELIVERY_EXCEPTION
              - NOT_PROCESSED
              - PARTIALLY_PROCESSED
              - SCHEDULING_PICK_UP
            items:
              type: string
              description: Filter by retrieval method (return kit) statuses.
              enum:
                - REQUESTED
                - PROCESSED
                - CANCELLED
                - LABEL_CREATED
                - SHIPPED
                - DELIVERED
                - SENT_BACK
                - ARRIVED_AT_PROCESSING_FACILITY
                - DELIVERY_EXCEPTION
                - NOT_PROCESSED
                - PARTIALLY_PROCESSED
                - SCHEDULING_PICK_UP
                - REQUESTED
                - PROCESSED
                - CANCELLED
                - LABEL_CREATED
                - SHIPPED
                - DELIVERED
                - SENT_BACK
                - ARRIVED_AT_PROCESSING_FACILITY
                - DELIVERY_EXCEPTION
                - NOT_PROCESSED
                - PARTIALLY_PROCESSED
                - SCHEDULING_PICK_UP
        - name: submittedBy
          in: query
          description: Filter by person IDs who submitted the return
          required: false
          schema:
            type: array
            description: Filter by person IDs who submitted the return
            items:
              type: string
              format: uuid
              description: Filter by person IDs who submitted the return
        - name: country
          in: query
          description: Filter by shipping address country codes
          required: false
          schema:
            type: array
            description: Filter by shipping address country codes
            items:
              type: string
              description: Filter by shipping address country codes
        - name: officeId
          in: query
          description: Filter by office IDs (order's owning office)
          required: false
          schema:
            type: array
            description: Filter by office IDs (order's owning office)
            items:
              type: string
              format: uuid
              description: Filter by office IDs (order's owning office)
        - name: vendorSku
          in: query
          description: Filter by vendor SKUs
          required: false
          schema:
            type: array
            description: Filter by vendor SKUs
            items:
              type: string
              description: Filter by vendor SKUs
        - 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: deliveryLocation
          in: query
          description: >-
            Filter by the return's delivery location (corresponds to the FE
            'Delivery location' multi-select on the Returns page). Allowed
            values: FIRSTBASE, OFFICE, MULTIPLE.
          required: false
          schema:
            type: array
            description: >-
              Filter by the return's delivery location (corresponds to the FE
              'Delivery location' multi-select on the Returns page). Allowed
              values: FIRSTBASE, OFFICE, MULTIPLE.
            enum:
              - FIRSTBASE
              - OFFICE
              - MULTIPLE
            items:
              type: string
              description: >-
                Filter by the return's delivery location (corresponds to the FE
                'Delivery location' multi-select on the Returns page). Allowed
                values: FIRSTBASE, OFFICE, MULTIPLE.
              enum:
                - OFFICE
                - FIRSTBASE
                - MULTIPLE
                - FIRSTBASE
                - OFFICE
                - MULTIPLE
        - name: sortBy
          in: query
          description: >-
            Field to sort by (createdAt, updatedAt, country, deliveryLocation,
            status, person)
          required: false
          schema:
            type: string
            description: >-
              Field to sort by (createdAt, updatedAt, country, deliveryLocation,
              status, person)
            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 return orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReturnOrderInfo'
        '400':
          description: Bad request
          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:
    ReturnOrderInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Return order ID
          example: ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4
        personId:
          type: string
          format: uuid
          description: Person ID
          example: 016fb454-066b-4ba5-9eca-a2fa14b7e7fc
        supportTicketId:
          type: integer
          format: int64
          description: Support ticket ID
          example: 12345
        createdAt:
          type: string
          format: date
          description: Created date
          example: '2025-11-26'
        updatedAt:
          type: string
          format: date
          description: Updated date
          example: '2025-11-26'
        confirmedAtTimestamp:
          type: string
          format: date-time
          description: Confirmed timestamp (UTC)
          example: '2025-11-27T10:15:00Z'
        shippingAddress:
          $ref: '#/components/schemas/AddressInfo'
          description: Shipping address
        status:
          type: string
          description: Return order status
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - RETURN_KIT_SENT
            - RETURN_KIT_DELIVERED
            - RETURN_KIT_SENT_BACK
            - RECEIVED_IN_WAREHOUSE
            - RETURNED
            - NOT_RETURNED
            - SUBMITTED
            - CANCELLED
            - NONE
            - CONFIRMED
            - PARTIALLY_COMPLETED
            - NOT_COMPLETED
          example: CONFIRMED
        retrievals:
          type: array
          description: >-
            Retrieval methods grouped by type. Always contains 4 entries: PL,
            RETURN_KIT, INBOUND, NOT_MAPPED
          items:
            $ref: '#/components/schemas/ReturnRetrievalMethodInfo'
        replacement:
          $ref: '#/components/schemas/ReplacementInfo'
          description: Replacement order if applicable
        returnLifecycleType:
          type: string
          description: Return lifecycle type
          enum:
            - ONE_OFF
            - OFFBOARDING
          example: ONE_OFF
        submittedBy:
          $ref: '#/components/schemas/PublicApiPersonRef'
          description: Person who submitted the return order.
        office:
          $ref: '#/components/schemas/OfficeRef'
          description: Office associated with the return, if any.
        person:
          $ref: '#/components/schemas/PublicApiPersonRef'
          description: Affected person reference (sibling to legacy personId).
        deliveryLocation:
          type: string
          description: >-
            The return's delivery location (mirrors the FE Returns 'Delivery
            location' column). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.
          enum:
            - FIRSTBASE
            - OFFICE
            - MULTIPLE
      required:
        - id
        - retrievals
    PublicApiHttpErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiError'
      required:
        - errors
    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
    ReturnRetrievalMethodInfo:
      type: object
      description: Retrieval method with associated return items
      properties:
        methodType:
          type: string
          description: Type of retrieval method
          enum:
            - PL
            - RETURN_KIT
            - INBOUND
            - NOT_MAPPED
          example: RETURN_KIT
        items:
          type: array
          description: >-
            List of return items using this retrieval method. Empty array if no
            items use this method.
          items:
            $ref: '#/components/schemas/ReturnOrderItemInfo'
      required:
        - items
        - methodType
    ReplacementInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        order:
          $ref: '#/components/schemas/PublicAPIGetOrderResponse'
        createdAt:
          type: string
          format: date
        status:
          type: string
          enum:
            - SUBMITTED
            - PROCESSING
            - COMPLETED
            - PARTIALLY_COMPLETED
            - CANCELLED
      required:
        - createdAt
        - id
        - status
    PublicApiPersonRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Person ID
          example: 016fb454-066b-4ba5-9eca-a2fa14b7e7fc
        forename:
          type: string
          description: Person's forename / first name
        surname:
          type: string
          description: Person's surname / last name
      required:
        - id
    OfficeRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Office ID
          example: 016fb454-066b-4ba5-9eca-a2fa14b7e7fc
        name:
          type: string
          description: Office name
      required:
        - id
    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
    ReturnOrderItemInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Return 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
        returnReason:
          type: string
          description: Order item's return reason
          enum:
            - OFFBOARDING
            - UNKNOWN
            - OFF_CYCLE
            - DAMAGED
            - UPGRADE
            - STANDARD_LIFECYCLE
            - PRODUCT_CHANGE
            - OTHER
            - LOST_BY_WORKER
            - LOST_BY_PARTNER
            - FULFILLMENT_ERROR
        inventoryId:
          type: string
          format: uuid
          description: Order item's inventory id
        retrievalMethodStatus:
          type: string
          description: Retrieval method status
          enum:
            - REQUESTED
            - PROCESSED
            - CANCELLED
            - LABEL_CREATED
            - SHIPPED
            - DELIVERED
            - SENT_BACK
            - ARRIVED_AT_PROCESSING_FACILITY
            - DELIVERY_EXCEPTION
            - NOT_PROCESSED
            - PARTIALLY_PROCESSED
            - SCHEDULING_PICK_UP
          example: DELIVERED
        inboundTrackingLink:
          type: string
          description: Inbound tracking link for return kit
          example: https://tracking.example.com/123456
        inboundCarrier:
          type: string
          description: Inbound carrier for return kit
          example: UPS
        inboundTrackingCode:
          type: string
          description: Inbound tracking code for return kit
          example: 1Z999AA10123456784
        outboundTrackingLink:
          type: string
          description: Outbound tracking link for return kit
          example: https://tracking.example.com/789012
        outboundCarrier:
          type: string
          description: Outbound carrier for return kit
          example: FedEx
        outboundTrackingCode:
          type: string
          description: Outbound tracking code for return kit
          example: 1Z999AA10567890123
        itad:
          type: boolean
          description: Whether this item was elected for ITAD (IT Asset Disposition)
          example: false
        vendorSku:
          type: string
          description: Vendor's own SKU identifier.
          example: APL-MK183LL/A
        vendorCode:
          type: string
          description: Vendor short code.
          example: APPLE
        serialNumber:
          type: string
          description: Serial number assigned to the inventory unit, if any.
        holdRequested:
          type: boolean
          description: >-
            Whether a machine retention hold was requested for this item at
            return creation. Null when not applicable or enhanced fields are not
            enabled.
      required:
        - categoryCode
        - id
        - itad
        - skuId
        - status
        - title
    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
    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'
    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
    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
    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

````