> ## Documentation Index
> Fetch the complete documentation index at: https://api.basedock.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Base.com Order Returns: Download, Status, and Refunds

> Use getOrderReturns to sync return requests from Base.com. Covers statuses, refund recording, extra fields, and the return change journal.

Order returns in Base work analogously to orders and have their own mirrored block of API methods. You can download, filter, and manage returns using dedicated endpoints that closely mirror the patterns you already know from working with orders.

## The main method: `getOrderReturns`

[`getOrderReturns`](https://api.baselinker.com/index.php?method=getOrderReturns) downloads returns from Base from a given date, with a maximum of 100 records per call — the same pagination principle as [`getOrders`](https://api.baselinker.com/index.php?method=getOrders).

| Parameter                                                      | Type       | Description                                                                                                               |
| -------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| `order_id`                                                     | int        | ID of the original order the return was created from.                                                                     |
| `return_id`                                                    | int        | Downloads a single specific return.                                                                                       |
| `date_from`                                                    | int (unix) | Return creation date to start collecting from.                                                                            |
| `id_from`                                                      | int        | Return ID to start collecting from.                                                                                       |
| `status_id`                                                    | int        | Limits results to a specific return status.                                                                               |
| `filter_order_return_source` / `filter_order_return_source_id` | —          | Filter by return source (marketplace code).                                                                               |
| `include_custom_extra_fields`                                  | bool       | Adds custom extra field values — see Extra fields; the same principle applies to returns via `getOrderReturnExtraFields`. |

<Note>
  Unlike orders, there is **no confirmed/unconfirmed concept** for returns — there is no `date_confirmed` field. Page through results using `date_from` (incrementing the last processed record's timestamp by +1 second), or `id_from`.
</Note>

## Key response fields

| Field                                                                      | Description                                                                                                                                                                    |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `return_id` / `order_id`                                                   | Return ID and the original order's ID.                                                                                                                                         |
| `status_id`                                                                | Return status — retrieve the full list via [`getOrderReturnStatusList`](https://api.baselinker.com/index.php?method=getOrderReturnStatusList), same concept as order statuses. |
| `fulfillment_status`                                                       | Numeric processing state: `0` = active, `5` = accepted, `1` = done, `2` = cancelled.                                                                                           |
| `refunded`                                                                 | Whether the return has already been refunded.                                                                                                                                  |
| `order_return_account_number` / `order_return_iban` / `order_return_swift` | Bank details for refunding the customer.                                                                                                                                       |
| `products`                                                                 | Returned line items — same structure as an order line item, plus `return_reason_id`.                                                                                           |

## Working with statuses and refunds

Return statuses are read and written analogously to orders:

* [`getOrderReturnStatusList`](https://api.baselinker.com/index.php?method=getOrderReturnStatusList) — fetch all configured return statuses.
* [`setOrderReturnStatus`](https://api.baselinker.com/index.php?method=setOrderReturnStatus) / [`setOrderReturnStatuses`](https://api.baselinker.com/index.php?method=setOrderReturnStatuses) — update the status on one or multiple returns.
* [`getOrderReturnReasonsList`](https://api.baselinker.com/index.php?method=getOrderReturnReasonsList) — retrieve the configured return reasons (why a customer is sending the item back).
* [`setOrderReturnRefund`](https://api.baselinker.com/index.php?method=setOrderReturnRefund) — marks a return as refunded.

<Warning>
  `setOrderReturnRefund` **does not trigger any actual payment**. It only records the refund information inside Base. Any real money transfer must be handled through your payment provider separately.
</Warning>

## Tracking changes over time

Just like orders, returns have their own journal. Use [`getOrderReturnJournalList`](https://api.baselinker.com/index.php?method=getOrderReturnJournalList) to poll for recent changes — it follows the same principle and activation requirement as [`getJournalList`](https://api.baselinker.com/index.php?method=getJournalList) for orders.

<Note>
  You must enable journal access in your Base account before using this endpoint: go to **Profile → API** and activate the journal for returns.
</Note>

## Returns from marketplace channels

For selected marketplace channels, Base can automatically fetch return requests directly from customers and create returns from them. This is configured per sales channel in the Base panel. Once enabled, you simply monitor new returns as described above — no additional API calls are needed to pull them in.

## Return shipping labels

If you also handle return shipping, the principle is identical to generating standard shipment labels. Use the same shipping label methods, but pass `return_shipment: true` in your request. See [Shipping Labels](/orders/shipping-labels) for full details.