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

Field	Type	Description	Required
name	string	Name of the recipient. Also needed when the recipient is a company, for example the contact person.	required to release
company_name	string	Company name if recipient is a company.	optional
email	string	Recipient email.	conditional Required to release shipments from a Spanish warehouse to Spain
street_name	string	Name of the street. Please send the number of the street in the field street_number if possible.	required to release
street_number	string	Number of the street.	conditional Required for DHL Packstation and Postfiliale deliveries, where it is the Packstation or Postfiliale number
address_addition	string	Rest of address details like building or floor.	optional
city	string	Recipient city.	required to release
postal_code	string	Recipient postal code.	required to release Except for destinations without postal codes: `AE`, `HK`, `LB`, `QA`
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)	conditional Required to release pickup point shipments and cash on delivery shipments to Italy

Items

Under items, you need to specify the items that have to be included in the 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 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. - 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 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
marketplace_order_number	string	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. Returns 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.	optional
marketplace	string	The marketplace that `marketplace_order_number` belongs to, in lower case. For example: `amazon`, `ebay`, `kaufland`. If you cannot determine it reliably, send `marketplace_order_number` on its own and leave this field out rather than guessing.	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. From `0` to `10`. It defaults to `0` (not printed) if not sent.	optional
format	string	Format of the document. It accepts: `document` (A4 paper), `label` (label printer)	conditional Required if `print_copies` is greater than `0`
data_type	string	File format of the document. Use `pdf` for documents you upload.	always

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.

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

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, printed on the customs documents.	required to release For shipments that need customs documents, such as shipments leaving the EU
goods_type	string	The goods type included in the shipment. It accepts: `document`, `gift`, `sample`, `remand`, `other` It defaults to `other` 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": "910121",
        "origin_country_code": "CN"
      }
    }
  ],
  "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/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"
  }
}

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,
            "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
        },
        "warnings": [],
        "units": [],
        "container_code": null,
        "options": {
            "has_dangerous_goods": false,
            "preferred_carrier": "DHL",
            "partial_fulfillment": false,
            "charge": true,
            "packaging": true,
            "custom_handling": false,
            "not_later_date": null,
            "international": null,
            "pickup_date": null,
            "v3_packaging": false,
            "auto_release": true,
            "fragile": false,
            "branding": false,
            "incoterm": "DAP",
            "create_return_label": false,
            "print_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",
            "marketplace_order_number": null,
            "marketplace": null,
            "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.