Listing shipments
API reference ShipmentListAPIV3
Overview
This endpoint can be used to get a list of shipments filtering by different parameters
Method access
GET https://api.getbyrd.com/v3/shipments
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 |
|---|---|---|
| q | string | Search by term. It searches for that term in the fields specified under field |
| fields | string | Fields where to search for the value in q |
| include_unit_items | boolean | Show shipment unit items If accepts true and falseRelevant for e.g. serial number tracking. See: SN |
| awaiting_allocation | boolean | Filter shipments awaiting allocation If accepts true and false |
| awaiting_release | boolean | Filter shipments awaiting release If accepts true and false |
| carrier | list of strings | Include only shipments of these carriers. If accepts a list with the names of carriers from Listing carriers |
| destination_email | string | Filter shipments with this destination email. |
| failed_address_validation | boolean | Filter shipments with failed address validation or not. If accepts true and false |
| failed_allocation | boolean | Filter shipments the failed at allocation to a warehouse. If accepts true and false |
| failed_packaging | boolean | Filter shipments the failed at packaging. If accepts true and false |
| failed release | boolean | Filter shipments the failed at release to a warehouse. If accepts true and false |
| is_b2b | boolean | Filter b2b shipments. If accepts true and false |
| is_cod | boolean | Filter cash on delivery shipments. If accepts true and false |
| missing_documents | boolean | Filter shipments with missing documents. If accepts true and false |
| service | string | Shipment method It accepts economy, standard, express, amazon_prime, pickup, pickup_point |
| status | list of strings | Filter shipments by its status If accepts a list with these values: new, releasing, released, picking, packaging, packaged, sent, delivered, returning, returned, deleted |
| sub_status | list of strings | Filter shipments by its sub-status If accepts a list with these values: validating_address, address_invalid, recalled, reserved, allocating, allocated, assigned, error_resolved, label_required, label_uploaded, manual_outbound |
Date fields
Use these fields to restrict your queries to certain dates:
| Field | Type | Description |
|---|---|---|
| date_field | string | Select the field to be used to filter by date_from and date_to.If accepts created_at, updated_at, released_at, packaged_date, sent_date |
| 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-23T17:00:03Z |
| sent_date | date | Filter by sent date. Example: 2023-03-23 |
| sent_date_from | datetime | Sent datetime from in UTC. Example: 2023-03-23T16:00:03Z |
| sent_date_to | datetime | Sent datetime from in UTC. Example: 2023-03-23T16:00:03Z |
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 |
Successful response example
{
"page": 0,
"per_page": 250,
"last_page": false,
"data": [{
"created_at": "2023-01-27T14:21:02.841740+00:00",
"checkpoints": {
"sent_at": null,
"packaged_at": "2023-01-30T06:07:18.238436+00:00",
"delivered_at": "2023-02-01T11:06:00+00:00",
"returned_at": null,
"picked_at": "2023-01-30T06:05:51.321241+00:00",
"accepted_at": null,
"allocated_at": "2023-01-27T14:21:05.818046+00:00",
"assigned_at": "2023-01-27T14:22:45.887386+00:00",
"released_at": "2023-01-27T14:21:07.314112+00:00"
},
"customs": {
"goods_type": "other",
"invoice_number": "123456"
},
"id": "the_shipment_id",
"sub_status": null,
"cash_on_delivery": null,
"notes": {
"packaging_instructions": "some instructions",
"customer_note": null,
"label_error_note": null
},
"service": "standard",
"warehouse": {
"allocated_by": {
"id": "an_user_id",
"first_name": "Name",
"last_name": "Last Name"
},
"code": "ECD",
"assigned_by": {
"id": "an_user_id",
"first_name": "Name",
"last_name": "Last Name"
},
"id": "warehouse_id",
"name": "Name of the warehouse",
"picked_by": {
"id": "an_user_id",
"first_name": "Name",
"last_name": "Last Name"
}
},
"dangerous_goods": {
"limited_quantity_weight": 0.0
},
"b2b_config": null,
"warnings": [],
"insurance": null,
"byrd_id": "ABCD123456",
"options": {
"has_dangerous_goods": false,
"packaging": true,
"branding": false,
"skip_barcode": false,
"custom_handled": false,
"v3_packaging": false,
"partial_fulfillment": false,
"return_label": false,
"not_before_date": "2023-01-27T12:28:03.569257+00:00",
"direct_complete": false,
"not_later_date": null,
"preferred_carrier": null,
"pickup_date": "2023-01-30",
"charge": true,
"remunerate": true,
"incoterm": "DAP",
"international": false,
"auto_release": true,
"fragile": false,
"custom_handling": false
},
"priority": 10,
"user": {
"company_name": "Company",
"billing_address": {
"country_code": "DE",
"postal_code": "123456",
"state": null,
"id": "company_id",
"street_name": "Street name",
"city": "City",
"street_number": "1234",
"address_addition": ""
},
"id": "user_id",
"first_name": "Name",
"sender_name": null,
"last_name": "Last Name"
},
"status": "delivered",
"container_code": null,
"metrics": {
"total_items": 1,
"total_picks": 1,
"total_skus": 1,
"total_packaging_units": 0
},
"return_address": {
"country_code": "DE",
"postal_code": "12345",
"state": null,
"id": "address_id",
"street_name": "Street.",
"city": "City",
"name": "Warehouse name",
"street_number": "123",
"address_addition": ""
},
"destination_address": {
"created_at": "2023-01-27T14:21:02.840477+00:00",
"id": "address_id",
"state": "",
"validated": false,
"phone": null,
"name": "Recipient Name",
"country_code": "DE",
"email": "email",
"street_name": "Street",
"city": "City",
"updated_at": "2023-01-27T14:21:02.840484+00:00",
"street_number": "12",
"company_name": "",
"postal_code": "12345",
"address_addition": ""
},
"updated_at": "2023-02-01T11:16:01.031581+00:00",
"shop": {
"id": null,
"type": null,
"order_id": "your_order_id",
"order_number": "your_order_number"
},
"units": [
{
"type": "parcel",
"checkpoints": {
"accepted_at": null,
"delivered_at": "2023-02-01T11:06:00+00:00"
},
"parcel_id": "ABCD123456",
"sequence_number": 1,
"id": "unit_id",
"sub_status": null,
"dimensions": {
"height": 16.0,
"width": 23.0,
"weight": 0.8,
"length": 31.0
},
"service": "standard",
"status": "delivered",
"metrics": null,
"packaging_materials": [
{
"code": "ABC1234",
"quantity": 1
}
],
"items": [],
"carrier": {
"tracking_number": "001234567890",
"tracking_url": "https://www.thecarrier.co?piececode=001234567890",
"shipment_id": "01264567897546",
"fuel_surcharge_rate": {
"tax_factor": 1.19,
"value": 0.136875,
"actual_carrier": "Name of the carrier",
"currency": "EUR"
},
"shipping_rate": {
"tax_factor": 1.19,
"value": 1.11,
"currency": "EUR"
},
"byrd_shipping_rate": {
"tax_factor": 1.19,
"value": 2.22,
"currency": "EUR"
},
"name": "dhl_de"
},
"errors": []
}
],
"items": [
{
"created_at": "2023-01-27T14:21:02.845038+00:00",
"type": "product",
"customs": {
"hs_tariff_number": "21061020",
"origin_country_code": "DE"
},
"id": "item_id",
"dimensions": {
"height": null,
"width": null,
"weight": 0.5,
"length": null
},
"lot_number": null,
"dangerous_goods": [],
"product_id": "product_id",
"name": "Name of the product",
"serial_number_tracked": false,
"children": [],
"updated_at": "2023-01-27T14:21:02.845045+00:00",
"quantity": 1,
"description": "Description of the product",
"sku": "sku",
"fragile": false,
"price": {
"tax_factor": 1.0,
"value": 28.03,
"currency": "EUR"
}
}
],
"errors": []
}]
}
Successful response example with flag include_unit_items set to True
{
"page": 0,
"per_page": 250,
"last_page": false,
"data": [{
"created_at": "2023-01-27T14:21:02.841740+00:00",
"checkpoints": {
"sent_at": null,
"packaged_at": "2023-01-30T06:07:18.238436+00:00",
"delivered_at": "2023-02-01T11:06:00+00:00",
"returned_at": null,
"picked_at": "2023-01-30T06:05:51.321241+00:00",
"accepted_at": null,
"allocated_at": "2023-01-27T14:21:05.818046+00:00",
"assigned_at": "2023-01-27T14:22:45.887386+00:00",
"released_at": "2023-01-27T14:21:07.314112+00:00"
},
"customs": {
"goods_type": "other",
"invoice_number": "123456"
},
"id": "the_shipment_id",
"sub_status": null,
"cash_on_delivery": null,
"notes": {
"packaging_instructions": "some instructions",
"customer_note": null,
"label_error_note": null
},
"service": "standard",
"warehouse": {
"allocated_by": {
"id": "an_user_id",
"first_name": "Name",
"last_name": "Last Name"
},
"code": "ECD",
"assigned_by": {
"id": "an_user_id",
"first_name": "Name",
"last_name": "Last Name"
},
"id": "warehouse_id",
"name": "Name of the warehouse",
"picked_by": {
"id": "an_user_id",
"first_name": "Name",
"last_name": "Last Name"
}
},
"dangerous_goods": {
"limited_quantity_weight": 0.0
},
"b2b_config": null,
"warnings": [],
"insurance": null,
"byrd_id": "ABCD12345",
"options": {
"has_dangerous_goods": false,
"packaging": true,
"branding": false,
"skip_barcode": false,
"custom_handled": false,
"v3_packaging": false,
"partial_fulfillment": false,
"return_label": false,
"not_before_date": "2023-01-27T12:28:03.569257+00:00",
"direct_complete": false,
"not_later_date": null,
"preferred_carrier": null,
"pickup_date": "2023-01-30",
"charge": true,
"remunerate": true,
"incoterm": "DAP",
"international": false,
"auto_release": true,
"fragile": false,
"custom_handling": false
},
"priority": 10,
"user": {
"company_name": "Company",
"billing_address": {
"country_code": "DE",
"postal_code": "123456",
"state": null,
"id": "company_id",
"street_name": "Street name",
"city": "City",
"street_number": "1234",
"address_addition": ""
},
"id": "user_id",
"first_name": "Name",
"sender_name": null,
"last_name": "Last Name"
},
"status": "delivered",
"container_code": null,
"metrics": {
"total_items": 1,
"total_picks": 1,
"total_skus": 1,
"total_packaging_units": 0
},
"return_address": {
"country_code": "DE",
"postal_code": "12345",
"state": null,
"id": "address_id",
"street_name": "Street.",
"city": "City",
"name": "Warehouse name",
"street_number": "123",
"address_addition": ""
},
"destination_address": {
"created_at": "2023-01-27T14:21:02.840477+00:00",
"id": "address_id",
"state": "",
"validated": false,
"phone": null,
"name": "Recipient Name",
"country_code": "DE",
"email": "email",
"street_name": "Street",
"city": "City",
"updated_at": "2023-01-27T14:21:02.840484+00:00",
"street_number": "12",
"company_name": "",
"postal_code": "12345",
"address_addition": ""
},
"updated_at": "2023-02-01T11:16:01.031581+00:00",
"shop": {
"id": null,
"type": null,
"order_id": "your_order_id",
"order_number": "your_order_number"
},
"units": [
{
"type": "parcel",
"checkpoints": {
"accepted_at": null,
"delivered_at": "2023-02-01T11:06:00+00:00"
},
"parcel_id": "ABCD12345",
"sequence_number": 1,
"id": "unit_id",
"sub_status": null,
"dimensions": {
"height": 16.0,
"width": 23.0,
"weight": 0.8,
"length": 31.0
},
"service": "standard",
"status": "delivered",
"metrics": null,
"packaging_materials": [
{
"code": "ABC1234",
"quantity": 1
}
],
"items": [
{
"product": {
"serial_number_enabled": true,
"name": "Name of the product",
"id": "product_id",
"sku": "sku"
},
"packaging_unit_id": null,
"quantity": 1,
"custom_bundle_id": null,
"id": "unit_item_id",
"serial_numbers": null,
},
],
"carrier": {
"tracking_number": "001234567890",
"tracking_url": "https://www.thecarrier.co?piececode=001234567890",
"shipment_id": "01264567897546",
"fuel_surcharge_rate": {
"tax_factor": 1.19,
"value": 0.136875,
"actual_carrier": "Name of the carrier",
"currency": "EUR"
},
"shipping_rate": {
"tax_factor": 1.19,
"value": 1.11,
"currency": "EUR"
},
"byrd_shipping_rate": {
"tax_factor": 1.19,
"value": 2.22,
"currency": "EUR"
},
"name": "dhl_de"
},
"errors": []
}
],
"items": [
{
"created_at": "2023-01-27T14:21:02.845038+00:00",
"type": "product",
"customs": {
"hs_tariff_number": "21061020",
"origin_country_code": "DE"
},
"id": "item_id",
"dimensions": {
"height": null,
"width": null,
"weight": 0.5,
"length": null
},
"lot_number": null,
"dangerous_goods": [],
"product_id": "product_id",
"name": "Name of the product",
"serial_number_tracked": false,
"children": [],
"updated_at": "2023-01-27T14:21:02.845045+00:00",
"quantity": 1,
"description": "Description of the product",
"sku": "sku",
"fragile": false,
"price": {
"tax_factor": 1.0,
"value": 28.03,
"currency": "EUR"
}
}
],
"errors": []
}]
}
Updated about 2 months ago