Get a return label of an order

Request

Returns one return label of the order with its status:

pending: the label is still being created at the carrier. Poll again in a few seconds.
ready: the label has its tracking_code and carrier, and label_pdf_base64 holds its PDF, downloaded from the carrier on every read. When that download fails, the label is still returned with label_pdf_base64 set to null; read it again later. A failed download never creates a new label.
failed: the label could not be created; error says why. Request a new one with POST /orders/{id}/return_labels.

Security

BearerAuth

Path

idinteger, (int64)required

Order ID

label_idinteger, (int64)required

Return label ID, as returned by POST /orders/{id}/return_labels or the list

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

Responses

The return label

Bodyapplication/json

carrierstring or nullrequired

Name of the carrier that issues the label, known from the moment the label is requested. A return created from this label reports the same value as its carrier

created_atstring, (date-time)required

When the label was requested

errorReturnLabelError (object) or nullrequired

One of:

Why a return label could not be created

idinteger, (int64)required

Hive's unique identifier of the return label. It stays the same from the moment the label is requested

return_idinteger or null, (int64)required

ID of the return the label belongs to, readable with GET /returns/{id}. null while the label is not ready, and for a label printed into the parcel at packing until a return is recorded for it

shipment_idinteger or null, (int64)required

ID of the shipment the label returns. null only for some labels created before 2024

statusstringrequired

pending while the label is being created at the carrier, ready once it has a tracking number and a document, failed when it could not be created (see error). Labels from other sources than this API are always ready

Enum:"pending""ready""failed"

tracking_codestring or nullrequired

Tracking number of the return parcel, assigned by the carrier. null until the label is ready

label_pdf_base64string or null, base64required

The label as a base64-encoded PDF, ready to print. null while the label is not ready, and when the carrier did not return the document; the label and its tracking number are still valid, and a later read returns the document

Response

{
  "carrier": "DHL DE",
  "created_at": "2026-10-06T09:12:44.512Z",
  "error": null,
  "id": 987654,
  "label_pdf_base64": null,
  "return_id": null,
  "shipment_id": 4567890,
  "status": "pending",
  "tracking_code": null
}