> ## 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 replacements in paginated result

> Returns a paginated list of replacement orders for the organization. A replacement is created when a defective or lost device needs to be swapped for a new one.



## OpenAPI

````yaml /openapi.json get /api/v1/replacements
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/replacements:
    get:
      tags:
        - Replacements
      summary: List all replacements in paginated result
      description: >-
        Returns a paginated list of replacement orders for the organization. A
        replacement is created when a defective or lost device needs to be
        swapped for a new one.
      operationId: listReplacements
      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: replacementOrderStatus
          in: query
          description: >-
            Filter by replacement order status (calculated from order and return
            statuses).
          required: false
          schema:
            type: array
            description: >-
              Filter by replacement order status (calculated from order and
              return statuses).
            enum:
              - SUBMITTED
              - PROCESSING
              - COMPLETED
              - PARTIALLY_COMPLETED
              - CANCELLED
            items:
              type: string
              description: >-
                Filter by replacement order status (calculated from order and
                return statuses).
              enum:
                - SUBMITTED
                - PROCESSING
                - COMPLETED
                - PARTIALLY_COMPLETED
                - CANCELLED
                - SUBMITTED
                - PROCESSING
                - COMPLETED
                - PARTIALLY_COMPLETED
                - CANCELLED
        - name: country
          in: query
          description: Filter by country codes
          required: false
          schema:
            type: array
            description: Filter by country codes
            items:
              type: string
              description: Filter by country codes
        - name: submittedBy
          in: query
          description: Filter by person IDs who submitted the replacement
          required: false
          schema:
            type: array
            description: Filter by person IDs who submitted the replacement
            items:
              type: string
              format: uuid
              description: Filter by person IDs who submitted the replacement
        - name: shipmentStatus
          in: query
          description: >-
            Filter by the shipment order status of the replacement's linked
            order.
          required: false
          schema:
            type: array
            description: >-
              Filter by the shipment order status of the replacement's linked
              order.
            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_DELIVERED
              - RETURN_KIT_SENT_BACK
              - RECEIVED_IN_WAREHOUSE
              - RETURNED
              - NOT_RETURNED
              - OUT_FOR_DELIVERY
              - DELIVERY_EXCEPTION
              - SUBMITTED
              - CANCELLED
              - CONFIRMED
              - NOT_COMPLETED
              - PARTIALLY_COMPLETED
            items:
              type: string
              description: >-
                Filter by the shipment order status of the replacement's linked
                order.
              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
                - 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_DELIVERED
                - RETURN_KIT_SENT_BACK
                - RECEIVED_IN_WAREHOUSE
                - RETURNED
                - NOT_RETURNED
                - OUT_FOR_DELIVERY
                - DELIVERY_EXCEPTION
                - SUBMITTED
                - CANCELLED
                - CONFIRMED
                - NOT_COMPLETED
                - PARTIALLY_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: 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 serial numbers
          required: false
          schema:
            type: array
            description: Filter by serial numbers
            items:
              type: string
              description: Filter by serial numbers
        - name: startDate
          in: query
          description: Filter replacements created after this date (ISO-8601)
          required: false
          schema:
            type: string
            format: date
            description: Filter replacements created after this date (ISO-8601)
            example: '2024-01-01'
          example: '2024-01-01'
        - name: endDate
          in: query
          description: Filter replacements created before this date (ISO-8601)
          required: false
          schema:
            type: string
            format: date
            description: Filter replacements created before this date (ISO-8601)
            example: '2024-12-31'
          example: '2024-12-31'
        - name: sortBy
          in: query
          description: Field to sort by (createdAt, country, person, status)
          required: false
          schema:
            type: string
            description: Field to sort by (createdAt, country, person, status)
            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: A paginated list of replacement orders matching the filter criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicAPIGetReplacementResponse'
        '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:
    PublicAPIGetReplacementResponse:
      type: object
      description: Replacement details
      properties:
        id:
          type: string
          format: uuid
          description: Replacement ID
          example: 123E4567-E89B-12D3-A456-426614174000
        status:
          type: string
          description: Replacement status
          enum:
            - SUBMITTED
            - PROCESSING
            - COMPLETED
            - PARTIALLY_COMPLETED
            - CANCELLED
          example: SUBMITTED
        createdAt:
          type: string
          format: date
          description: Date the replacement was created
          example: '2025-01-15'
        person:
          $ref: '#/components/schemas/PublicApiPersonRef'
          description: Person associated with the replacement
        submittedBy:
          $ref: '#/components/schemas/PublicApiPersonRef'
          description: Person who submitted the replacement
        order:
          $ref: '#/components/schemas/PublicAPIGetOrderResponse'
          description: Replacement order details
        returnOrder:
          $ref: '#/components/schemas/PublicAPIGetOrderResponse'
          description: Return order details
      required:
        - createdAt
        - id
        - status
    PublicApiHttpErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiError'
      required:
        - errors
    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
    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
    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
    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
    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

````