Getting the details of a shipment
API reference ShipmentAPIV3
Overview
To get the details of a specific shipment including the tracking data, send the shipment_id in the endpoint. The response will include different shipment details
Method access
GET https://api.getbyrd.com/v3/shipments/<shipment_id>
Request Headers
Authorization: Bearer token-from >Authentication
Content-Type: application/json
User-Agent: your user-agent >How to call the APIs
Successful response example
{
"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": [],
"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": []
}
}
List of Shipments
API: ShipmentListAPIV3
Tracking information for multiple shipments can be obtained by using the the following endpoint. To limit the number of obtained shipments we advise to use filter options which can be passed as parameters.
- postal_code
- sent_date
- product_ids: array[string]
- status: Values: sent, delivered, returning, returned
- sent_date_to: Shipments sent before specific point in time
- sent_date_from: Shipments sent after specific point in time
For example only check shipments with status=sent.
GET /v3/shipments?status=sent
Tracking Information Data Format
Shipments contain a list with the name units. Inside this list the element carrier conatains the tracking information per unit.
byrd Terminology: Units
A unit corresponds to a parcel in the real world. The majority of shipments have a single unit, however some have more than one. This happens because the contents of the shipment can't fit into a single parcel, requiring them to be split up into multiple parts. Units have their own parcel ID and tracking information.
Example units List
units ListThe following code is an example of the units List. This example shows only a the relevant fields. A complete example can be found in the documentation of the response of the request.
"units": [
{
"type": "parcel",
"carrier": {
"name": "dhl_de",
"tracking_url": "https://carrier-tracking/ABCD1234GH",
"shipment_id": "1324376253",
"tracking_number": "ABCD1234GH"
},
"dimensions": {
"weight": 0.25,
"width": 13.0,
"length": 18.0,
"height": 5.0
},
"service": "standard",
"status": "sent",
"parcel_id": "1234ABC45"
}
]
Updated about 1 year ago