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

Details of the associated order

photos

Photos of the returned items

received_at

ISO8601 datetime

When the return was received

return_items

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

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

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

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

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.

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

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

Last updated