Requests a new return label for a shipped order, the same way the Request return label button in the Hive app does: the label is for the shipment the Hive app uses (the heaviest delivered shipment, or the heaviest shipment when none is delivered yet), the carrier is chosen from your return settings, and once the label is ready a return is created with status on_the_way. The request takes no body; a body sent anyway is ignored.

Every call creates a new label, unless it repeats an Idempotency-Key (below). The response is 202 with the new label in status pending, and the Location header points at it; poll it with GET until its status is ready or failed. The label's id does not change. A repeated call without a key creates another label, so to read a label again, follow its Location or list the order's labels with GET /orders/{id}/return_labels.

Retrying safely. To retry a call whose response you did not get (a dropped connection, a timeout or a 5xx) without creating a second label, send an Idempotency-Key header and repeat the same key in the retry. A call with a key already used on this order creates nothing and answers with the label that key created, whatever the order looks like now and even when it has reached the label limit: 202 with Location while the label is pending, 200 once it is ready or failed. Keys are compared within one order, so the same key on another order requests a label for that order. A failed label stays the answer for its key; use a new key to request a new label.

Up to 5 labels per order, as in the Hive app. The count includes the order's labels that have a return, from any source (the Hive app, this API, the customer returns portal) and including labels whose return was cancelled, plus the labels this API is still creating. Labels whose creation failed do not count, and a label printed into the parcel at packing counts only once a return is recorded for it. Concurrent calls for the same order wait for each other, so together they never exceed the limit.

Creation usually takes a few seconds. A label that still has no tracking number 15 minutes after the call that requested it becomes failed with the code carrier_timeout.

When the label cannot be requested, the response is 422 with errors keyed by one of these codes:

• not_returnable: the order has not shipped yet, or is cancelled.
• customs_required: the order crossed a customs border, so a return label cannot be created for it.
• no_return_method: no return delivery method in your return settings covers the route and weight of the label's shipment.
• label_limit_reached: the order already has 5 return labels, counted as described above.
• missing_customs_data: the return needs customs data that some products lack (HS code, country of origin, declared value).
• other: any other reason, for example a carrier contract missing from your settings.