Skip to content

Get a return

Request

Returns a specific return.

Security
BearerAuth
Path
idinteger, (int64)required

Return ID

curl -i -X GET \
  'https://developers.hive.app/_mock/merchant-api-v2/mapi_v2_oas31/returns/{id}' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

A return

Bodyapplication/json
announced_itemsArray of objects(ReturnAnnouncedItem)required

List of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.

carrierstring or null

Carrier name

completed_handling_atstring or null, (date-time)

When the return handling finished

created_atstring, (date-time)required

When the return was created

handled_itemsArray of objects(ReturnHandledItem)

List of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.

idinteger, (int64)required

Hive's unique identifier

orderobject(ReturnOrder)required

Details of the associated order

Example:
{
  "id": 123456,
  "merchant_order_id": "ORD-1001",
  "customer_order_number": "CUST-ORD-2023-01"
}
photosArray of objects(ReturnPhoto)

Photos of the returned items

return_reasonReturnReason (string) or null
Any of:

Reason for the return. Possible values:

  • customer_return: Customer initiated return
  • customs_documents_missing: Missing customs documentation
  • invalid_address: Invalid shipping address
  • not_picked_up: Package was not picked up by customer
  • other: Other reason not specified
  • rejected_by_customer: Customer rejected the delivery
string(ReturnReason)
Enum:"customer_return""customs_documents_missing""invalid_address""not_picked_up""other""rejected_by_customer"
return_reason_typeReturnReasonType (string) or null
Any of:

Type of return categorization. Possible values:

  • active: Customer return (end-customer actively shipped the return)
  • passive: Carrier return (end-customer never received the parcel - shipped back by carrier for reasons like invalid address, not picked up, damages, missing customs documents, etc.)
string(ReturnReasonType)
Enum:"active""passive"
started_processing_atstring or null, (date-time)

When processing at the fulfillment center started

statusstring(ReturnStatus)read-onlyrequired

Status of the return. Possible values:

  • action_required: Waiting for merchant guidance
  • arrived: Arrived at fulfillment center
  • handling_completed: Return processing completed
  • on_the_way: On the way to fulfillment center
  • processing: Return processing in progress
Enum:"action_required""arrived""handling_completed""on_the_way""processing"
tracking_codestring or null

Tracking number assigned by the carrier

tracking_urlstring or null

Carrier website showing tracking information

updated_atstring, (date-time)required
received_atstring or null, (date-time)deprecated

Use started_processing_at and completed_handling_at instead.

Response
{
  "id": 5555,
  "announced_items": [
    { … }
  ],
  "carrier": "DHL",
  "completed_handling_at": "2023-10-10T15:00:00Z",
  "created_at": "2023-10-08T10:00:00Z",
  "handled_items": [
    { … }
  ],
  "order": {
    "id": 123456,
    "merchant_order_id": "ORD-1001",
    "customer_order_number": "CUST-ORD-2023-01"
  },
  "photos": [
    { … }
  ],
  "received_at": null,
  "return_reason": "customer_return",
  "return_reason_type": "active",
  "started_processing_at": "2023-10-09T13:00:00Z",
  "status": "arrived",
  "tracking_code": "TRACK-RET-123",
  "tracking_url": "https://dhl.com/track/RET-123",
  "updated_at": "2023-10-10T15:00:00Z"
}