Create a return

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"
    }
  ]
}

POST

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

Body

application/json

Request to create a return order

personId

string<uuid>

required

ID of the person the return is for

Example:

"123e4567-e89b-12d3-a456-426614174000"

returnItems

object[]

required

Items to include in the return

Minimum array length: 1

Show child attributes

requestAddressConfirmation

boolean

required

Whether to request address confirmation from the person before shipping the return kit

returnKitAddress

object

Address for the return kit shipment. Required when requestAddressConfirmation is false (the default). Omit only when requestAddressConfirmation is true, in which case the person is prompted to confirm their address before the kit ships.

Show child attributes

officeId

string<uuid>

Office ID to return equipment to. When provided, returnTo is set to OFFICE and returnMethod is forced to SHIPMENT

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Return order created

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

List all returns Get a single return order by ID

⌘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

Body

Response