Get a single return order by ID

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

{id}

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

Path Parameters

string<uuid>

required

Query Parameters

includeShipment

boolean

Response

The requested return order

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

Create a return List all replacements in paginated result

⌘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

Get a single return order by ID

Authorizations

Path Parameters

Query Parameters

Response