# Returns

## The Return resource

<table><thead><tr><th width="222">Property</th><th width="208">Type</th><th>Description</th></tr></thead><tbody><tr><td>carrier</td><td>String</td><td>Carrier name</td></tr><tr><td>completed_handling_at</td><td>ISO8601 datetime</td><td>When the return handling finished</td></tr><tr><td>created_at</td><td>ISO8601 datetime</td><td>When the return was created</td></tr><tr><td>id</td><td>Integer</td><td>Hive's unique identifier</td></tr><tr><td>order</td><td>A <a href="#the-returnorder-resource">ReturnOrder</a> object</td><td>Details of the associated order</td></tr><tr><td>photos</td><td>An array of <a href="#the-returnphoto-resource">ReturnPhoto</a> objects</td><td>Photos of the returned items</td></tr><tr><td>received_at</td><td>ISO8601 datetime</td><td>When the return was received</td></tr><tr><td>return_items</td><td>An array of <a href="#the-returnitem-resource">ReturnItem</a> objects</td><td>List of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.</td></tr><tr><td>return_line_items</td><td>An array of <a href="#the-returnlineitem-resource">ReturnLineItem</a> objects</td><td>List of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.</td></tr><tr><td>return_reason</td><td>String</td><td><p>Possible values:</p><p><strong>customer_return</strong></p><p><strong>not_picked_up</strong></p><p><strong>invalid_address</strong></p><p><strong>rejected_by_customer</strong></p><p><strong>customs_documents_missing</strong></p><p><strong>other</strong></p><p><em>null or empty string</em></p></td></tr><tr><td>return_reason_type</td><td>String</td><td><p>Possible values:<br><strong>active</strong> - customer return (the end-customer actively shipped the return)</p><p><strong>passive</strong> - carrier return (the end-customer never touched the parcel - it was shipped back by the carrier for reasons such as invalid address, the customer didn’t pick up their parcel from the shop or requested that it be sent back before receiving it, damages, customs documents missing, etc.)</p><p><em>null or empty string</em> - this happens in the rare case that a return is created before it’s processed and it is <em>not</em> a Customer Portal return, all Customer Portal returns are "active"</p></td></tr><tr><td>started_processing_at</td><td>ISO8601 datetime</td><td>When processing at the fulfillment center started</td></tr><tr><td>status</td><td>String</td><td><p>Possible values:<br><strong>on_the_way</strong> - is on the way to a fulfillment center</p><p><strong>arrived</strong> - arrived to a fulfillment center</p><p><strong>processing</strong> - the return processing is in progress</p><p><strong>action_required</strong> - waiting for merchant guidance</p><p><strong>handling_completed</strong> - the return processing is in completed</p></td></tr><tr><td>tracking_code</td><td>String</td><td>Tracking number assigned by the carrier</td></tr><tr><td>tracking_url</td><td>String</td><td>Carrier website showing tracking information</td></tr></tbody></table>

## The ReturnItem resource

| Property                  | Type                                            | Description                             |
| ------------------------- | ----------------------------------------------- | --------------------------------------- |
| customer\_return\_message | String                                          | Reason details provided by the customer |
| customer\_return\_reason  | String                                          | Reason provided by the customer         |
| id                        | Integer                                         | Hive's unique identifier                |
| quantity                  | Integer                                         | Quantity of items announced             |
| sku                       | A [ReturnSku](#the-returnedsku-resource) object | SKU details of the item                 |

## The ReturnLineItem resource

<table><thead><tr><th width="213">Property</th><th width="227">Type</th><th>Description</th></tr></thead><tbody><tr><td>condition</td><td>String</td><td>Possible values:<br><strong>A</strong> - Unused and in original packaging.<br><strong>B</strong> - Unused with missing/damaged packaging.<br><strong>C</strong> - Product is used or damaged.</td></tr><tr><td>follow_up_action</td><td>String</td><td>Action to be performed on the returned item. Possible values: <strong>restock</strong>, <strong>dispose</strong> and <strong>send_back</strong><br>Those actions are pre-selected based on return rules (Hive account manager inserts return rules into the system after negotiation with a merchant).</td></tr><tr><td>id</td><td>Integer</td><td>Hive's unique identifier</td></tr><tr><td>inventory_batch_id</td><td>Integer</td><td>Unique identifier in Hive system of the inventory batch (if present) into which returned item is going to be restocked (relevant only when <code>"follow_up_action": "restock"</code>)</td></tr><tr><td>photos</td><td>Array of <a href="#the-returnlineitemphoto-resource">ReturnLineItemPhoto</a> objects</td><td>Photos of the returned item</td></tr><tr><td>return_item_id</td><td>Integer</td><td>Announced return item's unique identifier in Hive system (can be blank, e.g. when the return is not a Customer Portal return)</td></tr><tr><td>sku</td><td>A <a href="#the-returnedsku-resource">ReturnSku</a> object</td><td>SKU details of the item</td></tr><tr><td>quantity</td><td>Integer</td><td>The quantity of items returned for the same SKU</td></tr></tbody></table>

## The ReturnSku resource

| Property          | Type    | Description                      |
| ----------------- | ------- | -------------------------------- |
| id                | Integer | Hive's unique SKU identifier     |
| merchant\_sku\_id | String  | Merchant's unique SKU identifier |

## The ReturnOrder resource

<table><thead><tr><th>Property</th><th width="145">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>Integer</td><td>Hive's unique order identifier</td></tr><tr><td>merchant_order_id</td><td>String</td><td>Merchant's unique order identifier</td></tr><tr><td>name</td><td>String</td><td>Customer's order identifier</td></tr></tbody></table>

## The ReturnPhoto resource

<table><thead><tr><th width="222">Property</th><th width="156">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>Integer</td><td>Hive's unique identifier</td></tr><tr><td>image_url</td><td>String</td><td>Publicly accessible URL (for 15 minutes)</td></tr><tr><td>photo_type</td><td>String</td><td>Type of photo. Usual values: <strong>inside</strong> or <strong>outside</strong></td></tr></tbody></table>

## The ReturnLineItemPhoto resource

<table><thead><tr><th width="222">Property</th><th width="156">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>Integer</td><td>Hive's unique identifier</td></tr><tr><td>image_url</td><td>String</td><td>Publicly accessible URL (for 15 minutes)</td></tr></tbody></table>

## List all returns

## Lists all order returns

<mark style="color:blue;">`GET`</mark> `https://app.hive.app/merchant_api/v1/returns`

Returns paginated order returns ordered by descending creation time.

#### Query Parameters

| Name              | Type             | Description                                                                         |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------- |
| created\_at\[lt]  | ISO8601 datetime | Return results where the `created_at` field is less than this value.                |
| created\_at\[lte] | ISO8601 datetime | Return results where the `created_at` field is less than or equal to this value.    |
| created\_at\[gt]  | ISO8601 datetime | Return results where the `created_at` field is greater than this value.             |
| created\_at\[gte] | ISO8601 datetime | Return results where the `created_at` field is greater than or equal to this value. |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "data": [
        {
            "id": 70047,
            "return_reason_type": "active",
            "return_reason": "customer_return",
            "status": "handling_completed",
            "created_at": "2023-05-18T09:38:18.999+02:00",
            "received_at": "2023-05-19T10:38:18.999+02:00",
            "started_processing_at": "2023-05-20T11:38:18.999+02:00",
            "completed_handling_at": "2023-05-21T12:38:18.999+02:00",
            "tracking_code": "TC123456789",
            "tracking_url": "https://example.org/package?trackingNumber=TC123456789",
            "carrier": "ExampleCarrier",
            "order": {
                "id": 1230221,
                "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106",
                "name": "#DE12345"
            },
            "photos": [
                {
                    "id": 115234,
                    "photo_type": "outside",
                    "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703678.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591"
                },
                {
                    "id": 115235,
                    "photo_type": "inside",
                    "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703679.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591"
                }
            ],
            "return_items": [
                {
                    "id": 27890,
                    "quantity": 1,
                    "customer_return_reason": "incorrect_product_arrived",
                    "customer_return_message": "I ordered red pencil but got green one",
                    "sku": {
                        "id": 123085,
                        "merchant_sku_id": "ABC123"
                    }
                }
            ],
            "return_line_items": [
                {
                    "id": 10456,
                    "inventory_batch_id": 123,
                    "return_item_id": 27890,
                    "condition": "A",
                    "follow_up_action": "restock",
                    "photos": [
                        {
                            "id": 117781,
                            "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703467.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591"
                        }
                    ],
                    "sku": {
                        "id": 123085,
                        "merchant_sku_id": "ABC123"
                    },
                    "quantity": 1
                }
            ]
        }
    ],
    "pagination": {
        "current_page": 1,
        "item_count": 1,
        "items_per_page": 20,
        "page_count": 1
    }
}
```

{% endtab %}
{% endtabs %}

## Get one return

## Get one specific order return

<mark style="color:blue;">`GET`</mark> `https://app.hive.app/merchant_api/v1/returns/{id}`

Returns specific order return belonging to the merchant and with matching Hive ID

#### Path Parameters

| Name                                 | Type    | Description                 |
| ------------------------------------ | ------- | --------------------------- |
| id<mark style="color:red;">\*</mark> | Integer | The (Hive) ID of the return |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": 70047,
    "return_reason_type": "active",
    "return_reason": "customer_return",
    "status": "handling_completed",
    "created_at": "2023-05-18T09:38:18.999+02:00",
    "received_at": "2023-05-19T10:38:18.999+02:00",
    "started_processing_at": "2023-05-20T11:38:18.999+02:00",
    "completed_handling_at": "2023-05-21T12:38:18.999+02:00",
    "tracking_code": "TC123456789",
    "tracking_url": "https://example.org/package?trackingNumber=TC123456789",
    "carrier": "ExampleCarrier",
    "order": {
        "id": 1230221,
        "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106"
    },
    "photos": [
        {
            "id": 115234,
            "photo_type": "outside",
            "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703678.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591"
        },
        {
            "id": 115235,
            "photo_type": "inside",
            "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703679.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591"
        }
    ],
    "return_items": [
        {
            "id": 27890,
            "quantity": 1,
            "customer_return_reason": "incorrect_product_arrived",
            "customer_return_message": "I ordered red pencil but got green one",
            "sku": {
                "id": 123085,
                "merchant_sku_id": "ABC123"
            }
        }
    ],
    "return_line_items": [
        {
            "id": 10456,
            "inventory_batch_id": 123,
            "return_item_id": 27890,
            "condition": "A",
            "follow_up_action": "restock",
            "photos": [
                {
                    "id": 117781,
                    "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703467.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591"
                }
            ],
            "sku": {
                "id": 123085,
                "merchant_sku_id": "ABC123"
            },
            "quantity": 1
        }
    ]
}
```

{% endtab %}
{% endtabs %}