List all returns

Error

A valid request URL is required to generate request examples

[
  {
    "id": "ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4",
    "retrievals": [
      {
        "methodType": "RETURN_KIT",
        "items": [
          {
            "id": "123E4567-E89B-12D3-A456-426614174000",
            "skuId": "123E4567-E89B-12D3-A456-426614174000",
            "title": "iPad Air - Silver, 64GB, WiFi",
            "categoryCode": "COMPUTER",
            "status": "PROCESSING",
            "itad": false,
            "shipment": {
              "trackingUrl": "<string>",
              "trackingCode": "1Z00000000",
              "carrier": "UPS",
              "status": "DELIVERED",
              "trackingHistory": [
                {
                  "status": "IN_TRANSIT",
                  "timestamp": "2023-11-07T05:31:56Z"
                }
              ]
            },
            "inventoryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "retrievalMethodStatus": "DELIVERED",
            "inboundTrackingLink": "https://tracking.example.com/123456",
            "inboundCarrier": "UPS",
            "inboundTrackingCode": "1Z999AA10123456784",
            "outboundTrackingLink": "https://tracking.example.com/789012",
            "outboundCarrier": "FedEx",
            "outboundTrackingCode": "1Z999AA10567890123",
            "vendorSku": "APL-MK183LL/A",
            "vendorCode": "APPLE",
            "serialNumber": "<string>",
            "holdRequested": true
          }
        ]
      }
    ],
    "personId": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
    "supportTicketId": 12345,
    "createdAt": "2025-11-26",
    "updatedAt": "2025-11-26",
    "confirmedAtTimestamp": "2025-11-27T10:15:00Z",
    "shippingAddress": {
      "countryCode": "US",
      "addressLine1": 123,
      "addressLine2": "Suite 103",
      "administrativeArea": "NY",
      "locality": "New York City",
      "postalCode": 10123
    },
    "status": "CONFIRMED",
    "replacement": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "createdAt": "2023-12-25",
      "order": {
        "id": "123E4567-E89B-12D3-A456-426614174000",
        "status": "COMPLETED",
        "orderItems": [
          {
            "id": "123E4567-E89B-12D3-A456-426614174000",
            "skuId": "123E4567-E89B-12D3-A456-426614174000",
            "title": "iPad Air - Silver, 64GB, WiFi",
            "categoryCode": "COMPUTER",
            "status": "PROCESSING",
            "statusHistory": [
              {
                "status": "APPROVED",
                "timestamp": "2023-01-01T12:00:00Z"
              }
            ],
            "shipment": {
              "trackingUrl": "<string>",
              "trackingCode": "1Z00000000",
              "carrier": "UPS",
              "status": "DELIVERED",
              "trackingHistory": [
                {
                  "status": "IN_TRANSIT",
                  "timestamp": "2023-11-07T05:31:56Z"
                }
              ]
            },
            "vendorSku": "APL-MK183LL/A",
            "vendorCode": "APPLE",
            "serialNumber": "C02XL0AAJG5L",
            "justification": "Need higher RAM for local development workflows",
            "purchaseOrderNumber": "PO-US-LAPTOPS-001"
          }
        ],
        "statusHistory": [
          {
            "status": "APPROVED",
            "timestamp": "2023-01-01T12:00:00Z"
          }
        ],
        "personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
        "officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
        "shippingAddress": {
          "countryCode": "US",
          "addressLine1": 123,
          "addressLine2": "Suite 103",
          "administrativeArea": "NY",
          "locality": "New York City",
          "postalCode": 10123
        },
        "submittedBy": "John S. (Firstbase)",
        "approvedBy": "Jane Smith",
        "approvedAt": "2026-02-26",
        "deliverToOffice": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "NYC HQ",
          "address": {
            "countryCode": "US",
            "addressLine1": 123,
            "addressLine2": "Suite 103",
            "administrativeArea": "NY",
            "locality": "New York City",
            "postalCode": 10123
          }
        },
        "deliverToPerson": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane.smith@example.com"
        },
        "createdAt": "2026-02-26T14:15:22.123Z",
        "updatedAt": "2026-03-15T09:00:00.000Z",
        "expectedBy": "2026-03-10",
        "packageSlug": "engineering-onboarding"
      }
    },
    "returnLifecycleType": "ONE_OFF",
    "submittedBy": {
      "id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
      "forename": "<string>",
      "surname": "<string>"
    },
    "office": {
      "id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
      "name": "<string>"
    },
    "person": {
      "id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
      "forename": "<string>",
      "surname": "<string>"
    }
  }
]

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

GET

api

returns

Error

A valid request URL is required to generate request examples

[
  {
    "id": "ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4",
    "retrievals": [
      {
        "methodType": "RETURN_KIT",
        "items": [
          {
            "id": "123E4567-E89B-12D3-A456-426614174000",
            "skuId": "123E4567-E89B-12D3-A456-426614174000",
            "title": "iPad Air - Silver, 64GB, WiFi",
            "categoryCode": "COMPUTER",
            "status": "PROCESSING",
            "itad": false,
            "shipment": {
              "trackingUrl": "<string>",
              "trackingCode": "1Z00000000",
              "carrier": "UPS",
              "status": "DELIVERED",
              "trackingHistory": [
                {
                  "status": "IN_TRANSIT",
                  "timestamp": "2023-11-07T05:31:56Z"
                }
              ]
            },
            "inventoryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "retrievalMethodStatus": "DELIVERED",
            "inboundTrackingLink": "https://tracking.example.com/123456",
            "inboundCarrier": "UPS",
            "inboundTrackingCode": "1Z999AA10123456784",
            "outboundTrackingLink": "https://tracking.example.com/789012",
            "outboundCarrier": "FedEx",
            "outboundTrackingCode": "1Z999AA10567890123",
            "vendorSku": "APL-MK183LL/A",
            "vendorCode": "APPLE",
            "serialNumber": "<string>",
            "holdRequested": true
          }
        ]
      }
    ],
    "personId": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
    "supportTicketId": 12345,
    "createdAt": "2025-11-26",
    "updatedAt": "2025-11-26",
    "confirmedAtTimestamp": "2025-11-27T10:15:00Z",
    "shippingAddress": {
      "countryCode": "US",
      "addressLine1": 123,
      "addressLine2": "Suite 103",
      "administrativeArea": "NY",
      "locality": "New York City",
      "postalCode": 10123
    },
    "status": "CONFIRMED",
    "replacement": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "createdAt": "2023-12-25",
      "order": {
        "id": "123E4567-E89B-12D3-A456-426614174000",
        "status": "COMPLETED",
        "orderItems": [
          {
            "id": "123E4567-E89B-12D3-A456-426614174000",
            "skuId": "123E4567-E89B-12D3-A456-426614174000",
            "title": "iPad Air - Silver, 64GB, WiFi",
            "categoryCode": "COMPUTER",
            "status": "PROCESSING",
            "statusHistory": [
              {
                "status": "APPROVED",
                "timestamp": "2023-01-01T12:00:00Z"
              }
            ],
            "shipment": {
              "trackingUrl": "<string>",
              "trackingCode": "1Z00000000",
              "carrier": "UPS",
              "status": "DELIVERED",
              "trackingHistory": [
                {
                  "status": "IN_TRANSIT",
                  "timestamp": "2023-11-07T05:31:56Z"
                }
              ]
            },
            "vendorSku": "APL-MK183LL/A",
            "vendorCode": "APPLE",
            "serialNumber": "C02XL0AAJG5L",
            "justification": "Need higher RAM for local development workflows",
            "purchaseOrderNumber": "PO-US-LAPTOPS-001"
          }
        ],
        "statusHistory": [
          {
            "status": "APPROVED",
            "timestamp": "2023-01-01T12:00:00Z"
          }
        ],
        "personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
        "officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
        "shippingAddress": {
          "countryCode": "US",
          "addressLine1": 123,
          "addressLine2": "Suite 103",
          "administrativeArea": "NY",
          "locality": "New York City",
          "postalCode": 10123
        },
        "submittedBy": "John S. (Firstbase)",
        "approvedBy": "Jane Smith",
        "approvedAt": "2026-02-26",
        "deliverToOffice": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "NYC HQ",
          "address": {
            "countryCode": "US",
            "addressLine1": 123,
            "addressLine2": "Suite 103",
            "administrativeArea": "NY",
            "locality": "New York City",
            "postalCode": 10123
          }
        },
        "deliverToPerson": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane.smith@example.com"
        },
        "createdAt": "2026-02-26T14:15:22.123Z",
        "updatedAt": "2026-03-15T09:00:00.000Z",
        "expectedBy": "2026-03-10",
        "packageSlug": "engineering-onboarding"
      }
    },
    "returnLifecycleType": "ONE_OFF",
    "submittedBy": {
      "id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
      "forename": "<string>",
      "surname": "<string>"
    },
    "office": {
      "id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
      "name": "<string>"
    },
    "person": {
      "id": "016fb454-066b-4ba5-9eca-a2fa14b7e7fc",
      "forename": "<string>",
      "surname": "<string>"
    }
  }
]

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

Authorizations

Authorization

string

header

required

Prefix the value with "ApiKey" to indicate the custom authorization type

Query Parameters

page

integer<int32>

The page number to request (1 based)

Required range: x >= 1

Example:

1

size

integer<int32>

The number of results to return in a page

Required range: x <= 500

Example:

10

personIDs

string<uuid>[]

The list of persons that will be returned

includeShipment

boolean

Include shipment data in the response

startDate

string<date-time>

UTC Date-time to filter orders created after (ISO-8601 without timezone)

Example:

"2007-12-03T10:15:30"

endDate

string<date-time>

UTC Date-time to filter orders created before (ISO-8601 without timezone)

Example:

"2007-12-03T10:15:30"

status

enum<string>[]

Filter by the return order's status.

Available options:

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

returnKitStatus

enum<string>[]

Filter by retrieval method (return kit) statuses.

Available options:

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

submittedBy

string<uuid>[]

Filter by person IDs who submitted the return

country

string[]

Filter by shipping address country codes

officeId

string<uuid>[]

Filter by office IDs (order's owning office)

vendorSku

string[]

Filter by vendor SKUs

skuId

string<uuid>[]

Filter by SKU IDs

serialNumber

string[]

Filter by inventory serial numbers

deliveryLocation

enum<string>[]

Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.

Available options:

OFFICE,

FIRSTBASE,

MULTIPLE,

FIRSTBASE,

OFFICE,

MULTIPLE

sortBy

string

Field to sort by (createdAt, updatedAt, country, deliveryLocation, status, person)

Example:

"createdAt"

sortDirection

string

Sort direction (ASC, DESC)

Example:

"DESC"

Response

Paginated list of return orders

string<uuid>

required

Return order ID

Example:

"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"

retrievals

object[]

required

Retrieval methods grouped by type. Always contains 4 entries: PL, RETURN_KIT, INBOUND, NOT_MAPPED

Show child attributes

personId

string<uuid>

Person ID

Example:

"016fb454-066b-4ba5-9eca-a2fa14b7e7fc"

supportTicketId

integer<int64>

Support ticket ID

Example:

12345

createdAt

string<date>

Created date

Example:

"2025-11-26"

updatedAt

string<date>

Updated date

Example:

"2025-11-26"

confirmedAtTimestamp

string<date-time>

Confirmed timestamp (UTC)

Example:

"2025-11-27T10:15:00Z"

shippingAddress

object

Shipping address

Show child attributes

status

enum<string>

Return order status

Available options:

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"

replacement

object

Replacement order if applicable

Show child attributes

returnLifecycleType

enum<string>

Return lifecycle type

Available options:

ONE_OFF,

OFFBOARDING

Example:

"ONE_OFF"

submittedBy

object

Person who submitted the return order.

Show child attributes

office

object

Office associated with the return, if any.

Show child attributes

person

object

Affected person reference (sibling to legacy personId).

Show child attributes

deliveryLocation

enum<string>

The return's delivery location (mirrors the FE Returns 'Delivery location' column). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.

Available options:

FIRSTBASE,

OFFICE,

MULTIPLE

Get a single shipment notice order by ID (V1)Create a return

⌘I

People

Shipment Notices V1

Returns

Replacements

People — Lifecycle

Packages

Orders

New Joiners

ITAD

Inventory

Inventory Orders

Inventory Levels

Assets

Return Orders

Offices

Warehouses V1

Shipment

Regions V1

Categories

Catalog

Brands

Authorizations

Query Parameters

Response