Listing returns

API reference ReturnShipmentListAPI

Overview

This endpoint can be used to get a list of the returns that are created in byrd. The response will include the details for every return

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

Query params

You can filter the list by different fields combining them depending on your needs. The most frequent are:

Field

Type

Description

shipment_idstring

Get all the returns for a specific shipment_id

date_field string

Select the field to be used to filter bydate_from and date_to.
If accepts updatedAt, postedAt, deliveredAt, processedAt, announcedAt, createdAt

date_fromdatetime

Datetime from in UTC.
Filter by the field indicated under date_field
Example: 2023-03-23T16:00:03Z

date_todatetime

Datetime to in UTC.
Filter by the field indicated under date_field
Example: 2023-03-23T16:00:03Z

statusstring

Get only returns created by these user_ids
If accepts announced, confirmed (by the warehouse)

Pagination

By sending these parameters you can get the result in different pages:

Field

Type

Description

per_page string

Items per page
Default is 250

page string

It returns only that page

sort_by string

It sorts the response by this field

sort_order string

It sorts the response ascending or descending depending on this value
It accepts asc and desc

Response details

The returnType field

The returnType field specifies the type of a return. It allows distinguishing between returns initiated by the courier or carrier and returns initiated by the customer.

Possible Values:

  • courier: Indicates that the return was initiated by the courier. This typically occurs when the courier encounters issues delivering the package, such as an incorrect address, failed delivery attempts, or logistical challenges.
  • customer: Indicates that the return was initiated by the customer. This usually happens when the customer wants to return a product due to reasons such as dissatisfaction, product defects, change of mind, or other customer-specific circumstances.

The reason field

The reason field denotes the reason for the return of a shipment. It provides information about the specific cause or circumstance that led to the return. The reason field offers a set of predefined values that categorize common reasons for returned shipments.

Possible values:
The reason field can have the following values:

  • bad-address: Indicates that the shipment was returned due to an incorrect or incomplete address provided for delivery. This could include factors like missing apartment numbers, wrong postal codes, or insufficient address details.
  • bad-product: Signifies that the return occurred because the product received by the customer was defective, damaged, or not in compliance with the expected quality standards.
  • country: Indicates that the return was due to shipping restrictions or limitations imposed by the destination country or customs regulations.
  • no-pickup: Denotes that the customer was unavailable or failed to pickup the shipment from the location the courier held the shipment after a failed delivery.
  • rec-unknown: Specifies that the return was prompted by the unavailability or unknown recipient at the delivery address. This could include scenarios where the recipient moved or cannot be located.
  • refused-delivery: Indicates that the customer explicitly refused to accept the delivery, resulting in the return of the shipment.
  • unwanted: Signifies that the return was initiated by the customer due to reasons such as a change of mind, ordering the wrong product, or no longer desiring the item.

The condition field of items

The items field contains a list of the processed returned items in the warehouse. In comparison to the itemsAnnounced field, those items are confirmed by the warehouse and their condition rated. This field can have one of the following 3 values:

  • a-new: The item is like new and normally put back into stock
  • used: The item show usage signs and can't be resold without further steps.
  • damaged: The item can't be resold anymore.

The specific process can vary from one customer to the next and needs to be defined during onboarding.

Successful response example

{
  "data": [
    {
      "returnType": "courier",
      "reason": "string",
      "announcedAt": "2022-06-27T17:13:37.581Z",
      "courierTrackingURL": "string",
      "sendDocumentsToEmail": "[email protected]",
      "processedAt": "2022-06-27T17:13:37.581Z",
      "warehouseID": "string",
      "updatedAt": "2022-06-27T17:13:37.581Z",
      "id": "string",
      "itemsAnnounced": [
        {
          "createdAt": "2022-06-27T17:13:37.581Z",
          "reason": "string",
          "amount": 0,
          "updatedAt": "2022-06-27T17:13:37.581Z",
          "id": "string",
          "shipmentItemID": "string"
        }
      ],
      "status": "announced",
      "postedAt": "2022-06-27T17:13:37.581Z",
      "items": [
        {
          "createdAt": "2022-06-27T17:13:37.581Z",
          "photos": [
            {
              "id": "string",
              "createdAt": "2022-06-27T17:13:37.581Z",
              "updatedAt": "2022-06-27T17:13:37.581Z",
              "url": "string"
            }
          ],
          "condition": "a-new",
          "byrdProductID": "string",
          "amount": 0,
          "updatedAt": "2022-06-27T17:13:37.581Z",
          "id": "string",
          "internalComments": "string",
          "returnID": "string",
          "shipmentItemID": "string"
        }
      ],
      "deliveredAt": "2022-06-27T17:13:37.581Z",
      "courier": "string",
      "documents": [
        {
          "dataType": "string",
          "createdAt": "2022-06-27T17:13:37.581Z",
          "updatedAt": "2022-06-27T17:13:37.581Z",
          "type": "string",
          "id": "string"
        }
      ],
      "shipmentID": "string",
      "createdAt": "2022-06-27T17:13:37.581Z",
      "shipment": {
        "destinationEmail": "string",
        "outboundError": {},
        "carrierShipmentID": "string",
        "totalPickedUnits": 0,
        "plannedSentDay": "2022-06-27",
        "weight": 0,
        "sentDate": "2022-06-27T17:13:37.581Z",
        "releasedAt": "2022-06-27T17:13:37.581Z",
        "userLength": 0,
        "destinationName": "string",
        "toBeBranded": true,
        "acceptedDate": "2022-06-27T17:13:37.581Z",
        "packagingMaterials": "string",
        "amazon_prime_generated_label": "string",
        "releaseError": {},
        "fragile": true,
        "shipmentItems": [
          {
            "description": "string",
            "length": 0,
            "dangerousGoods": {
              "unClass": "9A",
              "unNumber": "UN-3480",
              "wattHours": 0
            },
            "weight": 0,
            "price": {
              "taxFactor": 0,
              "value": 0,
              "currency": "string"
            },
            "height": 0,
            "byrdProductID": "string",
            "lotNumber": "string",
            "width": 0,
            "updatedAt": "2022-06-27T17:13:37.581Z",
            "id": "string",
            "byrdProduct": "string",
            "sku": "string",
            "productID": "string",
            "amount": 0,
            "customs": {
              "customsTariffNumber": "string",
              "originCountryCode": "string"
            },
            "createdAt": "2022-06-27T17:13:37.581Z",
            "variantID": "string",
            "pictureID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "productName": "string"
          }
        ],
        "userWeight": 0,
        "packagingStartDate": "2022-06-27T17:13:37.581Z",
        "subStatus": "string",
        "carrierService": "string",
        "height": 0,
        "deliveryDate": "2022-06-27T17:13:37.581Z",
        "latestShipDate": "2022-06-27T17:13:37.581Z",
        "type": "string",
        "customs": {
          "invoiceNumber": "string",
          "goodsType": "document"
        },
        "orderNumber": "string",
        "addressValidationError": "string",
        "description": "string",
        "shopType": "string",
        "shopID": "string",
        "carrierTrackingURL": "string",
        "carrierTrackingNumber": "string",
        "b2bConfig": {
          "createdAt": "2022-06-27T17:13:37.581Z",
          "customerInput": "string",
          "templateKey": "string",
          "isPallet": true,
          "templateID": "string",
          "updatedAt": "2022-06-27T17:13:37.581Z",
          "id": "string"
        },
        "user": {
          "senderName": "string",
          "companyName": "string",
          "directComplete": true,
          "billingAddress": {
            "latitude": 0,
            "createdAt": "2022-06-27T17:13:37.581Z",
            "postalCode": "string",
            "locality": "string",
            "countryCode": "string",
            "subAdminArea": "string",
            "adminArea": "string",
            "thoroughfare": "string",
            "subThoroughfare": "string",
            "updatedAt": "2022-06-27T17:13:37.581Z",
            "subSubThoroughfare": "string",
            "id": "string",
            "subLocality": "string",
            "longitude": 0,
            "validated": true
          },
          "firstName": "string",
          "skipBarcodePick": "string",
          "id": "string",
          "warehouseInstructions": "string",
          "lastName": "string"
        },
        "packagedDate": "2022-06-27T17:13:37.581Z",
        "cod": {
          "codCurrency": "EUR",
          "codValue": 0
        },
        "option": "book",
        "width": 0,
        "packagingMaterialID": "string",
        "byrdOtherFees": {
          "taxFactor": 0,
          "value": 0,
          "currency": "string"
        },
        "destinationCompany": "string",
        "returnDate": "2022-06-27T17:13:37.581Z",
        "documents": [
          {
            "name": "string",
            "dataType": "pdf",
            "createdAt": "2022-06-27T17:13:37.581Z",
            "outputType": "document",
            "copies": 0,
            "toBePrinted": true,
            "meta": {},
            "updatedAt": "2022-06-27T17:13:37.581Z",
            "type": "string",
            "id": "string"
          }
        ],
        "byrdShippingRate": {
          "taxFactor": 0,
          "value": 0,
          "currency": "string"
        },
        "preferredCarrier": "string",
        "length": 0,
        "insurance": {
          "insuranceValue": 0,
          "insuranceCurrency": "EUR"
        },
        "copied": true,
        "carrier": "string",
        "warehouseID": "string",
        "shippingRate": {
          "taxFactor": 0,
          "value": 0,
          "currency": "string"
        },
        "userWidth": 0,
        "destinationPhone": "string",
        "parcelID": "string",
        "updatedAt": "2022-06-27T17:13:37.581Z",
        "id": "string",
        "dont_charge": true,
        "status": "string",
        "labelError": "string",
        "recallReason": "string",
        "toBePackaged": true,
        "byrdCODFee": {
          "taxFactor": 0,
          "value": 0,
          "currency": "string"
        },
        "customHandling": true,
        "otherFees": {
          "taxFactor": 0,
          "value": 0,
          "currency": "string"
        },
        "createdAt": "2022-06-27T17:13:37.581Z",
        "orderID": "string",
        "destinationAddress": {
          "latitude": 0,
          "createdAt": "2022-06-27T17:13:37.581Z",
          "postalCode": "string",
          "locality": "string",
          "countryCode": "string",
          "subAdminArea": "string",
          "adminArea": "string",
          "thoroughfare": "string",
          "subThoroughfare": "string",
          "updatedAt": "2022-06-27T17:13:37.581Z",
          "subSubThoroughfare": "string",
          "id": "string",
          "subLocality": "string",
          "longitude": 0,
          "validated": true
        },
        "labelErrorNote": "string",
        "userHeight": 0
      },
      "publicComments": "string",
      "courierTrackingNumber": "string"
    }
  ],
  "page": 0,
  "per_page": 0,
  "page_count": 0,
  "total_count": 0
}