# List returns

Returns all returns across all sales channels belonging to the authenticated merchant.

See the Pagination section in the API overview above for details on how pagination works.

Endpoint: GET /returns
Version: 2.0.0
Security: BearerAuth

## Query parameters:

  - `sales_channel_id[in]` (array)
    Filter results by one or more sales channel ID

  - `created_at[gt]` (string)
    Filter results created after this date (ISO 8601 format)

  - `created_at[lt]` (string)
    Filter results created before this date (ISO 8601 format)

  - `created_at[gte]` (string)
    Filter results created on or after this date (ISO 8601 format)

  - `created_at[lte]` (string)
    Filter results created on or before this date (ISO 8601 format)

  - `limit` (integer)
    Number of items to return per page (for pagination)

## Response 200 fields (application/json):

  - `data` (array)

  - `data.announced_items` (array, required)
    List of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.

  - `data.announced_items.customer_return_message` (string)
    Reason details provided by the customer

  - `data.announced_items.customer_return_reason` (string)
    Reason provided by the customer

  - `data.announced_items.id` (integer, required)
    Hive's unique identifier

  - `data.announced_items.quantity` (integer, required)
    Quantity of items announced

  - `data.announced_items.sku` (object, required)
    SKU details for a returned item

  - `data.announced_items.sku.id` (integer, required)
    Hive's unique SKU identifier

  - `data.announced_items.sku.sku_code` (string, required)
    Merchant's SKU code

  - `data.carrier` (string,null)
    Carrier name

  - `data.completed_handling_at` (string,null)
    When the return handling finished

  - `data.created_at` (string, required)
    When the return was created

  - `data.handled_items` (array)
    List of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.

  - `data.handled_items.condition` (string)
    Condition of the returned item. Possible values:
- A: Unused and in original packaging
- B: Unused with missing/damaged packaging
- C: Product is used or damaged
    Enum: "A", "B", "C"

  - `data.handled_items.follow_up_action` (string)
    Action to be performed on the returned item. Those actions are pre-selected based on return rules (Hive account manager inserts return rules into the system after negotiation with a merchant).
Possible values:
- dispose: Dispose of the item
- restock: Restock the item for sale
- send_back: Send the item back to the merchant
    Enum: "dispose", "restock", "send_back"

  - `data.handled_items.inventory_batch_id` (integer,null)
    Unique identifier in Hive system of the inventory batch (if present) into which returned item is going to be restocked (relevant only when follow_up_action = restock)

  - `data.handled_items.photos` (array)
    Photos of the returned item

  - `data.handled_items.photos.image_url` (string, required)
    Publicly accessible URL (for 15 minutes)

  - `data.handled_items.quantity` (integer, required)
    The quantity of items returned for the same SKU

  - `data.handled_items.return_item_id` (integer,null)
    Announced return item's unique identifier in Hive system (can be blank, e.g. when the return is not a Customer Portal return)

  - `data.order` (object, required)
    Details of the associated order

  - `data.order.customer_order_number` (string, required)
    Customer's order identifier

  - `data.order.id` (integer, required)
    Hive's unique order identifier

  - `data.order.merchant_order_id` (string, required)
    Merchant's unique order identifier

  - `data.photos` (array)
    Photos of the returned items

  - `data.photos.photo_type` (string, required)
    Type of photo. Usual values "inside" or "outside"

  - `data.received_at` (string,null)
    When the return was received

  - `data.return_reason` (any)

  - `data.return_reason_type` (any)

  - `data.started_processing_at` (string,null)
    When processing at the fulfillment center started

  - `data.status` (string, required)
    Status of the return. Possible values:
- action_required: Waiting for merchant guidance
- arrived: Arrived at fulfillment center
- handling_completed: Return processing completed
- on_the_way: On the way to fulfillment center
- processing: Return processing in progress
    Enum: "action_required", "arrived", "handling_completed", "on_the_way", "processing"

  - `data.tracking_code` (string,null)
    Tracking number assigned by the carrier

  - `data.tracking_url` (string,null)
    Carrier website showing tracking information

  - `data.updated_at` (string, required)

  - `pagination` (object)

  - `pagination.first_page_url` (string)
    URL to fetch the first page of results

  - `pagination.limit` (integer)
    Number of items returned per page

  - `pagination.next_page_url` (string,null)
    URL to fetch the next page of results. If null, there are no more results.

## Response 401 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 403 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 429 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code