GuidesAPI ReferenceChangelog
API Reference

List returns

get
https://api.getbyrd.com/v2/returns

Returns the courier and customer returns of your shipments, newest
first unless you sort otherwise, filtered by the query parameters.
See the Listing returns guide for the meaning of returnType,
reason and the item condition.

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

Only include returns of the shipment with this ID (UUID).

status
array of strings

Only include returns in one of these statuses: announced, confirmed, cancelled. Cancelled returns are never shown to customer accounts.

status
Allowed:
string
enum
Defaults to createdAt

Date field date_from and date_to apply to. Defaults to createdAt.

  • createdAt: when the return was created
  • updatedAt: when the return was last changed
  • announcedAt: when the return was announced
  • postedAt: when the parcel was handed to the carrier
  • deliveredAt: when the return arrived at the warehouse
  • processedAt: when the warehouse checked the items
Allowed:
date-time

Only include returns whose date_field is at or after this time (ISO 8601, UTC), e.g. 2023-03-23T16:00:03Z.

date-time

Only include returns whose date_field is before this time (ISO 8601, UTC), e.g. 2023-03-23T16:00:03Z. Must be after date_from.

string

Only include returns of the shipment with this parcel ID, or of the shipment unit with this parcel ID.

reason
array of strings

Only include returns with one of these reasons. See reason in the response for the values.

reason
string

Only include returns shipped with this carrier, as a carrier identifier such as dhl_de.

string

Only include returns with this carrier tracking number.

user_ids
array of uuids

Only include returns of shipments owned by these users (UUIDs). As a customer you only get your own returns.

user_ids
string

Only include returns whose original shipment recipient name or company contains this text (case-insensitive).

string

Only include returns with a received item of this SKU.

string

Only include returns with a received item of the product with this ID (UUID).

string
enum

Only include returns of this type: courier or customer.

Allowed:
boolean

Only include returns for which the warehouse had (true) or had not (false) to search manually for the original shipment.

integer
≥ 1
Defaults to 250

Number of results per page

integer
≥ 0
Defaults to 0

Result page to jump to, 0-indexed

string

The model field to sort results by

string
enum

The direction of result sorting

Allowed:
string

The search term

fields
array of strings

Model fields to search through; comma separated

fields
Headers
string
enum
Defaults to application/vnd.byrd.customer+json

Generated from available response content types

Allowed:
Responses

Updated 11 days ago

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

Updated 11 days ago