GuidesAPI ReferenceChangelog
Guides

Tracking data

Overview

byrd saves the tracking data for the shipment under the units section. The tracking data consist in the carrier, tracking number and tracking url for each parcel. A unit gets its carrier, tracking number and tracking url when its shipping label is created, usually when it is packed: units in status packaged normally have them already, except B2B units still waiting for a label. Until a unit is sent, its label can still be replaced, for example when the shipment is recalled, so treat the tracking data as final once the unit is sent. Warehouse pickup shipments have no tracking data.

To get the tracking data you can periodically get the list of shipments filtering by sent_date_from and sent_date_to.

The units section

Shipment data contains a section called units. Under that section you will find a list of unit objects. Every unit object corresponds to a parcel in the real world. If the contents of the shipment can't fit into a single parcel, requiring them to be split up into multiple parts, multiple units will be created. Units have their own parcel ID and tracking information. The element carrier contains the tracking information per unit.

Carrier fields

FieldDescription
nameThe name of the carrier used to send the parcel.
tracking_numberThe tracking number from the carrier.
tracking_urlThe tracking url from the carrier.

Unit sub-status while sent

While a unit's status is sent, its sub_status reflects live carrier tracking updates. It is null for every other unit status.

Sub-statusDescription
pick_upThe carrier picked up the parcel from the warehouse.
in_transitThe parcel is moving through the carrier's network: sorted, on a truck or plane, clearing customs.
out_for_deliveryThe parcel is out for delivery today.
at_pickup_pointThe parcel arrived at a pickup point - a shop, locker or post office - and is waiting for the customer to collect it.
delayedThe carrier still expects to deliver the parcel, just later than planned.
failed_deliveryAn actual delivery exception occurred, not just a delay.

Unit data example

"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": []
            }
        ],

Updated 5 days ago