> 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.md).

# Returns

> Sales returns anchored to sales orders.

Read endpoints expose line detail and per-item receiving progress.

## Return 物件

A sales return with lines, per-item receiving progress, and linked transactions.

- `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.
- `tags` (array of string, 必填): Read-only tags parsed from the memo.
- `items` (array of ReturnLine, 必填): Detailed return lines.

  - `id` (integer, minimum 0, maximum 2147483647, 必填): Return line id.
  - `rank` (integer, minimum -9007199254740991, maximum 9007199254740991, 必填): Line rank in the return.
  - `order_item_id` (integer, minimum 0, maximum 2147483647, 必填): Source order line id.
  - `item` (ExtendedItemEntity, nullable, 必填): Set when the line references a single item.

    - `id` (integer, minimum 0, maximum 2147483647, 必填): Item or bundle id.
    - `name` (string, 必填): Display name.
    - `sku` (string, 必填): SKU. Empty string when unset.
    - `barcode` (string, 必填): Barcode. Empty string when unset.
    - `deleted` (boolean, 必填): Whether the underlying item or bundle is deleted.
  - `bundle` (ExtendedItemEntity, nullable, 必填): Set when the line references a bundle.

    - `id` (integer, minimum 0, maximum 2147483647, 必填): Item or bundle id.
    - `name` (string, 必填): Display name.
    - `sku` (string, 必填): SKU. Empty string when unset.
    - `barcode` (string, 必填): Barcode. Empty string when unset.
    - `deleted` (boolean, 必填): Whether the underlying item or bundle is deleted.
  - `price` (string, 必填): Returned line amount, not a unit price: the source order line's total (including tax and discount) scaled by returned quantity / ordered quantity. Equal to `subtotal` and `total`.
  - `quantity` (number, 必填): Quantity. May include up to four decimal places in core data.
  - `tax_name` (string, nullable, 必填): Always null on return lines.
  - `tax_rate` (string, nullable, 必填): Always null on return lines.
  - `tax_inclusive` (boolean, nullable, 必填): Always null on return lines.
  - `discount_name` (string, nullable, 必填): Always null on return lines.
  - `discount_type` (string, nullable, 必填): Always null on return lines.

    可能的值: `percent`, `amount`
  - `discount_value` (string, nullable, 必填): Always null on return lines.
  - `subtotal` (string, 必填): Same as `price`: the returned line amount.
  - `discount_amount` (string, 必填): Always "0"; any source discount is already reflected in `price`.
  - `tax_amount` (string, 必填): Always "0"; any source tax is already reflected in `price`.
  - `total` (string, 必填): Same as `price`: the returned line amount.
- `tx_items` (array of FulfillmentTxItem, 必填): Per-item receiving progress. Bundle return lines are exploded and duplicate items are collapsed.

  - `item` (ExtendedItemEntity, 必填): Reference to an item or bundle embedded in order, return, transaction, and bundle component responses.

    - `id` (integer, minimum 0, maximum 2147483647, 必填): Item or bundle id.
    - `name` (string, 必填): Display name.
    - `sku` (string, 必填): SKU. Empty string when unset.
    - `barcode` (string, 必填): Barcode. Empty string when unset.
    - `deleted` (boolean, 必填): Whether the underlying item or bundle is deleted.
  - `ordered_quantity` (number, 必填): Ordered or returned quantity for this item. Bundle lines are exploded into component quantities and duplicate items are collapsed.
  - `fulfilled_quantity` (number, 必填): Absolute quantity already fulfilled or received for this item.
  - `pending_quantity` (number, 必填): Remaining quantity for this item, clamped to zero when over-fulfilled.
- `transactions` (array of OrderTransactionSummary, 必填): Inventory transactions linked to this return.

  - `id` (integer, minimum 0, maximum 2147483647, 必填): Location transaction id.
  - `type` (string, 必填): Fulfillment direction of an order-linked transaction.

    可能的值: `in`, `out`
  - `transaction_time` (string, date-time, 必填): Effective transaction time.
  - `to_location` (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.
  - `count_of_items` (integer, minimum 0, maximum 9007199254740991, 必填)
  - `total_quantity` (number, 必填): Quantity. May include up to four decimal places in core data.

範例

```json
{
  "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",
  "tags": [],
  "items": [
    {
      "id": 700301,
      "rank": 0,
      "order_item_id": 700201,
      "item": {
        "id": 14290445,
        "name": "Finish Setting Powder",
        "sku": "SKU-12345678",
        "barcode": "2097678335587",
        "deleted": false
      },
      "bundle": null,
      "price": "99.95",
      "quantity": 5,
      "tax_name": null,
      "tax_rate": null,
      "tax_inclusive": null,
      "discount_name": null,
      "discount_type": null,
      "discount_value": null,
      "subtotal": "99.95",
      "discount_amount": "0",
      "tax_amount": "0",
      "total": "99.95"
    }
  ],
  "tx_items": [
    {
      "item": {
        "id": 14290445,
        "name": "Finish Setting Powder",
        "sku": "SKU-12345678",
        "barcode": "2097678335587",
        "deleted": false
      },
      "ordered_quantity": 5,
      "fulfilled_quantity": 5,
      "pending_quantity": 0
    }
  ],
  "transactions": [
    {
      "id": 14012345,
      "type": "in",
      "transaction_time": "2026-01-16T11:00:00.000Z",
      "to_location": {
        "id": 47041,
        "name": "Warehouse",
        "deleted": false
      },
      "count_of_items": 1,
      "total_quantity": 5
    }
  ]
}
```

## 端點

- [List sales returns](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/list-returns.md) `GET /v1/returns`
- [Create a sales return](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/create-return.md) `POST /v1/returns`
- [Get a sales return](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/get-return.md) `GET /v1/returns/{return_id}`
- [Update a sales return](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/update-return.md) `PUT /v1/returns/{return_id}`
- [Delete a sales return](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/delete-return.md) `DELETE /v1/returns/{return_id}`
- [Receive returned quantities](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/create-return-transaction.md) `POST /v1/returns/{return_id}/transactions`
- [Receive all remaining returned quantities](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/complete-return-transactions.md) `POST /v1/returns/{return_id}/transactions/complete`
- [Get a sales return by return number](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/get-return-by-number.md) `GET /v1/returns/by-number/{return_number}`
- [Update a sales return by return number](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/update-return-by-number.md) `PUT /v1/returns/by-number/{return_number}`
- [Delete a sales return by return number](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/delete-return-by-number.md) `DELETE /v1/returns/by-number/{return_number}`
- [Receive returned quantities by return number](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/create-return-transaction-by-number.md) `POST /v1/returns/by-number/{return_number}/transactions`
- [Receive all remaining returned quantities by return number](https://www.boxhero.io/docs/zh-tw/developers/api/reference/returns/complete-return-transactions-by-number.md) `POST /v1/returns/by-number/{return_number}/transactions/complete`