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_id | string | Get all the returns for a specific shipment_id |
| date_field | string | Select the field to be used to filter by date_from and date_to.It accepts updatedAt, postedAt, deliveredAt, processedAt, announcedAt, createdAt |
| date_from | datetime | Datetime from in UTC. Filter by the field indicated under date_fieldExample: 2023-03-23T16:00:03Z |
| date_to | datetime | Datetime to in UTC. Filter by the field indicated under date_fieldExample: 2023-03-23T16:00:03Z |
| status | string | Filter returns by their status. It 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:
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.customer: Set on every return created through the Announcing returns endpoint, where the customer selects a per-item reason instead of one of the values above.
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 three values:
a-new: The item is like new and normally put back into stock.used: The item shows 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
}Updated about 20 hours ago