GuidesAPI ReferenceChangelog
API Reference

List shipments

get
https://api.getbyrd.com/v3/shipments

Returns your shipments that match the filters, newest first by
default. To keep tracking data in sync, list the shipments sent in a
period with sent_date_from and sent_date_to; add
include_unit_items to get the items and serial numbers of each
parcel.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
uuid

Only the shipment with this ID (UUID).

ids
array of uuids

Only shipments with any of these IDs (UUIDs).

ids
uuid

Only shipments containing the product with this ID (UUID).

product_ids
array of uuids

Only shipments containing any of these products (UUIDs).

product_ids
string

Only shipments with a parcel whose parcel ID contains this text, ignoring case; also finds deleted parcels.

uuid

Only shipments with the parcel (unit) with this ID (UUID); also finds deleted parcels.

string
length between 3 and 10

Only shipments whose byrd ID contains this text, ignoring case; 3 to 10 characters.

string

Only shipments with a parcel that has this carrier tracking number.

string

Only shipments to this destination postal code.

storage_zone_ids
array of uuids or null | null

For warehouse use: only shipments picked entirely from these storage zones (UUIDs); null selects shipments with a pick from storage outside any zone. Needs a status filter with only allocated shipments.

storage_zone_ids
uuid

For warehouse use: only shipments assigned to this warehouse worker (UUID).

warehouse_ids
array of uuids

Only shipments fulfilled by any of these warehouses (UUIDs).

warehouse_ids
uuid

Only shipments fulfilled by this warehouse (UUID).

carrier
array of strings

Only shipments with a parcel sent with any of these carriers, by carrier slug; see the list of carriers.

carrier
predicted_carrier
array of strings

Only shipments whose carrier, as predicted when the shipment was released, is any of these carrier slugs; unlike carrier, this also finds shipments that have no parcel yet.

predicted_carrier
string
enum

Only shipments sent with this service.

Allowed:
string
enum
Defaults to created_at

Date of the shipment that date_from and date_to filter on; defaults to created_at.

  • created_at: created
  • updated_at: last changed
  • released_at: last release attempt
  • picked_at: picking completed
  • packaged_date: packed
  • sent_date: handed over to the carrier
  • delivery_date: delivered
  • returned_date: returned
  • warehouse_sla_accepted_by, customer_sla_accepted_by: deadline for the carrier to accept the shipment
date-time

Only shipments whose date_field is at or after this time (ISO 8601, inclusive).

date-time

Only shipments whose date_field is before this time (ISO 8601, exclusive); must be after date_from. For one calendar day, pass the following day, not the same day as date_from.

date-time

Only shipments sent at or after this time (ISO 8601).

date-time

Only shipments sent at or before this time (ISO 8601); must not be before sent_date_from.

date

Only shipments sent on this day (ISO 8601 date, UTC). Cannot be combined with date_from, date_to, sent_date_from or sent_date_to.

integer
≥ 1

Only shipments released at least this many whole days ago; at least 1.

boolean

When true, only shipments whose last release attempt failed.

boolean

When true, only shipments waiting to be released to a warehouse.

boolean

When true, only shipments waiting for their stock to be allocated in the warehouse.

boolean

When true, only packed shipments still waiting for a shipping label (sub-status label_required or label_error); when false, all other shipments.

boolean

When true, only shipments held because their address validation failed; when false, only shipments without an address validation error.

boolean

When true, only shipments whose stock could not be allocated in the warehouse.

boolean

When true, only shipments with a parcel whose shipping label could not be created (sub-status label_error).

boolean

When true, only shipments with a parcel whose label error was resolved and that waits to be packed again (sub-status error_resolved).

string

For warehouse use: only shipments kept in the warehouse container with this code before packing.

string

Only shipments to this recipient email address, ignoring case.

boolean

When true, only B2B shipments; when false, only B2C shipments.

processing_standard
array of strings

Only B2B shipments that use any of these B2B templates, by template key.

processing_standard
boolean

When true, only cash on delivery shipments; when false, only other shipments.

status
array of strings

Only shipments in any of these statuses; see status on the shipment for the values.

status
sub_status
array of strings

Only shipments in any of these sub-statuses; needs a status filter. With more than one sub-status, send exactly one status, and each combination has to be valid.

sub_status
exclude_sub_status
array of strings

Leaves out shipments in any of these sub-statuses; shipments without a sub-status are kept.

exclude_sub_status
boolean

When true, only shipments blocked because documents they need are missing.

priority_range
array of integers
length ≥ 2

For warehouse use: only shipments whose picking priority is within this range, given as min,max from 0 to 50; needs a status filter with only released statuses.

priority_range
integer
0 to 50

For warehouse use: only shipments with exactly this picking priority, from 0 to 50; needs a status filter with only released statuses.

destination_countries
array of strings

Only shipments to any of these countries (ISO 3166-1 alpha-2), for example DE,AT.

destination_countries
integer
≥ 1

Only shipments with exactly this number of different products, not counting bundles themselves; at least 1.

integer
≥ 1

Only shipments with exactly this total number of physical items to pick, counting the contents of bundles; at least 1.

integer
≥ 1

For warehouse use: only shipments with exactly this number of items to pick, counting a packaging unit as one; needs a status filter with only allocated shipments.

product_quantities
array of strings

For warehouse use: only shipments with exactly these contents, given as product_id:quantity pairs; needs a status filter with only allocated shipments.

product_quantities
lot_ids
array of uuids

For warehouse use: only shipments whose picks come from exactly this set of lots (UUIDs); an empty list selects shipments without lot-tracked picks. Needs a status filter with only allocated shipments.

lot_ids
boolean

For warehouse use: when true, only shipments with exactly the same contents as at least one other shipment in the result; needs a status filter with only allocated shipments.

exclude
array of strings

Parts to leave out of the response, which makes it faster: items, units.

exclude
Allowed:
only
array of strings

Fields to return, as comma-separated dotted paths of response field names, for example id,status,units.items; all fields when not sent.

only
string
enum

Only shipments with a label error in this state.

  • blocked: not resolved yet, like failed_packaging
  • resolved: resolved, like error_resolved
Allowed:
boolean

Only shipments packed (true) or not packed (false) with the v3 packing process.

string

Only shipments with exactly this shop.order_number.

string

Only shipments with exactly this shop.marketplace_order_number.

string

Only shipments with this shop.marketplace, for example amazon.

boolean

For warehouse use: when true, only shipments containing products that have a barcode.

boolean
Defaults to false

Whether to include the items packed in each parcel (units.items), for example to read their serial numbers; defaults to false. Cannot be combined with excluding units.

boolean

For warehouse use: when true, only shipments that can be packed on the automated labelling line; needs a status filter with only released statuses.

boolean

For warehouse use: only shipments that can (true) or cannot (false) be packed with the automatic bagging machine; needs a status filter with only released statuses.

boolean

When true, only shipments that can still be returned: sent, delivered, returning or returned, and sent within the last 180 days.

boolean

When true, only shipments with an open action you need to take to unblock them.

boolean

Only shipments that need (true) or do not need (false) a customs declaration because they cross a customs border; known once a shipment is released.

boolean

Only shipments that have (true) or do not have (false) a shipping label document.

uuid

For warehouse use: ID of a saved set of filters to apply instead of individual filters (UUID).

boolean

Deprecated. For warehouse use: when true, only shipments picked entirely from storage at ground level; when false, only shipments with at least one pick from a higher level.

boolean

For warehouse use: only shipments whose picking needs (true) or does not need (false) a forklift.

integer
≥ 1
Defaults to 250

Number of results per page

integer
≥ 0
Defaults to 0

Result page to jump to, 0-indexed

string

The model field to sort results by

string
enum

The direction of result sorting

Allowed:
string

The search term

fields
array of strings

Model fields to search through; comma separated

fields
Headers
string
enum
Defaults to application/vnd.byrd.customer+json

Generated from available response content types

Allowed:
Responses

Updated 29 days ago

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/vnd.byrd.customer+json
application/json

Updated 29 days ago