---
updatedAt: 2026-09-24T17:18:51.000Z
agentTools:
  projectIndex: https://developers.getbyrd.com/llms.txt
---

# Creating a shipment

API reference [ShipmentListAPIV3](ref:shipmentlistapiv3_post)

## 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](https://developers.getbyrd.com/docs/creating-b2b-shipment) for B2B shipments

#

**Method access**\
`POST https://api.getbyrd.com/v3/shipments`\
**Request Headers**\
`Authorization: Bearer token-from >`[Authentication](https://developers.getbyrd.com/docs/authentication)\
`Content-Type: application/json`\
`User-Agent:  your user-agent >`[How to call the APIs](https://developers.getbyrd.com/docs/how-to-call-byrd-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:

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> destination_address </span>",
    "0-1": "<span style=\"color:Teal\">address object</span>",
    "0-2": "**The destination address details.**  \nSee: [Destination details](https://developers.getbyrd.com/docs/creating-a-shipment#destination-details)",
    "0-3": "<span style=\"color:salmon\">always</span>",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> items </span>",
    "1-1": "<span style=\"color:Teal\">list of item objects</span>",
    "1-2": "**The items to be included in the shipment and their quantity.**  \nSee: [Items](https://developers.getbyrd.com/docs/creating-a-shipment#items)",
    "1-3": "<span style=\"color:salmon\">always</span>",
    "2-0": "<span style=\"color:SteelBlue; background:azure\"> service </span>",
    "2-1": "<span style=\"color:Teal\">string</span>",
    "2-2": "**Shipment method.**  \nThis overrides the automatic selection by byrd and can lead to shipment errors. This field should be used with caution.  \nIt accepts: `express`, `standard`, `economy`, `pickup_point`.  \nIt defaults to `standard` if not sent.  \nFor pickup point shipments, see specific guides for supported carriers.",
    "2-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "3-0": "<span style=\"color:SteelBlue; background:azure\"> warehouse_id</span>",
    "3-1": "<span style=\"color:Teal\">string</span>",
    "3-2": "**Id of the warehouse that has to fulfill the shipment.**  \nIf not sent, the warehouse is automatically assigned.  \nSee: [Listing warehouses](https://developers.getbyrd.com/docs/list-of-warehouses)",
    "3-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "4-0": "<span style=\"color:SteelBlue; background:azure\"> options </span>",
    "4-1": "<span style=\"color:Teal\">options object</span>",
    "4-2": "**Options for the shipment.**  \nSee: [Options](https://developers.getbyrd.com/docs/creating-a-shipment#options)",
    "4-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "5-0": "<span style=\"color:SteelBlue; background:azure\"> shop</span>",
    "5-1": "<span style=\"color:Teal\">shop object</span>",
    "5-2": "**Fields to add custom details from your order system.**  \nSee: [Shop](https://developers.getbyrd.com/docs/creating-a-shipment#shop)",
    "5-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "6-0": "<span style=\"color:SteelBlue; background:azure\">documents</span>",
    "6-1": "<span style=\"color:Teal\"> list of documents objects</span>",
    "6-2": "**Documents for the shipment.**  \nSee: [Documents](https://developers.getbyrd.com/docs/creating-a-shipment#documents)",
    "6-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "7-0": "<span style=\"color:SteelBlue; background:azure\">notes</span>",
    "7-1": "<span style=\"color:Teal\">notes object</span>",
    "7-2": "**Notes for the shipment.**  \nSee: [Notes](https://developers.getbyrd.com/docs/creating-a-shipment#notes)",
    "7-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "8-0": "<span style=\"color:SteelBlue; background:azure\"> insurance </span>",
    "8-1": "<span style=\"color:Teal\">insurance object</span>",
    "8-2": "**Insurance details for the shipment.**  \nSee: [Insurance](https://developers.getbyrd.com/docs/creating-a-shipment#insurance)",
    "8-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "9-0": "<span style=\"color:SteelBlue; background:azure\"> customs</span>",
    "9-1": "<span style=\"color:Teal\">customs object</span>",
    "9-2": "**Details about the good types an invoice number for customs.**  \nSee: [Customs](https://developers.getbyrd.com/docs/creating-a-shipment#customs)",
    "9-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired for international shipments",
    "10-0": "<span style=\"color:SteelBlue; background:azure\"> cash_on_delivery</span>",
    "10-1": "<span style=\"color:Teal\">cash_on_delivery object</span>",
    "10-2": "**Details about price and currency for cash on delivery shipments.**  \nSee: [Cash on delivery](https://developers.getbyrd.com/docs/creating-a-shipment#cash-on-delivery)",
    "10-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired for cash on delivery shipments",
    "11-0": "<span style=\"color:SteelBlue; background:azure\"> packaging_materials</span>",
    "11-1": "<span style=\"color:Teal\">list of packaging_material object</span>",
    "11-2": "**To suggest or require the warehouse which packaging material to use.**  \nSee: [Packaging materials](https://developers.getbyrd.com/docs/creating-a-shipment#packaging-materials)",
    "11-3": "<span style=\"color:DarkKhaki\">optional</span>"
  },
  "cols": 4,
  "rows": 12,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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 and 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.

Only `country_code` is required to create the shipment. Fields marked `required to release` can be added later by updating the shipment, but the shipment cannot be released to the warehouse without them.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\">name </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**Name of the recipient.**  \nAlso needed when the recipient is a company, for example the contact person.",
    "0-3": "<span style=\"color:salmon\">required to release</span>  \nA shipment without it is still created, but held in status `new` (sub-status `address_invalid`) until you add it.",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> company_name</span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**Company name if recipient is a company.**",
    "1-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "2-0": "<span style=\"color:SteelBlue; background:azure\"> email </span>",
    "2-1": "<span style=\"color:Teal\">string</span>",
    "2-2": "**Recipient email.**",
    "2-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired to release shipments from a Spanish warehouse to Spain",
    "3-0": "<span style=\"color:SteelBlue; background:azure\"> street_name </span>",
    "3-1": "<span style=\"color:Teal\">string</span>",
    "3-2": "**Name of the street.**  \nPlease send the number of the street in the field street_number if possible.",
    "3-3": "<span style=\"color:salmon\">required to release</span>",
    "4-0": "<span style=\"color:SteelBlue; background:azure\">street_number</span>",
    "4-1": "<span style=\"color:Teal\">string</span>",
    "4-2": "**Number of the street.**",
    "4-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired for DHL Packstation and Postfiliale deliveries, where it is the Packstation or Postfiliale number",
    "5-0": "<span style=\"color:SteelBlue; background:azure\">address_addition</span>",
    "5-1": "<span style=\"color:Teal\">string</span>",
    "5-2": "**Rest of address details like building or floor.**",
    "5-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "6-0": "<span style=\"color:SteelBlue; background:azure\">city</span>",
    "6-1": "<span style=\"color:Teal\">string</span>",
    "6-2": "**Recipient city.**",
    "6-3": "<span style=\"color:salmon\">required to release</span>  \nA shipment without it is still created, but held in status `new` (sub-status `address_invalid`) until you add it.",
    "7-0": "<span style=\"color:SteelBlue; background:azure\"> postal_code </span>",
    "7-1": "<span style=\"color:Teal\">string</span>",
    "7-2": "**Recipient postal code.**",
    "7-3": "<span style=\"color:salmon\">required to release</span>  \nExcept for destinations without postal codes: `AE`, `HK`, `LB`, `QA`",
    "8-0": "<span style=\"color:SteelBlue; background:azure\">state</span>",
    "8-1": "<span style=\"color:Teal\">string</span>",
    "8-2": "**Recipient state.**",
    "8-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "9-0": "<span style=\"color:SteelBlue; background:azure\"> country_code </span>",
    "9-1": "<span style=\"color:Teal\">string</span>",
    "9-2": "**Country code of the recipient.**  \nIt accepts only ISO 3166-1 two digit codes.",
    "9-3": "<span style=\"color:salmon\">always</span>",
    "10-0": "<span style=\"color:SteelBlue; background:azure\"> phone</span>",
    "10-1": "<span style=\"color:Teal\">string</span>",
    "10-2": "**Recipient phone number.**  \nPlease send the phone number country code if possible. (Eg. +49 12345890)",
    "10-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired to release pickup point shipments and cash on delivery shipments to Italy"
  },
  "cols": 4,
  "rows": 11,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\">sku </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**SKU of the product previously created in byrd.**",
    "0-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired if product_id is not sent",
    "1-0": "<span style=\"color:SteelBlue; background:azure\">product_id </span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**Id of the product previously created in byrd if sku is not sent.**",
    "1-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired if sku is not sent",
    "2-0": "<span style=\"color:SteelBlue; background:azure\">name </span>",
    "2-1": "<span style=\"color:Teal\">string</span>",
    "2-2": "**Name of the product.**",
    "2-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "3-0": "<span style=\"color:SteelBlue; background:azure\"> quantity </span>",
    "3-1": "<span style=\"color:Teal\">integer</span>",
    "3-2": "**Quantity of units to ship.**",
    "3-3": "<span style=\"color:salmon\">always</span>",
    "4-0": "<span style=\"color:SteelBlue; background:azure\"> lot_number </span>",
    "4-1": "<span style=\"color:Teal\">string</span>",
    "4-2": "**Lot the product should be picked from.** If not specified, byrd uses the FIFO principle to choose a lot.",
    "4-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "5-0": "<span style=\"color:SteelBlue; background:azure\"> price </span>",
    "5-1": "<span style=\"color:Teal\">price object</span>",
    "5-2": "**Unit price used for customs documents and shipment insurance.**  \nfields:  \n  \n- value (number): digits with decimals separated by a dot.\n- currency (string): currency in ISO 3-Letter code.  \n  **Retail price** should be used here. This price will be multiplied by the number indicated in the field \"quantity\" while building the customs documents.",
    "5-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "6-0": "<span style=\"color:SteelBlue; background:azure\"> customs</span>",
    "6-1": "<span style=\"color:Teal\">customs object</span>",
    "6-2": "**Details for customs.**  \nfields:  \n  \n- hs_tariff_number (string): Unique code that is documented in the Harmonised System (HS) for your product.  \n  It accepts only digits with lengths of 6, 8, or 10.\n- origin_country_code (string): Country code of the origin of the product.  \n  It accepts only ISO 3166-1 two digit codes.",
    "6-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired if you plan to send shipments outside of EU or UK and the data is not stored in the product. See [Creating a product](https://developers.getbyrd.com/docs/creating-a-product#fields)",
    "7-0": "<span style=\"color:SteelBlue; background:azure\"> type</span>",
    "7-1": "<span style=\"color:Teal\">string</span>",
    "7-2": "**Type of item.** It accepts `product` (default), `bundle` or `custom_bundle`  \nIf the value is `custom_bundle`, then the field `children` must be filled.",
    "7-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "8-0": "<span style=\"color:SteelBlue; background:azure\"> children</span>",
    "8-1": "<span style=\"color:Teal\">list of custom bundle item objects</span>",
    "8-2": "**Custom bundle items.** See: [Custom bundles](https://developers.getbyrd.com/docs/creating-a-shipment#custom-bundles) ",
    "8-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired if `type` is `custom_bundle`"
  },
  "cols": 4,
  "rows": 9,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\">sku </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**SKU of the product previously created in byrd.**",
    "0-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired if product_id is not sent",
    "1-0": "<span style=\"color:SteelBlue; background:azure\">product_id </span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**Id of the product previously created in byrd if sku is not sent.**",
    "1-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired if sku is not sent",
    "2-0": "<span style=\"color:SteelBlue; background:azure\">name </span>",
    "2-1": "<span style=\"color:Teal\">string</span>",
    "2-2": "**Name of the product.**",
    "2-3": "<span style=\"color:salmon\">always</span>",
    "3-0": "<span style=\"color:SteelBlue; background:azure\"> quantity </span>",
    "3-1": "<span style=\"color:Teal\">integer</span>",
    "3-2": "**Quantity of units to ship.**",
    "3-3": "<span style=\"color:salmon\">always</span>"
  },
  "cols": 4,
  "rows": 4,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> auto_release</span>",
    "0-1": "<span style=\"color:Teal\">boolean</span>",
    "0-2": "**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.**  \nIt accepts: `true`, `false`",
    "0-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> preferred_carrier</span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**If a specific carrier is preferred for this shipment.**  \nThis overrides the automatic selection by byrd and can lead to shipment errors. This field should be used with caution.  \nUse [Listing carriers](https://developers.getbyrd.com/docs/list-of-carriers) to get the list of available carriers.",
    "1-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "2-0": "<span style=\"color:SteelBlue; background:azure\">incoterm</span>",
    "2-1": "<span style=\"color:Teal\"> string</span>",
    "2-2": "**The incoterm used for the shipment and passed to the carrier.** It accepts: `DAP`, `DDP`",
    "2-3": "<span style=\"color:DarkKhaki\">optional</span>"
  },
  "cols": 4,
  "rows": 3,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> order_number </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**This field will be visible under the column _Order_ in the dashboard.**",
    "0-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> order_id</span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**Use this field for any other identifier of your orders. This field won't be visible in the dashboard.**",
    "1-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "2-0": "<span style=\"color:SteelBlue; background:azure\"> marketplace_order_number</span>",
    "2-1": "<span style=\"color:Teal\">string</span>",
    "2-2": "**The order number given by the marketplace the order was sold on**, when that is not the system sending us the shipment. For example, the Amazon order number of an Amazon order forwarded by a connected shop or aggregator.  \nReturns are labelled with this number, so sending it is what lets our warehouse match an incoming return to the shipment it came from. Keep sending `order_number` and `order_id` as before, this is an additional field.",
    "2-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "3-0": "<span style=\"color:SteelBlue; background:azure\"> marketplace</span>",
    "3-1": "<span style=\"color:Teal\">string</span>",
    "3-2": "**The marketplace that `marketplace_order_number` belongs to**, in lower case. For example: `amazon`, `ebay`, `kaufland`.  \nIf you cannot determine it reliably, send `marketplace_order_number` on its own and leave this field out rather than guessing.",
    "3-3": "<span style=\"color:DarkKhaki\">optional</span>"
  },
  "cols": 4,
  "rows": 4,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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:

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> url</span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**Url of the document. It can be an FTP or HTTP server without authentication. Document will be downloaded at the moment of printing.**",
    "0-3": "<span style=\"color:salmon\">always</span>",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> name</span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**Name of the document without spaces.**",
    "1-3": "<span style=\"color:salmon\">always</span>",
    "2-0": "<span style=\"color:SteelBlue; background:azure\">type</span>",
    "2-1": "<span style=\"color:Teal\"> string</span>",
    "2-2": "**Type of document.**  \nIt accepts: `consignment_note`, `delivery_note`, `export_document`, `proforma_invoice`, `supplement`, `other`",
    "2-3": "<span style=\"color:salmon\">always</span>",
    "3-0": "<span style=\"color:SteelBlue; background:azure\">print_copies</span>",
    "3-1": "<span style=\"color:Teal\"> integer</span>",
    "3-2": "**Number of copies to be printed.**  \nFrom `0` to `10`. It defaults to `0` (not printed) if not sent.",
    "3-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "4-0": "<span style=\"color:SteelBlue; background:azure\">format</span>",
    "4-1": "<span style=\"color:Teal\"> string</span>",
    "4-2": "**Format of the document.**  \nIt accepts: `document` (A4 paper), `label` (label printer)",
    "4-3": "<span style=\"color:DarkKhaki\">conditional</span>  \nRequired if `print_copies` is greater than `0`",
    "5-0": "<span style=\"color:SteelBlue; background:azure\">data_type</span>",
    "5-1": "<span style=\"color:Teal\"> string</span>",
    "5-2": "**File format of the document.**  \nUse `pdf` for documents you upload.",
    "5-3": "<span style=\"color:salmon\">always</span>"
  },
  "cols": 4,
  "rows": 6,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## Notes

Under `notes`, you can include an internal note.

Packaging instructions for the warehouse come from your account settings and cannot be set per shipment: `notes.packaging_instructions` is read-only, and a value sent in the request is ignored.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> customer_note </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**Note visible in the dashboard for byrd customer internal use. It is not sent to the recipient nor shown to the warehouse.**",
    "0-3": "<span style=\"color:DarkKhaki\">optional</span>"
  },
  "cols": 4,
  "rows": 1,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## Insurance

Fill the `insurance` object with the value of the shipment goods for insurance purposes.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> value </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**The value of the whole shipment for insurance purposes.**  \nIt accepts string of digits with decimals separated by a dot.",
    "0-3": "<span style=\"color:DarkKhaki\">optional</span>",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> currency </span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**Currency in ISO 3-Letter code.**",
    "1-3": "<span style=\"color:DarkKhaki\">optional</span>"
  },
  "cols": 4,
  "rows": 2,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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](https://developers.getbyrd.com/docs/creating-a-shipment#items)

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> invoice_number </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**The commercial invoice number of the order, printed on the customs documents.**",
    "0-3": "<span style=\"color:salmon\">required to release</span>  \nFor shipments that need customs documents, such as shipments leaving the EU",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> goods_type </span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**The goods type included in the shipment.**  \nIt accepts: `document`, `gift`, `sample`, `remand`, `other`  \nIt defaults to `other` if not sent.",
    "1-3": "<span style=\"color:DarkKhaki\">optional</span>"
  },
  "cols": 4,
  "rows": 2,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## Cash on delivery

For cash on delivery shipments, the `cash_on_delivery` object is required containing the object `price` including these fields:

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> value </span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**The total amount to collect from the customer.**  \nString of digits with decimals separated by a dot.",
    "0-3": "<span style=\"color:salmon\">always</span>",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> currency </span>",
    "1-1": "<span style=\"color:Teal\">string</span>",
    "1-2": "**Currency**  \nIt accepts: `EUR`",
    "1-3": "<span style=\"color:salmon\">always</span>"
  },
  "cols": 4,
  "rows": 2,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

## 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 ](https://developers.getbyrd.com/docs/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:

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "<span style=\"color:SteelBlue; background:azure\"> code</span>",
    "0-1": "<span style=\"color:Teal\">string</span>",
    "0-2": "**The unique packaging material code.**  \nThis code has to be asked to Support once the new packaging material was validated by the warehouse.",
    "0-3": "<span style=\"color:salmon\">always</span>",
    "1-0": "<span style=\"color:SteelBlue; background:azure\"> quantity</span>",
    "1-1": "<span style=\"color:Teal\">integer</span>",
    "1-2": "**Quantity**",
    "1-3": "<span style=\"color:salmon\">always</span>",
    "2-0": "<span style=\"color:SteelBlue; background:azure\"> required</span>",
    "2-1": "<span style=\"color:Teal\">boolean</span>",
    "2-2": "**If packaging material is required or suggested**  \nIt accepts: `true`, `false`.  \nIt defaults to `true` if not sent.",
    "2-3": "<span style=\"color:DarkKhaki\">optional</span>"
  },
  "cols": 4,
  "rows": 3,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

#

#

## Request body example

```json [POST] JSON Request body
{
    "destination_address": {
        "name": "William Byrd",
        "company_name": "",
        "email": "email@domain.com",
        "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",
        "marketplace_order_number": "123-4567890-1234567",
        "marketplace": "amazon"
    },
    "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"
    },
    "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

```json 201 Response
{
    "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
        },
        "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@domain.com",
            "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,
            "create_return_label": false,
            "print_return_label": false,
            "auto_release": true,
            "not_later_date": null,
            "charge": true,
            "packaging": false,
            "partial_fulfillment": false,
            "pickup_date": null,
            "preferred_carrier": "DHL",
            "has_dangerous_goods": false,
            "custom_handling": 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",
            "marketplace_order_number": "123-4567890-1234567",
            "marketplace": "amazon",
            "id": null,
            "type": null
        },
        "cash_on_delivery": {
            "price": {
                "value": 20.0,
                "currency": "EUR"
            }
        },
        "sub_status": "validating_address",
        "notes": {
            "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,
            "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
    }
}
```