API ReferenceReturns

Get Return Orders

View as Markdown
Retrieves a paginated list of return orders with optional filters for IDs, statuses, dates, and other criteria. Use this to track all returns across your ShipBob account.

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token or OAuth2

Headers

shipbob_channel_idstringOptionalformat: "int32"

Retrieve your channel ID from the GET /channel endpoint. Use the channel ID that has write scopes.

Query parameters

IdsstringOptional

The IDs of the returns to fetch. Accepts a comma-separated list of return IDs (e.g., 123,456,789).

ReferenceIdsstringOptional

Comma-separated list of return reference IDs (RMA numbers) to filter by.

StatusstringOptional

Comma-separated list of return statuses to filter by (e.g., AwaitingArrival,Arrived,Processing,Completed,Cancelled).

FulfillmentCenterIdsstringOptional

Comma-separated list of fulfillment center IDs to filter by.

TrackingNumbersstringOptional

Comma-separated list of tracking numbers to filter by.

OriginalShipmentIdsstringOptional

Comma-separated list of original shipment IDs to filter by.

InventoryIdsstringOptional

Comma-separated list of inventory IDs to filter by.

StartDatedatetimeOptional

Filter returns created on or after this date (ISO 8601 format).

EndDatedatetimeOptional

Filter returns created on or before this date (ISO 8601 format).

ReturnTypesstringOptional

Comma-separated list of return types to filter by (e.g., Regular,ReturnToSender).

ReturnActionsstringOptional

Comma-separated list of return actions to filter by (e.g., Restock,Quarantine,Dispose).

StoreOrderIdsstringOptional

Comma-separated list of store order IDs to filter by.

SortbystringOptional
Field to sort results by.
CompletedStartDatedatetimeOptional

Filter returns completed on or after this date (ISO 8601 format).

CompletedEndDatedatetimeOptional

Filter returns completed on or before this date (ISO 8601 format).

CursorintegerOptional1-2147483647
Page number to retrieve. Used for pagination through result sets.
LimitintegerOptional
Maximum number of records to return per page.
SortOrderenumOptional

Sort order for results. Desc = newest to oldest, Asc = oldest to newest, Desc is default

Allowed values:

Response headers

Page-Numberstring or null
Current page number
Total-Pagesstring or null
Total pages
Total-Countstring or null
Total records
Page-Sizestring or null
Page size

Response

OK
firststring or nullformat: "uri"
Return url for first cursor
itemslist of objects or null
Return records
laststring or nullformat: "uri"
Return url for last cursor
nextstring or nullformat: "uri"
Return url for next cursor
prevstring or nullformat: "uri"
Return url for prev cursor

Errors