Returns

The Return resource

Property	Type	Description
carrier	String	Carrier name
completed_handling_at	ISO8601 datetime	When the return handling finished
created_at	ISO8601 datetime	When the return was created
id	Integer	Hive's unique identifier
order	A ReturnOrder object	Details of the associated order
photos	An array of ReturnPhoto objects	Photos of the returned items
received_at	ISO8601 datetime	When the return was received
return_items	An array of ReturnItem objects	List of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.
return_line_items	An array of ReturnLineItem objects	List of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.
return_reason	String	Possible values: customer_return not_picked_up invalid_address rejected_by_customer customs_documents_missing other null or empty string
return_reason_type	String	Possible values: active - customer return (the end-customer actively shipped the return) passive - 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.) null or empty string - this happens in the rare case that a return is created before it’s processed and it is not a Customer Portal return, all Customer Portal returns are "active"
started_processing_at	ISO8601 datetime	When processing at the fulfillment center started
status	String	Possible values: on_the_way - is on the way to a fulfillment center arrived - arrived to a fulfillment center processing - the return processing is in progress action_required - waiting for merchant guidance handling_completed - the return processing is in completed
tracking_code	String	Tracking number assigned by the carrier
tracking_url	String	Carrier website showing tracking information

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 object	SKU details of the item

The ReturnLineItem resource

Property	Type	Description
condition	String	Possible values: A - Unused and in original packaging. B - Unused with missing/damaged packaging. C - Product is used or damaged.
follow_up_action	String	Action to be performed on the returned item. Possible values: restock, dispose and send_back Those actions are pre-selected based on return rules (Hive account manager inserts return rules into the system after negotiation with a merchant).
id	Integer	Hive's unique identifier
inventory_batch_id	Integer	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")
photos	Array of ReturnLineItemPhoto objects	Photos of the returned item
return_item_id	Integer	Announced return item's unique identifier in Hive system (can be blank, e.g. when the return is not a Customer Portal return)
sku	A ReturnSku object	SKU details of the item

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

Property	Type	Description
id	Integer	Hive's unique order identifier
merchant_order_id	String	Merchant's unique order identifier
name	String	Customer's order identifier

The ReturnPhoto resource

Property	Type	Description
id	Integer	Hive's unique identifier
image_url	String	Publicly accessible URL (for 15 minutes)
photo_type	String	Type of photo. Usual values: inside or outside

The ReturnLineItemPhoto resource

Property	Type	Description
id	Integer	Hive's unique identifier
image_url	String	Publicly accessible URL (for 15 minutes)

List all returns

Lists all order returns

GET 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.

200: OK

{
    "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"
                    }
                }
            ]
        }
    ],
    "pagination": {
        "current_page": 1,
        "item_count": 1,
        "items_per_page": 20,
        "page_count": 1
    }
}

Get one return

Get one specific order return

GET 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*	Integer	The (Hive) ID of the return

200: OK

{
    "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"
            }
        }
    ]
}