List returns · Bigblue Developers

POST/bigblue.storeapi.v1.PublicAPI/ListReturns

Returns returns one page at a time. Filter by order or by creation date, but not both. Without a filter, you get every return on the account.

Request body

orderstring

Only return returns for this order. The date range is ignored when this is set.

date_rangeDateRange

Only return returns created in this period, RFC 3339 UTC.

page_sizeinteger

Returns per page. Uses a server default when 0 or missing.

page_tokenstring

The next_page_token from the previous response.

date_range filters on create_time. To find returns received in a period, filter on return_time in your code.

Responses

200A page of returns.

returnsReturn[]

The returns on this page.

next_page_tokenstring

Token for the next page. Missing on the last page.

400A date is invalid.

{
  "code": "invalid_argument",
  "msg": "date_range.from value does not match regex pattern `\\d+-\\d+-\\d+T\\d+:\\d+:\\d+Z`",
  "meta": { "argument": "date_range.from" }
}

POST/bigblue.storeapi.v1.PublicAPI/ListReturns

Request: one order

{ "order": "BGBL0K3M9XQ2" }

Request: one week

{
  "date_range": {
    "from": "2026-03-16T00:00:00Z",
    "to": "2026-03-23T00:00:00Z"
  },
  "page_size": 100
}

200

{
  "returns": [
    {
      "id": "BGBL0K3M9XQ2RT01",
      "order": "BGBL0K3M9XQ2",
      "warehouse": "FR-CDG-001",
      "status": "RETURN_STATUS_RETURNED",
      "resolution_status": "RETURN_RESOLUTION_STATUS_ACTION_REQUIRED",
      "create_time": "2026-03-20T10:15:00Z",
      "return_time": "2026-03-23T09:40:00Z"
    }
  ],
  "next_page_token": "ChoKGAoHcmV0dXJucxINQkdCTDBLM005WFEy"
}