Updating a shipment

Overview

This endpoint can be used to update the details of a shipment. Shipment items and method can be updated before the shipment is released. The destination address can be updated before the shipment is packaged

Method access
      PATCH https://api.getbyrd.com/v3/shipments/<shipment_id>
Request Headers
      Authorization: Bearer token-from >Authentication
      Content-Type: application/json
      User-Agent: your user-agent >How to call the APIs

Fields

The fields are the same as in the shipment creation call:

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` Use Listing carriers to get the available methods for your preferred carrier.	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 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 and invoice number for customs. See: Customs	conditional Required for international shipments and the data is not stored in the product. See Creating a product

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
email	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
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

Items

Under items, you need to specify the items that has to be included in the shipment. If there is not 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 from where to pick the product.	optional
price	price object	Price used for customs documents and shipment insurance. fields: value (string): string of digits with decimals separated by a dot. currency (string): currency in ISO 3-Letter code. Retail price should be provided here.	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. Is a if you plan to send.. 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

Options

Under options you can specify if the shipment has to 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 has to 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.	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 columnOrder 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

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": "910121",
        "origin_country_code": "CN"
      }
    }
  ],
  "service": "economy",
  "options": {
    "auto_release": true,
    "preferred_carrier": "DHL",
    "incoterm": "ABC"
  },
  "shop": {
    "order_number": "OW-18940",
    "order_id": "123456"
  },
  "documents": [
    {
      "type": "delivery_note",
      "url": "https://urltodocument/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"
  }
}

Successful response example

{
    "data": {
        "b2b_config": null,
        "errors": [],
        "metrics": {
            "total_packaging_units": 0,
            "total_picks": 0,
            "total_skus": 0,
            "total_items": 2
        },
        "notes": {
            "label_error_note": null,
            "packaging_instructions": null,
            "customer_note": "This is an internal note"
        },
        "items": [
            {
                "name": "Dog food",
                "type": "product",
                "dangerous_goods": null,
                "children": [],
                "price": {
                    "value": 20.00,
                    "currency": "EUR",
                    "tax_factor": 1.0
                },
                "product_id": null,
                "description": null,
                "dimensions": {
                    "height": null,
                    "length": null,
                    "weight": null,
                    "width": null
                },
                "quantity": 2,
                "customs": {
                    "hs_tariff_number": "910121",
                    "origin_country_code": "CN"
                },
                "created_at": "2023-03-23T11:47:56.077055+00:00",
                "sku": "AB-1234",
                "fragile": false,
                "updated_at": "2023-03-23T11:47:56.077061+00:00",
                "serial_number_tracked": false,
                "id": "the_item_line_id",
                "lot_number": "2/23"
            }
        ],
        "destination_address": {
            "name": "William Byrd",
            "email": "[email protected]",
            "street_number": "15",
            "postal_code": "458ABC",
            "city": "City",
            "street_name": "The name of the street",
            "created_at": "2023-03-23T11:47:56.068145+00:00",
            "phone": "+421111111111",
            "company_name": "",
            "address_addition": "1st floor",
            "updated_at": "2023-03-23T11:47:56.068152+00:00",
            "country_code": "DE",
            "id": "the_address_id",
            "validated": false,
            "state": null
        },
        "return_address": null,
        "dangerous_goods": {
            "limited_quantity_weight": 0.0
        },
        "warehouse": {
            "id": null,
            "picked_by": null
        },
        "warnings": [],
        "units": [],
        "container_code": null,
        "options": {
            "has_dangerous_goods": false,
            "preferred_carrier": "DHL",
            "partial_fulfillment": false,
            "charge": true,
            "skip_barcode": true,
            "custom_handled": false,
            "packaging": true,
            "custom_handling": false,
            "not_later_date": null,
            "international": null,
            "pickup_date": null,
            "v3_packaging": false,
            "auto_release": true,
            "direct_complete": true,
            "fragile": false,
            "remunerate": true,
            "branding": false,
            "incoterm": "ABC",
            "return_label": false
        },
        "insurance": {
            "value": 20.45,
            "currency": "EUR"
        },
        "cash_on_delivery": null,
        "customs": {
            "goods_type": "other",
            "invoice_number": "2023-12894091"
        },
        "created_at": "2023-03-23T11:47:56.070212+00:00",
        "byrd_id": "HXB2ZDF9NP",
        "checkpoints": {
            "returned_at": null,
            "accepted_at": null,
            "packaged_at": null,
            "sent_at": null,
            "released_at": null,
            "delivered_at": null
        },
        "shop": {
            "order_id": "123456",
            "type": null,
            "order_number": "OW-18940",
            "id": null
        },
        "updated_at": "2023-03-23T11:47:56.070217+00:00",
        "sub_status": null,
        "id": "the_shipment_id",
        "priority": null,
        "status": "releasing",
        "service": "economy"
    }
}

❗️
Data which is always required
The destination_address, items, and documents contents must always be complete (i.e., for lists, new items will replace existing, missing will be deleted). Partial updates inside sections is not supported.