GuidesAPI ReferenceChangelog
API Reference

Announce a return.

post
https://api.getbyrd.com/v3/returns/announce

Creates a customer return in the announced state for items of one
of your shipments. The return label is generated asynchronously and
emailed to send_documents_to_email a few seconds later, unless
send_email is false, so documents is usually empty in the
response. See
Announcing returns.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
uuid
required

ID of the shipment being returned (UUID). The shipment must be yours and must have been sent.

uuid

ID of the byrd account the shipment belongs to (UUID). Ignored for customer accounts: the return is always created for your own account.

string

Email address the return label is sent to once it is generated. Required unless send_email is false, and must be left out then.

boolean
Defaults to true

Whether the return label is emailed once it is generated. Set it to false to only generate the label and download it from documents instead. Defaults to true.

string
length ≤ 2

Language of the email carrying the return label and of the label itself, as an ISO 639-1 two-letter code, for example de. en, de and fr are supported and any other value falls back to English. When null, the language is taken from the destination country of the shipment, falling back to English.

string
enum

Returns Portal tier the return is announced through, basic or pro. Ignored for customer accounts.

Allowed:
string
enum

Kind of return label generated for the return. Defaults to byrd_label.

  • byrd_label: carrier shipping label for courier.
  • identifier_only: label that only identifies the return to the warehouse; it is not a shipping label and has no tracking number.
Allowed:
string
enum
Defaults to portal

Where the return was announced. Ignored for customer accounts.

  • portal: the Returns Portal.
  • dashboard: the byrd dashboard.
  • api: the API.
Allowed:
items_announced
array of objects

Items of the shipment that are being returned, with their amounts; at least one. Each shipment item can be announced in only one return.

items_announced
string
enum
required
length ≤ 64

Carrier the return is shipped with. Must be a carrier enabled for your account, the warehouse and the destination country; ask your byrd contact person which value applies to you.

Responses

Updated 1 day ago

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 1 day ago