Create a shipment

post

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

Creates a B2C shipment, or a B2B shipment when b2b_config is sent.
The shipment starts in status new and is released to a warehouse
automatically when options.auto_release is true. Use
validate_only to check a request without creating the shipment.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

validate_only

boolean

Defaults to false

Whether to only validate the request and return the resulting shipment without saving it; defaults to false.

ensure_unique_order_id

boolean

Defaults to false

Whether to reject the shipment (409) if one of your shipments that is not deleted already has the same shop.order_id; defaults to false.

ensure_unique_marketplace_order_number

boolean

Defaults to false

Whether to reject the shipment (409) if another shipment from the same shop integration already has this shop.marketplace_order_number; only applies to shipments from a byrd shop integration. Defaults to false.

Body Params

customs

object | null

Customs details used to generate the export documents; required for international shipments. null when none were provided.

destination_address

object

required

Address and contact details of the recipient. For deliveries to a carrier pickup point, see the pickup point guides for how to fill it.

documents

array of objects

Documents the warehouse prints and packs with the shipment, such as delivery notes or invoices.

documents

insurance

object | null

Declared value the shipment is insured for; null when the shipment is not insured.

items

array of objects

required

length ≥ 1

Products in the shipment and their quantities; at least one.

items*

product_id

uuid | null

ID of the byrd product to ship (UUID); send it or sku. null for custom bundles.

shop_product_id

string | null

ID of the product in your shop or order system; not necessarily a UUID.

quantity

integer

required

≥ 1

Number of units to ship; at least 1. For items of a custom bundle, the number per bundle.

name

string | null

Name of the product; replaced by the name stored on the product. Required for custom bundles and their items.

price

object | null

Retail price of one unit, used for customs documents and insurance; it is multiplied by quantity. Required for custom bundles.

dimensions

object | null

Dimensions and weight of one unit of the product; missing values are taken from the product, and the weight stored on the product always replaces the one sent.

customs

object | null

Customs details of the product, needed for shipments leaving the EU or the UK; taken from the product when not sent.

lot_number

string | null

Lot the units have to be picked from; if not sent, byrd chooses lots first in, first out (FIFO).

description

string | null

Description of the product, used on customs documents; taken from the product when not sent.

sku

string | null

SKU of the byrd product to ship; send it or product_id. Required for custom bundles, where it has to be unique within the shipment.

serial_number_tracked

boolean | null

Whether serial numbers are recorded for the item when it is packed; set from the serial number setting of the product.

type

string | null

Type of item.

product: a single product (default)
bundle: a bundle product set up in byrd
custom_bundle: products packed together, listed in children
supplement: a supplementary product, such as a flyer, added because it is linked to another product in the shipment

children

array of objects | null

Items the bundle consists of; empty for other item types. Required when type is custom_bundle: list every product to pack together, including the bag or box they go in.

children

notes

object | null

Free-text notes for your own use and packaging instructions for the warehouse.

options

object

Fulfilment and shipping options set on the shipment.

service

string

enum

Shipping service the shipment is sent with.

standard: regular delivery
express: faster delivery, picked with higher priority
economy: cheapest, slower delivery
pickup_point: delivery to a carrier pickup point
pickup: collected from the warehouse, not shipped

Allowed:

shop

object

Order references from your shop or order system, such as the order number.

user_id

string

ID of the byrd account the shipment is created for (UUID); for your requests it is always your own account.

warehouse_id

string

ID of the warehouse that has to fulfil the shipment; if omitted, byrd assigns one automatically.

cash_on_delivery

object | null

Amount the carrier collects from the recipient on delivery; null when the shipment is not cash on delivery.

pickup_point

object | null

Carrier pickup point to deliver to, for pickup_point shipments; the fields it needs depend on the carrier.

packaging_materials

array of objects

Packaging materials requested or suggested for packing the shipment.

packaging_materials

201Success response to a valid request

400Generic error response

403Generic error response