Overview

Announce a return by calling this endpoint. After some seconds you will receive a label in the provided email.

Method access
POST https://api.getbyrd.com/v3/returns/announce
Request Headers
Authorization: Bearer token-from> Authentication
Content-Type: application/json
User-Agent: your user-agent> How to call the APIs

Fields

Field	Type	Description	Required
shipment_id	string	The shipment id to return.	always
send_documents_to_email	email	Email that will receive the return label.	always
items_announced	items announced object	Items to be returned	always

Items announced object

Field	Type	Description	Required
shipment_item_id	string	The shipment item id to return. The shipment item id can be obtained under "items" object from the response to the original shipment creation call or by getting the original shipment details.	always
amount	integer	Email to send the return label.	always
reason	string	Reason of the return for the item.	always

Request body example

{
  "send_documents_to_email": "[email protected]",
  "shipment_id": "the_shipment_id_to_return",
  "items_announced": [
    {
      "amount": 1,
      "reason": "arrived-too-late",
      "shipment_item_id": "the_shipment_item_id_to_return"
    }
  ],
}

Successful response example

{
    "data": {
        "id": "4c0d9698-ab56-4619-a250-1d0de9ccc558",
        "created_at": "2026-02-10T11:43:22.773469+00:00",
        "updated_at": "2026-02-10T11:43:22.773492+00:00",
        "shipment_id": "da98e764-9be7-4af3-b51d-fe3fdd7b9017",
        "send_documents_to_email": "[email protected]",
        "documents_email_language": null,
        "portal_tier": null,
        "courier": null,
        "status": "announced",
        "return_type": "customer",
        "reason": "customer",
        "items_announced": [
            {
                "id": "64c0e48e-a470-4106-8ec1-b803081a7824",
                "created_at": "2026-02-10T11:43:22.777474+00:00",
                "updated_at": "2026-02-10T11:43:22.777487+00:00",
                "shipment_item_id": "fe773346-ca34-41c9-822f-4a08dbae3604",
                "amount": 1,
                "reason": "item-too-sunny"
            }
        ],
        "documents": []
    }
}