cURL
curl -sS -X GET 'https://apipub.firstbasehq.com/api/v1/returns?page=1&size=10&sortBy=createdAt&sortDirection=DESC' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json'import requests
url = "https://apipub.firstbasehq.com/api/v1/returns"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://apipub.firstbasehq.com/api/v1/returns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));[
{
"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"
}
]
},
"returnReason": "OFFBOARDING",
"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 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
},
"status": "CONFIRMED",
"replacement": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-12-25",
"status": "SUBMITTED",
"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"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"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 Sesame Street",
"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",
"deliveryLocation": "PERSON"
}
},
"returnLifecycleType": "ONE_OFF",
"submittedBy": null,
"office": null,
"person": null,
"deliveryLocation": "FIRSTBASE",
"personLastDay": "2026-01-31"
}
]{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Returns
List 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.
GET
https://apipub.firstbasehq.com
/
api
/
v1
/
returns
cURL
curl -sS -X GET 'https://apipub.firstbasehq.com/api/v1/returns?page=1&size=10&sortBy=createdAt&sortDirection=DESC' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json'import requests
url = "https://apipub.firstbasehq.com/api/v1/returns"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://apipub.firstbasehq.com/api/v1/returns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));[
{
"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"
}
]
},
"returnReason": "OFFBOARDING",
"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 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
},
"status": "CONFIRMED",
"replacement": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-12-25",
"status": "SUBMITTED",
"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"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"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 Sesame Street",
"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",
"deliveryLocation": "PERSON"
}
},
"returnLifecycleType": "ONE_OFF",
"submittedBy": null,
"office": null,
"person": null,
"deliveryLocation": "FIRSTBASE",
"personLastDay": "2026-01-31"
}
]{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Authorizations
Query Parameters
Filter by the return order's status.
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 Filter by retrieval method (return kit) statuses.
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 Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.
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 Response
Paginated list of return orders