Creating a shipment
API reference ShipmentListAPIV3
Overview
This endpoint can be used to create shipments in byrd. By default a B2C shipment will be created. Please refer to Creating a B2B shipment for B2B shipments
Method access
POST 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
Fields
To create a product usable by the rest of the system these fields are required or might be required in the JSON request body depending on your case:
| Field | Type | Description | Required |
|---|---|---|---|
| destination_address | address object | The destination address details. See: Destination details | always |
| items | list of item objects | The items to be included in the shipment and their quantity. See: Items | always |
| service | string | Shipment method. This overrides the automatic selection by byrd and can lead to shipment errors. This field should be used with caution. It accepts: express, standard, economy, pickup_point.It defaults to standard if not sent.For pickup point shipments, see specific guides for supported carriers. | optional |
| warehouse_id | string | Id of the warehouse that has to fulfill the shipment. If not sent, the warehouse is automatically assigned. See: Listing warehouses | optional |
| options | options object | Options for the shipment. See: Options | optional |
| shop | shop object | Fields to add custom details from your order system. See: Shop | optional |
| documents | list of documents objects | Documents for the shipment. See: Documents | optional |
| notes | notes object | Notes for the shipment. See: Notes | optional |
| insurance | insurance object | Insurance details for the shipment. See: Insurance | optional |
| customs | customs object | Details about the good types an invoice number for customs. See: Customs | conditional Required for international shipments |
| cash_on_delivery | cash_on_delivery object | Details about price and currency for cash on delivery shipments. See: Cash on delivery | conditional Required for cash on delivery shipments |
| packaging_materials | list of packaging_material object | To suggest or require the warehouse which packaging material to use. See: Packaging materials | optional |
Destination details
Please fill the destination_address data using the right field for each type of data as accurately as possible to ensure that your shipments are processed delivered without incidents.
The destination email and phone will be given to the carrier to inform the recipient about the delivery. Some carriers send emails and or SMS to the recipient.
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | Name of the recipient if recipient is an individual. | always |
| company_name | string | Company name if recipient is a company. | always if not individual |
| string | Recipient email. | optional | |
| street_name | string | Name of the street. Please send the number of the street in the field street_number if possible. | always |
| street_number | string | Number of the street. | always |
| address_addition | string | Rest of address details like building or floor. | optional |
| city | string | Recipient city. | always |
| postal_code | string | Recipient postal code. | always |
| state | string | Recipient state. | optional |
| country_code | string | Country code of the recipient. It accepts only ISO 3166-1 two digit codes. | always |
| phone | string | Recipient phone number. Please send the phone number country code if possible. (Eg. +49 12345890) | always</span |
Items
Under items, you need to specify the items that are shipped with a shipment. If there is no stock available for any of the items, the shipment will remain in pending and it can be released manually from the dashboard once the stock is updated.
| Field | Type | Description | Required |
|---|---|---|---|
| sku | string | SKU of the product previously created in byrd. | conditional Required if product_id is not sent |
| product_id | string | Id of the product previously created in byrd if sku is not sent. | conditional Required if sku is not sent |
| name | string | Name of the product. | optional |
| quantity | integer | Quantity of units to ship. | always |
| lot_number | string | Lot the product should be picked from. If not specified, byrd uses the FIFO principle to choose a lot. | optional |
| price | price object | Unit price used for customs documents and shipment insurance. fields: - value (number): digits with decimals separated by a dot. - currency (string): currency in ISO 3-Letter code. Retail price should be used here. This price will be multiplied by the number indicated in the field "quantity" while building the customs documents. | optional |
| customs | customs object | Details for customs. fields: - hs_tariff_number (string): Unique code that is documented in the Harmonised System (HS) for your product. It accepts only digits with lengths of 6, 8, or 10. - origin_country_code (string): Country code of the origin of the product. It accepts only ISO 3166-1 two digit codes. | conditional Required if you plan to send shipments outside of EU or UK and the data is not stored in the product. See Creating a product |
| type | string | Type of item. It accepts product (default), bundle or custom_bundleIf the value is custom_bundle, then the field children must be filled. | optional |
| children | list of custom bundle item objects | Custom bundle items. See: Custom bundles | conditional Required if type is custom_bundle |
Custom bundles
A custom bundle is a special item type to identify articles that have to be packed together in a bag or a box. A parcel can include multiple custom bundles or custom bundles and single articles.
This feature is useful if, for example, your business sells kits that can be customised by your customer during the checkout.
The parent item must include a value in the sku field as well as in the name field. This SKU won't be present in the Products list of your dashboard as it is not a real product, but it's used internally by the system to identify the custom bundle within the shipment and to create customs documents. It's not possible to have duplicated SKUs for custom bundles in the same shipment.
Custom bundle items
Specify the ingredients of your custom bundle by sending a list of custom bundle items in the field children.
Be sure to include the bag or the box where the ingredients has to be grouped among the custom bundle items.
You can specify the price, dimensions and customs details for the whole custom bundle by setting them on the parent item.
| Field | Type | Description | Required |
|---|---|---|---|
| sku | string | SKU of the product previously created in byrd. | conditional Required if product_id is not sent |
| product_id | string | Id of the product previously created in byrd if sku is not sent. | conditional Required if sku is not sent |
| name | string | Name of the product. | always |
| quantity | integer | Quantity of units to ship. | always |
Options
Under options you can specify if the shipment should be autoreleased to the warehouse, the preferred carrier and the incoterm in case of international shipments.
| Field | Type | Description | Required |
|---|---|---|---|
| auto_release | boolean | If the shipment should be autoreleased to the warehouse after being created. Otherwise it will stay in status new for manual release from the dashboard. It accepts: true, false | optional |
| preferred_carrier | string | If a specific carrier is preferred for this shipment. This overrides the automatic selection by byrd and can lead to shipment errors. This field should be used with caution. Use Listing carriers to get the list of available carriers. | optional |
| incoterm | string | The incoterm used for the shipment and passed to the carrier. It accepts: DAP, DDP | optional |
Shop
Under shop, you can include details from your order management system and use them to link byrd shipments with the orders in your system.
| Field | Type | Description | Required |
|---|---|---|---|
| order_number | string | This field will be visible under the column Order in the dashboard. | optional |
| order_id | string | Use this field for any other identifier of your orders. This field won't be visible in the dashboard. | optional |
Documents
Under documents, you can attach a link to documents to be printed with the shipment. The element accepts a list of objects with these fields:
| Field | Type | Description | Required |
|---|---|---|---|
| url | string | Url of the document. It can be an FTP or HTTP server without authentication. Document will be downloaded at the moment of printing. | always |
| name | string | Name of the document without spaces. | always |
| type | string | Type of document. It accepts: consignment_note, delivery_note, export_document, proforma_invoice, supplement, other | always |
| print_copies | integer | Number of copies to be printed. | always |
| format | string | Format of the document. It accepts: document | always |
| data_type | string | Type of document. It accepts: pdf | always |
Notes
Under notes, you can include some internal notes and packaging instructions .
| Field | Type | Description | Required |
|---|---|---|---|
| customer_note | string | Note visible in the dashboard for byrd customer internal use. It is not sent to the recipient nor shown to the warehouse.. | optional |
| packaging_instructions | string | Packaging instructions to the warehouse. | optional |
Insurance
Fill the insurance object with the value of the shipment goods for insurance purposes.
| Field | Type | Description | Required |
|---|---|---|---|
| value | string | The value of the whole shipment for insurance purposes. It accepts string of digits with decimals separated by a dot. | optional |
| currency | string | Currency in ISO 3-Letter code. | optional |
Customs
For international shipments, the customs object is required as well as the customs object for every item line so the customs documents can be generated automatically by byrd. See Items
| Field | Type | Description | Required |
|---|---|---|---|
| invoice_number | string | The commercial invoice number of the order. | always |
| goods_type | string | The goods type included in the shipment. It accepts: document, gift, sample, remand, other | always |
Cash on delivery
For cash on delivery shipments, the cash_on_delivery object is required containing the object price including these fields:
| Field | Type | Description | Required |
|---|---|---|---|
| value | string | The total amount to collect from the customer. String of digits with decimals separated by a dot. | always |
| currency | string | Currency It accepts: EUR | always |
Packaging materials
You can send the unique packaging material code on the shipment body to require or suggest the warehouse use a specific packaging material for a shipment. Remember that you must create the packaging material in your dashboard first, and the warehouse must validate it. After that, you can ask our Support for the unique code for the packaging material you created.
There are two modes of using this feature:
- Suggestion mode (required: false): when the warehouse is suggested to use the specified packaging material but can use a different one for some reason (e.g., the product doesn't fit in the material).
- Required mode (required: true): when the warehouse must use the packaging material if there is stock. Please use this field carefully once you confirm that your products fit well in the packaging material required. If the warehouse has stock of the packaging material but the content can't fit, the shipment might get blocked until the packaging material is updated. You can only do this through the API by calling Updating a shipment .
In both modes, if the packaging material is not in stock in the warehouse, a different one will be used.
The field packaging_materials accepts a list of an object with these fields:
| Field | Type | Description | Required |
|---|---|---|---|
| code | string | The unique packaging material code. This code has to be asked to Support once the new packaging material was validated by the warehouse. | always |
| quantity | integer | Quantity | always |
| required | boolean | If packaging material is required or suggested It accepts: true, false.It defaults to true if not sent. | optional |
Request body example
{
"destination_address": {
"name": "William Byrd",
"company_name": "",
"email": "[email protected]",
"street_name": "The name of the street",
"street_number": "15",
"address_addition": "1st floor",
"city": "City",
"postal_code": "458ABC",
"country_code": "DE",
"phone": "+421111111111"
},
"items": [
{
"sku": "AB-1234",
"name": "Dog food",
"quantity": 2,
"lot_number": "2/23",
"price": {
"value": 20,
"currency": "EUR"
},
"customs": {
"hs_tariff_number": "9101218956",
"origin_country_code": "CN"
}
},
{
"sku": "KIT-5678",
"name": "Kit of dog food",
"quantity": 2,
"price": {
"value": 45,
"currency": "EUR"
},
"customs": {
"hs_tariff_number": "4632454578",
"origin_country_code": "CN"
},
"type": "custom_bundle",
"children": [
{
"name": "Dog food",
"quantity": 4,
"sku": "AB-1234"
},
{
"name": "Iron supplement",
"quantity": 4,
"sku": "IS-1994"
},
{
"name": "Bag",
"quantity": 1,
"sku": "BAG-1890"
}
]
}
],
"service": "economy",
"options": {
"auto_release": true,
"preferred_carrier": "DHL",
"incoterm": "DAP"
},
"shop": {
"order_number": "OW-18940",
"order_id": "123456"
},
"documents": [
{
"type": "delivery_note",
"url": "https://urltodocument.com/OW-18940.pdf",
"print_copies": 1,
"format": "document",
"data_type": "pdf",
"name": "Delivery_note"
}
],
"notes": {
"customer_note": "This is an internal note",
"packaging_instructions": "Please put the flyer on top of the items."
},
"insurance": {
"value": "20.45",
"currency": "EUR"
},
"customs": {
"invoice_number": "2023-12894091",
"goods_type": "other"
},
"cash_on_delivery": {
"price": {
"value": 20.00,
"currency": "EUR"
}
},
"packaging_materials": [
{
"code": "C004854",
"quantity": 1,
"required": false
}
]
}
Successful response example
{
"data": {
"byrd_id": "TSU64QKPSC",
"created_at": "2023-07-19T06:36:19.012258+00:00",
"customs": {
"invoice_number": "2023-12894091",
"goods_type": "other"
},
"return_address": null,
"warnings": [],
"status": "new",
"metrics": {
"total_picks": 0,
"total_items": 13,
"total_skus": 0,
"total_packaging_units": 0
},
"warehouse": {
"id": null,
"picked_by": null
},
"container_code": null,
"destination_address": {
"validated": false,
"created_at": "2023-07-19T06:36:19.008108+00:00",
"name": "William Byrd",
"street_name": "The name of the street",
"state": null,
"company_name": "",
"address_addition": "1st floor",
"city": "City",
"country_code": "DE",
"id": "an_unique_id",
"email": "[email protected]",
"postal_code": "458ABC",
"phone": "+421111111111",
"updated_at": "2023-07-19T06:36:19.008126+00:00",
"street_number": "15"
},
"units": [],
"options": {
"incoterm": "DAP",
"international": null,
"branding": false,
"fragile": false,
"v3_packaging": false,
"return_label": false,
"auto_release": true,
"remunerate": true,
"not_later_date": null,
"charge": true,
"packaging": false,
"partial_fulfillment": false,
"pickup_date": null,
"preferred_carrier": "DHL",
"custom_handled": false,
"skip_barcode": false,
"has_dangerous_goods": false,
"custom_handling": false,
"direct_complete": false
},
"checkpoints": {
"delivered_at": null,
"returned_at": null,
"released_at": null,
"packaging_started_at": null,
"packaged_at": null,
"accepted_at": null,
"sent_at": null
},
"shop": {
"order_number": "OW-18940",
"order_id": "123456",
"id": null,
"type": null
},
"cash_on_delivery": {
"price": {
"value": 20.0,
"currency": "EUR"
}
},
"sub_status": "validating_address",
"notes": {
"packaging_instructions": "Did you ever hear the Tragedy of Darth Plagueis the Wise?\nNo.\nI thought not. It's not a story the Jedi would tell you. It's a Sith legend. ",
"label_error_note": null,
"customer_note": "This is an internal note"
},
"id": "an_unique_id",
"dangerous_goods": {
"limited_quantity_weight": 0.0
},
"b2b_config": null,
"user": {
"id": "an_unique_id",
"first_name": "Will",
"last_name": "Byrdinger",
"sender_name": null,
"billing_address": {
"id": "an_unique_id",
"postal_code": "10401",
"street_name": "Favoritenstraße testt",
"city": "Wien",
"street_number": "18",
"country_code": "AT",
"state": null,
"address_addition": "1. Stock"
},
"company_name": "Byrdinger"
},
"service": "economy",
"packaging_materials": [
{
"code": "C004854",
"quantity": 1,
"required": false
}
],
"errors": [],
"updated_at": "2023-07-19T06:36:19.012273+00:00",
"insurance": {
"value": 20.45,
"currency": "EUR"
},
"items": [
{
"quantity": 2,
"created_at": "2023-07-19T06:36:19.019100+00:00",
"customs": {
"origin_country_code": "CN",
"hs_tariff_number": "4632454578"
},
"name": "Kit of dog food",
"price": {
"value": 45.0,
"currency": "EUR",
"tax_factor": 1.0
},
"dimensions": {
"weight": 0.0,
"length": null,
"height": null,
"width": null
},
"fragile": false,
"description": null,
"type": "custom_bundle",
"id": "an_unique_id",
"sku": "KIT-5678",
"dangerous_goods": null,
"lot_number": null,
"updated_at": "2023-07-19T06:36:19.019102+00:00",
"children": [
{
"quantity": 4,
"id": "an_unique_id0",
"customs": null,
"lot_number": null,
"fragile": false,
"description": null,
"sku": "AB-1234",
"name": "Dog food",
"price": null,
"dimensions": {
"weight": null,
"length": null,
"height": null,
"width": null
},
"dangerous_goods": null,
"type": "product",
"product_id": null,
"serial_number_tracked": false
},
{
"quantity": 1,
"id": "an_unique_id",
"customs": null,
"lot_number": null,
"fragile": false,
"description": null,
"sku": "BAG-1890",
"name": "Bag",
"price": null,
"dimensions": {
"weight": null,
"length": null,
"height": null,
"width": null
},
"dangerous_goods": null,
"type": "product",
"product_id": null,
"serial_number_tracked": false
},
{
"quantity": 4,
"id": "an_unique_id",
"customs": null,
"lot_number": null,
"fragile": false,
"description": null,
"sku": "IS-1994",
"name": "Iron supplement",
"price": null,
"dimensions": {
"weight": null,
"length": null,
"height": null,
"width": null
},
"dangerous_goods": null,
"type": "product",
"product_id": null,
"serial_number_tracked": false
}
],
"product_id": null,
"serial_number_tracked": false
},
{
"quantity": 2,
"created_at": "2023-07-19T06:36:19.019070+00:00",
"customs": {
"origin_country_code": "CN",
"hs_tariff_number": "9101218956"
},
"name": "Dog food",
"price": {
"value": 20.0,
"currency": "EUR",
"tax_factor": 1.0
},
"dimensions": {
"weight": null,
"length": null,
"height": null,
"width": null
},
"fragile": false,
"description": null,
"type": "product",
"id": "an_unique_id",
"sku": "AB-1234",
"dangerous_goods": null,
"lot_number": "2/23",
"updated_at": "2023-07-19T06:36:19.019081+00:00",
"children": [],
"product_id": null,
"serial_number_tracked": false
}
],
"priority": null
}
}
Updated 10 days ago
What’s Next