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
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
GEThttps://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.
