> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/list-returns.md).

# List sales returns

> Returns a cursor-paginated list of active sales returns.

Ordered newest first by `return_time`, then by id (descending); the cursor follows this order. Line items, tags, and receiving progress are available from the single-return endpoint.

`GET https://rest.boxhero-app.com/v1/returns`

## 授權

- `Authorization` (string, 必填): `Bearer <token>` 格式的 Bearer 驗證標頭，其中 `<token>` 為您的 [API 權杖](https://www.boxhero.io/docs/zh-tw/developers/api/authentication.md)。

## 查詢參數

- `statuses` (string | array of string): Filter by one or more return statuses.
- `partner_id` (integer, minimum 0, maximum 2147483647): Filter by partner id.
- `return_number` (string): Filter by exact return number. Whitespace is ignored and letters are uppercased.
- `order_number` (string): Filter by exact source order number. Whitespace is ignored and letters are uppercased.
- `order_id` (integer, minimum 0, maximum 2147483647): Filter by source order id.
- `tags` (string | array of string): Filter by tags with all-match semantics.
- `returned_after` (string, date-time): Filter by return_time >= this timestamp.
- `returned_before` (string, date-time): Filter by return_time < this timestamp.
- `created_by_id` (integer, minimum 0, maximum 2147483647): Filter by creator member id.
- `cursor` (integer, minimum 0, maximum 2147483647): Page cursor. Pass the `cursor` field from the previous response to fetch the next page. Omit on the first call.
- `limit` (integer, minimum 1, maximum 100): Page size. Accepts `1`–`100`; defaults to `100`.

## 回應

**200** A page of sales returns.

- `items` (array of SimpleReturn, 必填): Items in this page. Most resources are ordered by id ascending; transactions and orders/returns are ordered by time descending (see each list endpoint).

  - `id` (integer, minimum 0, maximum 2147483647, 必填): Return id.
  - `return_number` (string, 必填): Return number.
  - `return_time` (string, date-time, 必填): Return date/time.
  - `status` (string, 必填): Return status. Recording stock through the return's transaction endpoints advances the status automatically: `confirmed` becomes `in-progress` once any quantity is received, and `done` once nothing remains. A `done` return is never reverted by such transaction changes.

    可能的值: `confirmed`, `in-progress`, `done`
  - `partner` (Entity, nullable, 必填): Customer for the sales return.

    - `id` (integer, minimum 0, maximum 2147483647, 必填): Id of the referenced entity.
    - `name` (string, 必填): Display name of the entity at the time the transaction was recorded.
    - `deleted` (boolean, 必填): `true` when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.
  - `order` (OrderRef, 必填): Reference to the source sales order for a return.

    - `id` (integer, minimum 0, maximum 2147483647, 必填): Order id.
    - `order_number` (string, 必填): Order number.
  - `total_price` (string, 必填): Return total as a decimal string.
  - `currency_code` (string, nullable, 必填): Source sales order ISO currency code, or null when unset.
  - `memo` (string, 必填): Free-text memo. Empty string when not set.
  - `revision` (integer, minimum -9007199254740991, maximum 9007199254740991, 必填): Optimistic-concurrency version.
  - `created_by` (Entity, 必填): Reference to a related entity (location, partner, or user) embedded in a transaction. The snapshot is captured at transaction time and does not update if the source entity is later renamed or removed.

    - `id` (integer, minimum 0, maximum 2147483647, 必填): Id of the referenced entity.
    - `name` (string, 必填): Display name of the entity at the time the transaction was recorded.
    - `deleted` (boolean, 必填): `true` when the underlying entity has since been deleted. The embedded snapshot is preserved so historical transactions remain readable.
  - `created_at` (string, date-time, 必填): Server-side creation timestamp.
  - `url` (string, uri, 必填): Web URL to view this return in the BoxHero app.
  - `count_of_items` (integer, minimum 0, maximum 9007199254740991, 必填): Number of return lines.
  - `total_quantity` (number, 必填): Sum of returned quantities. Bundle lines are exploded into component item quantities.
- `count` (integer, minimum 0, maximum 9007199254740991, 必填): Number of items in this page (`items.length`).
- `limit` (integer, minimum 0, maximum 9007199254740991, 必填): Page size used to build this response.
- `cursor` (integer, minimum 0, maximum 2147483647, nullable, 必填): Cursor to pass as `cursor` in the next request. `null` when `has_more` is `false`.
- `has_more` (boolean, 必填): True when another page is available. The cursor is monotonic — pass it as `cursor` on the next request to advance the page. Direction follows each resource's ordering (most resources: id ascending; transactions and orders/returns: time descending).

**400** Query validation failed, or the team is not in LOCATION mode.

- `id` (string, 必填): Unique exception id (`ex_` followed by 32 lowercase hex chars, no dashes — e.g. `ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a`). Quote this in support tickets so we can find the request in our logs.
- `type` (string, 必填): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  可能的值: `/errors/not-found`, `/errors/invalid-request`, `/errors/invalid-team-mode`, `/errors/tokens/invalid`, `/errors/tokens/required`, `/errors/too-many-requests`, `/errors/core/usage-limit-exceeded`, `/errors/core/forbidden`, `/errors/core/unhandled`, `/errors/unhandled`
- `title` (string, 必填): Human-readable summary of the error, in English.
- `correlationID` (string, 必填): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. A client-supplied `X-Correlation-Id` request header (at most 128 chars of `A-Z a-z 0-9 . _ : / = -`) is echoed back here and in the response header; a missing or invalid value is silently replaced with a generated `rq_…` id.
- `instance` (string): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix. Absent on unknown-path `404` and unexpected `500` responses.
- `code` (string): Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. `not-available-for-api-token` on 403). Use this for fine-grained branching after dispatching on `type`.
- `errors` (array of object): Field-level error details. Present on request-validation `/errors/invalid-request` (400) responses. Absent on malformed-JSON `400`, `413` body-too-large, and most errors mapped from BoxHero core (which include it only when core supplies an array; this can include `403`). Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

  - `path` (array of string | number, 必填)
  - `message` (string, 必填)

**401** Missing, invalid, or revoked API token. `/errors/tokens/required` when no Bearer token is sent; `/errors/tokens/invalid` when the token is unknown or revoked (a revoked token may keep working for up to 60 seconds because validation results are cached).

- `id` (string, 必填): Unique exception id (`ex_` followed by 32 lowercase hex chars, no dashes — e.g. `ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a`). Quote this in support tickets so we can find the request in our logs.
- `type` (string, 必填): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  可能的值: `/errors/not-found`, `/errors/invalid-request`, `/errors/invalid-team-mode`, `/errors/tokens/invalid`, `/errors/tokens/required`, `/errors/too-many-requests`, `/errors/core/usage-limit-exceeded`, `/errors/core/forbidden`, `/errors/core/unhandled`, `/errors/unhandled`
- `title` (string, 必填): Human-readable summary of the error, in English.
- `correlationID` (string, 必填): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. A client-supplied `X-Correlation-Id` request header (at most 128 chars of `A-Z a-z 0-9 . _ : / = -`) is echoed back here and in the response header; a missing or invalid value is silently replaced with a generated `rq_…` id.
- `instance` (string): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix. Absent on unknown-path `404` and unexpected `500` responses.
- `code` (string): Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. `not-available-for-api-token` on 403). Use this for fine-grained branching after dispatching on `type`.
- `errors` (array of object): Field-level error details. Present on request-validation `/errors/invalid-request` (400) responses. Absent on malformed-JSON `400`, `413` body-too-large, and most errors mapped from BoxHero core (which include it only when core supplies an array; this can include `403`). Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

  - `path` (array of string | number, 必填)
  - `message` (string, 必填)

**429** Rate limit exceeded. Limits are per team and shared by all of the team's API tokens: 5 requests per second and 300 requests per minute. The `RateLimit` and `X-RateLimit-*` headers reflect the per-minute window; check them and `Retry-After` before retrying. This status is also returned when the client IP exceeds 30 failed authentication attempts within 60 seconds, even if the token is valid.

- `id` (string, 必填): Unique exception id (`ex_` followed by 32 lowercase hex chars, no dashes — e.g. `ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a`). Quote this in support tickets so we can find the request in our logs.
- `type` (string, 必填): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  可能的值: `/errors/not-found`, `/errors/invalid-request`, `/errors/invalid-team-mode`, `/errors/tokens/invalid`, `/errors/tokens/required`, `/errors/too-many-requests`, `/errors/core/usage-limit-exceeded`, `/errors/core/forbidden`, `/errors/core/unhandled`, `/errors/unhandled`
- `title` (string, 必填): Human-readable summary of the error, in English.
- `correlationID` (string, 必填): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. A client-supplied `X-Correlation-Id` request header (at most 128 chars of `A-Z a-z 0-9 . _ : / = -`) is echoed back here and in the response header; a missing or invalid value is silently replaced with a generated `rq_…` id.
- `instance` (string): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix. Absent on unknown-path `404` and unexpected `500` responses.
- `code` (string): Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. `not-available-for-api-token` on 403). Use this for fine-grained branching after dispatching on `type`.
- `errors` (array of object): Field-level error details. Present on request-validation `/errors/invalid-request` (400) responses. Absent on malformed-JSON `400`, `413` body-too-large, and most errors mapped from BoxHero core (which include it only when core supplies an array; this can include `403`). Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

  - `path` (array of string | number, 必填)
  - `message` (string, 必填)

請求

**cURL**

```bash
curl --request GET \
  --url 'https://rest.boxhero-app.com/v1/returns' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN"
```

**JavaScript**

```javascript
const response = await fetch("https://rest.boxhero-app.com/v1/returns", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
  },
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://rest.boxhero-app.com/v1/returns",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
)
data = response.json()
```

**HTTP**

```http
GET /v1/returns HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
```

回應

**200**

```json
{
  "items": [
    {
      "id": 90301,
      "return_number": "R-1001",
      "return_time": "2026-01-15T09:30:00.000Z",
      "status": "done",
      "partner": {
        "id": 431488,
        "name": "Northwind Retail",
        "deleted": false
      },
      "order": {
        "id": 90201,
        "order_number": "SO-2001"
      },
      "total_price": "99.95",
      "currency_code": "USD",
      "memo": "",
      "revision": 3,
      "created_by": {
        "id": 1001,
        "name": "John Smith",
        "deleted": false
      },
      "created_at": "2026-01-15T09:30:00.000Z",
      "url": "https://app.boxhero-app.com/returns/90301",
      "count_of_items": 1,
      "total_quantity": 5
    }
  ],
  "count": 1,
  "limit": 100,
  "cursor": null,
  "has_more": false
}
```

**400**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-request",
  "title": "Query validation failed, or the team is not in LOCATION mode.",
  "instance": "/returns"
}
```

**401**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/tokens/required",
  "title": "Missing API token. Provide a Bearer token in the Authorization header.",
  "instance": "/returns",
  "example": "Bearer wqnot0dlysdg5vymubzi4kiv"
}
```

**429**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/too-many-requests",
  "title": "Too many requests.",
  "instance": "/returns",
  "retryAfter": 60
}
```