GuidesAPI ReferenceChangelog
Guides

Updating a shipment

API reference ShipmentAPIV3

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:

FieldTypeDescriptionRequired
destination_address address objectThe destination address details.
See: Destination details		always
items list of item objectsThe items to be included in the shipment and their quantity.
See: Items		always
service stringShipment 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_idstringId of the warehouse that has to fulfill the shipment.
If not sent, the warehouse is automatically assigned.
See: Listing warehouses		optional
options options objectOptions for the shipment.
See: Options		optional
shopshop objectFields to add custom details from your order system.
See: Shop		optional
documents list documents objectsDocuments for the shipment.
See: Documents		optional
notesnotes objectNotes for the shipment.
See: Notes		optional
insurance insurance objectInsurance details for the shipment.
See: Insurance		optional
customscustoms objectDetails 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.

FieldTypeDescriptionRequired
name stringName of the recipient if recipient is an individual.always
company_namestringCompany name if recipient is a company.always if not individual
email stringRecipient email.optional
street_name stringName of the street.
Please send the number of the street in the field street_number if possible.		always
street_numberstringNumber of the street.always
address_additionstringRest of address details like building or floor.optional
citystringRecipient city.always
postal_code stringRecipient postal code.always
country_code stringCountry code of the recipient.
It accepts only ISO 3166-1 two digit codes.		always
phonestringRecipient 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.

FieldTypeDescriptionRequired
sku stringSKU of the product previously created in byrd.conditional
Required if product_id is not sent
product_id stringId of the product previously created in byrd if sku is not sent.conditional
Required if sku is not sent
name stringName of the product.optional
quantity integerQuantity of units to ship.always
lot_number stringLot from where to pick the product.optional
price price objectPrice 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
customscustoms objectDetails 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.

FieldTypeDescriptionRequired
auto_releasebooleanIf 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_carrierstringIf 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 stringThe 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.

FieldTypeDescriptionRequired
order_number stringThis field will be visible under the column Order in the dashboard.optional
order_idstringUse 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:

FieldTypeDescriptionRequired
urlstringUrl of the document. It can be an FTP or HTTP server without authentication. Document will be downloaded at the moment of printing.always
namestringName of the document without spaces.always
type stringType of document.
It accepts: consignment_note, delivery_note, export_document, proforma_invoice, supplement, other		always
print_copies integerNumber of copies to be printed.always
format stringFormat of the document.
It accepts: document		always
data_type stringType of document.
It accepts: pdf		always

Notes

Under notes, you can include some internal notes and packaging instructions .

FieldTypeDescriptionRequired
customer_note stringNote visible in the dashboard for byrd customer internal use. It is not sent to the recipient nor shown to the warehouse..optional
packaging_instructions stringPackaging instructions to the warehouse.optional

Insurance

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

FieldTypeDescriptionRequired
value stringThe value of the whole shipment for insurance purposes.
It accepts string of digits with decimals separated by a dot.		optional
currency stringCurrency 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

FieldTypeDescriptionRequired
invoice_number stringThe commercial invoice number of the order.always
goods_type stringThe 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.

Updated about 1 year ago