Returns

The Return resource

Properties

id - the return's unique identifier in Hive system

return_reason_type - type of the return. Possible values:

Return reason type options

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/empty string - this happens in the rare case that a return is created before it’s processed and it is not a PPA return, all PPA returns are automatically set to "active" (PPA=Hive Post Purchase App)

return_reason - the more specific reason why the order was returned. Possible values:

Return reason options

customer_return

not_picked_up

invalid_address

rejected_by_customer

customs_documents_missing

other/null/empty string - some other specific case

status - current status of the return. Possible values:

Status options

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

created_at - The date and time when the return record appeared in Hive system

received_at - The date and time when the return was received in a Hive fulfillment center

started_processing_at - The date and time when the return processing in a fulfillment center was started

completed_handling_at - The date and time when the return processing in a fulfillment center was completed

tracking_code - returned parcel tracking code provided by carrier

tracking_url - tracking url constructed by Hive based on tracking code and carrier (can be blank, e.g. when carrier is blank)

carrier - carrier name (can be blank, e.g. when it is created in the FC)

order.id - returned order's unique identifier in Hive system

order.merchant_order_id - returned order's unique identifier provided by merchant

order.name - the name of the order as it's shown to the customer (e.g. #DE20351)

photos - photos of the returned parcel

photos[i].id - photo's unique identifier in Hive system

photos[i].photo_type - can be any string, usual values are inside (photo of how return looks inside the box) and outside(photo of how return looks outside the box).

photos[i].image_url - a url of the photo image (expires in 15min)

return_items - list of return items announced through the PPA (i.e. the end-customer selects these in the PPA to communicate that they will be returning these items), this list can be empty if the return is not a PPA return (PPA=Hive Post Purchase App)

return_items[i].id - announced return item's unique identifier in Hive system

return_items[i].quantity - announced return item's announced quantity

return_items[i].customer_return_reason - return reason provided by the customer via PPA (can be empty)

return_items[i].customer_return_message - return reason details provided by the customer via PPA (can be empty)

return_items[i].sku.id - the announced returnable sku's unique identifier in Hive system

return_items[i].sku.merchant_sku_id - the announced returnable sku's unique identifier provided by merchant

return_line_items - list of items that are actually handled in the FC, this list can be empty if return items have not been handled in the FC yet

return_line_items[i].id - returned item's unique identifier in Hive system

return_line_items[i].inventory_batch_id - 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")

return_line_items[i].return_item_id - announced return item's unique identifier in Hive system (can be blank, e.g. when the return is not a PPA return)

return_line_items[i].condition - possible values are A, B and C. A - Unused and in original packaging. B - Unused with missing/damaged packaging. C - Product is used or damaged.

return_line_items[i].follow_up_action - an action to be performed on the returned item, possible options are 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).

return_line_items[i].photos - photos of the returned item

return_line_items[i].photos[j].id - photo's unique identifier in Hive system

return_line_items[i].photos[j].image_url - a url of the photo image (expires in 15min)

return_line_items[i].sku.id - returned sku's unique identifier in Hive system

return_line_items[i].sku.merchant_sku_id - returned sku's unique identifier provided by merchant

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