Announcing returns

Announce a customer return and receive a return label by email

Overview

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

🚧
This endpoint moved to /v3
The previous path POST /v2/returns/announce was removed and no longer
works. It answers 405 Method Not Allowed, not 404, so a client calling it
may look like it is using the wrong HTTP verb. Use the /v3 path below.
Migrating from /v2 requires three changes to your request:

the path is now /v3/returns/announce

request fields are snake_case (shipment_id, not shipmentID)

courier is a new required field

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
courier	string	The carrier the return is shipped with. Must be one of the carrier identifiers below, and must be a carrier enabled for your account, warehouse and destination country. Ask your byrd contact person which value applies to you.	always
items_announced	items announced object	Items to be returned.	always
documents_email_language	string	Language of the email carrying the return label. ISO 639-1 two letter code, for example `de`.	optional
label_type	string	Kind of return label generated for the return. It accepts: - `byrd_label`: carrier shipping label for `courier` - `identifier_only`: a return slip whose cut-off strip identifies the return to the warehouse; it is not a shipping label and has no tracking number. `courier` is still required. It defaults to `byrd_label` if not sent.	optional

The API reference also lists user_id, origin and portal_tier. They are ignored for customer accounts: the return is always created for your own account.

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	Number of units of this item to return. Minimum `1`.	always
reason	string	The reason for returning this item.	always

Carrier identifiers

Accepted values for courier:

amazon_prime          exporto_global        post_at
asendia_global        fedex_global          post_de
brt_it                gls_global            post_it
colissimo_fr          mondialrelay_fr       post_nl
correos_es            parcelforce_gb        royalmail_gb
dbschenker_global     schneckenpost_de      sendcloud_global
delivengo_fr          seur_es               sevensenders_global
derkurier_de          dpd_at
dhl_de                dpd_de
dhlexpress_de         dpd_gb

Request body example

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

Successful response example

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "shipment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "send_documents_to_email": "[email protected]",
    "documents_email_language": "de",
    "courier": "colissimo_fr",
    "status": "announced",
    "return_type": "customer",
    "reason": "customer",
    "portal_tier": null,
    "created_at": "2023-12-11T10:02:52.402Z",
    "updated_at": "2023-12-11T10:02:52.402Z",
    "items_announced": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "shipment_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "amount": 1,
        "reason": "arrived-too-late",
        "created_at": "2023-12-11T10:02:52.402Z",
        "updated_at": "2023-12-11T10:02:52.402Z"
      }
    ],
    "documents": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "printable_label",
        "data_type": "pdf",
        "created_at": "2023-12-11T10:02:52.402Z",
        "updated_at": "2023-12-11T10:02:52.402Z"
      }
    ]
  }
}

The return label is generated asynchronously, so documents is usually empty in
the immediate response. The label is sent to send_documents_to_email a few
seconds later.

Updated 1 day ago