Shipment

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/byrd/main/json-schema/byrd-shipment-schema.json",
  "title": "Shipment",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/byrd-apis-openapi.yml#/components/schemas/Shipment",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "readOnly": true,
      "description": "ID of the shipment (UUID)."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "When the record was created (ISO 8601)."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "When the record was last changed (ISO 8601)."
    },
    "b2b_config": {
      "readOnly": true,
      "description": "B2B configuration of the shipment: the B2B template it uses and your answers to it; `null` for B2C shipments.",
      "allOf": [
        {
          "$ref": "#/$defs/B2BConfig"
        }
      ]
    },
    "checkpoints": {
      "readOnly": true,
      "description": "Timestamps (ISO 8601, UTC) of the milestones the shipment has reached; a milestone not reached yet is `null`.",
      "allOf": [
        {
          "$ref": "#/$defs/Checkpoints"
        }
      ]
    },
    "container_code": {
      "type": "string",
      "description": "Code of the warehouse container the picked items are kept in until the shipment is packed."
    },
    "customs": {
      "description": "Customs details used to generate the export documents; required for international shipments. `null` when none were provided.",
      "allOf": [
        {
          "$ref": "#/$defs/Customs"
        }
      ]
    },
    "destination_address": {
      "description": "Address and contact details of the recipient. For deliveries to a carrier pickup point, see the pickup point guides for how to fill it.",
      "allOf": [
        {
          "$ref": "#/$defs/ShipmentDestinationAddress"
        }
      ]
    },
    "errors": {
      "readOnly": true,
      "description": "Errors blocking the shipment from progressing, for example a failed address validation or an allocation problem; empty when nothing is blocking it.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/ShipmentUnitDetailError"
      }
    },
    "insurance": {
      "description": "Declared value the shipment is insured for; `null` when the shipment is not insured.",
      "allOf": [
        {
          "$ref": "#/$defs/Insurance"
        }
      ]
    },
    "metrics": {
      "readOnly": true,
      "description": "Item, SKU, pick and packaging-unit counts for the shipment.",
      "allOf": [
        {
          "$ref": "#/$defs/Metrics"
        }
      ]
    },
    "notes": {
      "description": "Free-text notes for your own use and packaging instructions for the warehouse.",
      "allOf": [
        {
          "$ref": "#/$defs/Notes"
        }
      ]
    },
    "options": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "branding": {
          "type": [
            "boolean",
            "null"
          ],
          "default": null,
          "description": "Whether the shipment is packed with your branded packaging material; defaults to your account setting."
        },
        "packaging": {
          "type": [
            "boolean",
            "null"
          ],
          "default": null,
          "description": "Whether the warehouse packs the items in packaging material; defaults to your account setting."
        },
        "custom_handling": {
          "type": [
            "boolean",
            "null"
          ],
          "default": false,
          "description": "Whether the shipment is held for custom handling at the warehouse; it cannot be packed while this is `true`. Read-only for you."
        },
        "auto_release": {
          "type": [
            "boolean",
            "null"
          ],
          "default": null,
          "description": "Whether the shipment is released to a warehouse automatically once it is created; if `false` or not sent, it normally stays `new` until you release it."
        },
        "preferred_carrier": {
          "type": [
            "string",
            "null"
          ],
          "default": null,
          "description": "Carrier to send the shipment with, instead of the one byrd selects; see the list of carriers. Use it with caution, as a carrier that cannot serve the shipment leads to shipment errors."
        },
        "incoterm": {
          "type": [
            "string",
            "null"
          ],
          "default": null,
          "description": "Incoterm passed to the carrier for international shipments.\n\n- `DAP`: delivered at place; the recipient pays import duties and taxes (default)\n- `DDP`: delivered duty paid; you pay them"
        },
        "charge": {
          "type": "string",
          "readOnly": true,
          "description": "Whether byrd charges you for the shipment."
        },
        "fragile": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the shipment contains at least one fragile product."
        },
        "organic": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the shipment contains at least one organic product."
        },
        "grs": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the shipment contains at least one product that complies with the Global Recycled Standard (GRS)."
        },
        "create_return_label": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether a return label is created for each parcel when the shipment is released; send it together with `print_return_label`."
        },
        "print_return_label": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the return label is printed and packed with the shipment; requires `create_return_label` to be `true`, and has to be sent together with it."
        },
        "economy_fallback": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the shipment is sent with the `standard` service when `economy` is not available for it; set on your account."
        },
        "not_before_date": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "Earliest date the shipment may be sent (ISO 8601, at midnight); `null` when there is no such date."
        },
        "not_later_date": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "Latest date and time the shipment has to be sent by (ISO 8601); `null` when not set."
        },
        "pickup_date": {
          "type": "string",
          "format": "date",
          "readOnly": true,
          "description": "Date the carrier collects the shipment (ISO 8601), for B2B shipments; `null` when not scheduled."
        },
        "international": {
          "type": [
            "boolean",
            "null"
          ],
          "default": null,
          "description": "Whether the shipment needs a customs declaration because it crosses a customs border; `null` until the shipment is released."
        },
        "has_dangerous_goods": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the shipment contains at least one item classified as dangerous goods."
        },
        "v3_packaging": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the warehouse packs the shipment with the v3 packing process."
        },
        "requires_export_declaration": {
          "type": "string",
          "readOnly": true,
          "description": "Whether the shipment has to carry an export declaration; always `false` before the shipment is released."
        },
        "slam_compatible": {
          "type": "string",
          "readOnly": true,
          "description": "Whether the warehouse can pack the shipment on its automated labelling line; `null` until the shipment is released."
        },
        "autobag_compatible": {
          "type": "string",
          "readOnly": true,
          "description": "Whether the warehouse can pack the shipment with its automatic bagging machine."
        },
        "partial_fulfillment": {
          "type": "string",
          "readOnly": true,
          "description": "Whether the shipment was split off so that part of an order could be sent while the rest waits."
        },
        "expired_stock_allowed": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether the shipment may be fulfilled with expired stock; defaults to `false`."
        },
        "pickup_date_from": {
          "type": "string",
          "format": "date",
          "readOnly": true,
          "description": "First day of the window in which the shipment will be collected (ISO 8601), for B2B shipments; set with the schedule pickup endpoint."
        },
        "pickup_date_to": {
          "type": "string",
          "format": "date",
          "readOnly": true,
          "description": "Last day of the window in which the shipment will be collected (ISO 8601), for B2B shipments; set with the schedule pickup endpoint."
        },
        "self_pickup_by_customer": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether you collect the shipment from the warehouse yourself instead of a carrier, for B2B shipments; set with the schedule pickup endpoint."
        },
        "shipping_label_mode": {
          "type": "string",
          "readOnly": true,
          "description": "How the shipping label is obtained.\n\n- `auto`: byrd creates it with the carrier\n- `manual`: byrd uploads it, for example for `pickup` shipments"
        }
      },
      "description": "Fulfilment and shipping options set on the shipment."
    },
    "origin": {
      "type": "string",
      "readOnly": true,
      "description": "How the shipment was created; `null` for shipments created before this was recorded.\n\n- `api`: through the API with an API key\n- `manual`: in the byrd dashboard\n- `integration`: by a byrd shop integration"
    },
    "byrd_id": {
      "type": "string",
      "readOnly": true,
      "description": "Short human-readable identifier of the shipment, shown in the dashboard and printed on warehouse documents."
    },
    "priority": {
      "type": "integer",
      "readOnly": true,
      "description": "Picking priority in the warehouse, from 0 (normal) to 40 (highest); rises automatically once the shipping deadline is reached. `null` until the shipment is released."
    },
    "return_address": {
      "readOnly": true,
      "description": "Address of the fulfilling warehouse that returns are sent to; `null` until the shipment is released.",
      "allOf": [
        {
          "$ref": "#/$defs/ReturnAddress"
        }
      ]
    },
    "service": {
      "type": "string",
      "enum": [
        "economy",
        "standard",
        "express",
        "pickup",
        "pickup_point"
      ],
      "description": "Shipping service the shipment is sent with.\n\n- `standard`: regular delivery\n- `express`: faster delivery, picked with higher priority\n- `economy`: cheapest, slower delivery\n- `pickup_point`: delivery to a carrier pickup point\n- `pickup`: collected from the warehouse, not shipped"
    },
    "shop": {
      "description": "Order references from your shop or order system, such as the order number.",
      "allOf": [
        {
          "$ref": "#/$defs/ShipmentShop"
        }
      ]
    },
    "status": {
      "type": "string",
      "readOnly": true,
      "description": "Current status of the shipment.\n\n- `new`: created and not yet released to a warehouse\n- `releasing`: being released to a warehouse\n- `released`: released and waiting to be picked\n- `picking`: items are being picked\n- `packaging`: being packed\n- `packaged`: packed and labelled\n- `sent`: handed over to the carrier\n- `delivered`: delivered to the recipient\n- `returning`: a return shipment was created\n- `returned`: the return arrived at the warehouse\n- `deleted`: deleted"
    },
    "sub_status": {
      "type": "string",
      "readOnly": true,
      "description": "Detail on the current `status`; `null` when there is none.\n\n- `validating_address`, `address_invalid`, `recalled`: while `new`\n- `reserved`, `allocating`, `allocated`, `assigned`, `inbounding`, `inbound_error`: while `released`\n- `label_error`, `error_resolved`, `autobag_failed`: while `packaging`\n- `label_required`, `label_created`, `label_uploaded`, `pickup_details_required`, `pickup_details_uploaded`, `manual_outbound`, `waiting_for_pickup`, `fba_details_required`, `fba_box_label_required`, `fba_pallet_label_required`: while `packaged`, mostly for B2B shipments\n- `pick_up`, `in_transit`, `at_pickup_point`, `out_for_delivery`, `delayed`, `failed_delivery`: carrier tracking events while `sent`\n- `claim_reported`: a support claim is open, while `sent` or `delivered`"
    },
    "units": {
      "readOnly": true,
      "description": "Physical parcels or pallets the shipment is packed into, each with its own tracking information.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/ShipmentUnitDetail"
      }
    },
    "warnings": {
      "readOnly": true,
      "description": "Problems that do not block the shipment, for example an address validation error on a shipment released anyway, or the reason it was recalled.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/ShipmentUnitDetailError"
      }
    },
    "warehouse": {
      "readOnly": true,
      "description": "Warehouse fulfilling the shipment; its fields are `null` until a warehouse is assigned.",
      "allOf": [
        {
          "$ref": "#/$defs/ShipmentWarehouse"
        }
      ]
    },
    "user": {
      "readOnly": true,
      "description": "byrd account the shipment belongs to.",
      "allOf": [
        {
          "$ref": "#/$defs/ShipmentUser"
        }
      ]
    },
    "dangerous_goods": {
      "readOnly": true,
      "description": "Dangerous goods totals for the shipment.",
      "allOf": [
        {
          "$ref": "#/$defs/DGDetails"
        }
      ]
    },
    "cash_on_delivery": {
      "description": "Amount the carrier collects from the recipient on delivery; `null` when the shipment is not cash on delivery.",
      "allOf": [
        {
          "$ref": "#/$defs/CashOnDelivery"
        }
      ]
    },
    "total_value": {
      "readOnly": true,
      "description": "Total value of the items (unit price × quantity), converted to EUR.",
      "allOf": [
        {
          "$ref": "#/$defs/CashOnDeliveryPrice"
        }
      ]
    },
    "packaging_materials": {
      "description": "Packaging materials requested or suggested for packing the shipment.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/PackagingMaterials"
      }
    },
    "user_id": {
      "type": "string",
      "format": "uuid",
      "writeOnly": true,
      "description": "ID of the byrd account the shipment is created for (UUID); for your requests it is always your own account."
    },
    "documents": {
      "writeOnly": true,
      "description": "Documents the warehouse prints and packs with the shipment, such as delivery notes or invoices.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Document"
      }
    },
    "warehouse_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "writeOnly": true,
      "description": "ID of the warehouse that has to fulfil the shipment; if omitted, byrd assigns one automatically."
    },
    "warehouse_user_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "writeOnly": true,
      "description": "ID of the warehouse worker assigned to pick the shipment."
    },
    "pickup_point": {
      "type": [
        "object",
        "null"
      ],
      "default": null,
      "writeOnly": true,
      "description": "Carrier pickup point to deliver to, for `pickup_point` shipments; the fields it needs depend on the carrier.",
      "additionalProperties": {}
    },
    "items": {
      "description": "Products in the shipment and their quantities; at least one.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Item"
      }
    }
  },
  "required": [
    "destination_address",
    "items"
  ],
  "$defs": {
    "B2BConfig": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "ID of the B2B configuration (UUID)."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "When the record was created (ISO 8601)."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "When the record was last changed (ISO 8601)."
        },
        "template_key": {
          "type": "string",
          "readOnly": true,
          "description": "Key of the B2B template (processing standard) the shipment uses."
        },
        "exchanged_pallets": {
          "type": "integer",
          "readOnly": true,
          "description": "Number of pallets exchanged with the carrier at pickup."
        },
        "template_id": {
          "type": "string",
          "format": "uuid",
          "description": "ID of the B2B template to use (UUID); see the list of B2B config templates."
        },
        "customer_input": {
          "type": "string",
          "description": "Your values for the fields the B2B template asks for, in the structure given by its `customerInputSchema`."
        },
        "is_pallet": {
          "type": "boolean",
          "description": "Whether the shipment is sent on pallets (`true`) or as parcels (`false`); defaults to `false`."
        }
      },
      "required": [
        "customer_input",
        "template_id"
      ],
      "title": "B2B config"
    },
    "Carrier": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "tracking_number": {
          "type": "string"
        },
        "tracking_url": {
          "type": "string"
        },
        "is_tracked": {
          "type": "boolean"
        },
        "shipment_id": {
          "type": "string"
        },
        "shipping_rate": {
          "$ref": "#/$defs/CarrierShippingRate"
        },
        "byrd_shipping_rate": {
          "$ref": "#/$defs/CarrierShippingRate"
        },
        "fuel_surcharge_rate": {
          "$ref": "#/$defs/FuelSurcharge"
        },
        "peak_surcharge_rate": {
          "$ref": "#/$defs/PeakSurcharge"
        },
        "decarbonization_surcharge_rate": {
          "$ref": "#/$defs/DecarbonizationSurcharge"
        },
        "pddp_surcharge_rate": {
          "$ref": "#/$defs/PddpSurcharge"
        },
        "remote_area_surcharge_rate": {
          "$ref": "#/$defs/RemoteAreaSurcharge"
        },
        "island_surcharge_rate": {
          "$ref": "#/$defs/IslandSurcharge"
        },
        "sub_carrier_name": {
          "type": "string"
        },
        "sub_carrier_tracking_number": {
          "type": "string"
        },
        "sub_carrier_tracking_url": {
          "type": "string"
        },
        "sub_carrier_shipment_id": {
          "type": "string"
        }
      },
      "title": "Carrier"
    },
    "CarrierShippingRate": {
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "description": "Amount in `currency`, with a dot as decimal separator."
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "Currency of `value` (ISO 4217), for example `EUR`."
        },
        "tax_factor": {
          "type": [
            "number",
            "null"
          ],
          "description": "Tax factor of the price; `1.0` on item prices and `null` elsewhere. Ignored on input."
        }
      },
      "required": [
        "currency",
        "value"
      ],
      "title": "Carrier shipping rate"
    },
    "CashOnDelivery": {
      "type": "object",
      "properties": {
        "price": {
          "description": "Total amount the carrier collects from the recipient; only `EUR` is supported.",
          "allOf": [
            {
              "$ref": "#/$defs/CashOnDeliveryPrice"
            }
          ]
        }
      },
      "title": "Cash on delivery"
    },
    "CashOnDeliveryPrice": {
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "description": "Amount in `currency`, with a dot as decimal separator."
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "Currency of `value` (ISO 4217), for example `EUR`."
        },
        "tax_factor": {
          "type": [
            "number",
            "null"
          ],
          "description": "Tax factor of the price; `1.0` on item prices and `null` elsewhere. Ignored on input."
        }
      },
      "required": [
        "currency",
        "value"
      ],
      "title": "Cash on delivery price"
    },
    "Checkpoints": {
      "type": "object",
      "properties": {
        "release_error_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the last attempt to release the shipment failed (ISO 8601, UTC); `null` if releasing never failed."
        },
        "released_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the shipment was released to the warehouse (ISO 8601, UTC)."
        },
        "picked_at": {
          "type": "string",
          "format": "date-time",
          "description": "When picking of the shipment's items was completed (ISO 8601, UTC)."
        },
        "assigned_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the shipment was assigned to a warehouse worker for picking (ISO 8601, UTC)."
        },
        "allocated_at": {
          "type": "string",
          "format": "date-time",
          "description": "When stock was allocated to the shipment for picking (ISO 8601, UTC)."
        },
        "packaging_started_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the warehouse started packing the shipment (ISO 8601, UTC)."
        },
        "packaged_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the shipment was packed and labelled (ISO 8601, UTC)."
        },
        "accepted_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the carrier first scanned the last of the shipment's units (ISO 8601, UTC); `null` until every unit was scanned."
        },
        "sent_at": {
          "type": "string",
          "format": "date-time",
          "description": "When all of the shipment's units left the warehouse (ISO 8601, UTC)."
        },
        "delivered_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the last of the shipment's units was delivered to the recipient (ISO 8601, UTC)."
        },
        "returned_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the return of the shipment arrived at the warehouse (ISO 8601, UTC)."
        }
      },
      "title": "Checkpoints"
    },
    "Customs": {
      "type": "object",
      "properties": {
        "invoice_number": {
          "type": "string",
          "description": "Commercial invoice number of the order, printed on the customs documents."
        },
        "goods_type": {
          "type": "string",
          "description": "Type of goods in the shipment, declared to customs; defaults to `other`.\n\n- `document`: documents only\n- `gift`: a gift\n- `sample`: commercial samples\n- `remand`: goods sent back\n- `other`: anything else, such as sold goods"
        },
        "export_mrn": {
          "type": [
            "string",
            "null"
          ],
          "description": "Movement Reference Number (MRN) of the export declaration filed for the shipment, passed to the carrier; up to 18 characters."
        },
        "has_electronic_export_notification": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether an electronic export declaration was filed for the shipment; passed to the carrier."
        }
      },
      "title": "Customs"
    },
    "DGDetails": {
      "type": "object",
      "properties": {
        "limited_quantity_weight": {
          "type": "number",
          "readOnly": true,
          "description": "The total weight of the dangerous goods of type limited quantity (LQ)."
        }
      },
      "title": "DG details"
    },
    "DecarbonizationSurcharge": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$"
        },
        "tax_factor": {
          "type": [
            "number",
            "null"
          ]
        },
        "actual_carrier": {
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "type": "string",
          "readOnly": true
        }
      },
      "title": "Decarbonization surcharge"
    },
    "Dimensions": {
      "type": "object",
      "properties": {
        "height": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0.1,
          "description": "Height in cm; `null` when unknown."
        },
        "width": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0.1,
          "description": "Width in cm; `null` when unknown."
        },
        "length": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0.1,
          "description": "Length in cm; `null` when unknown."
        },
        "weight": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0.001,
          "description": "Weight in kg; `null` when unknown."
        }
      },
      "title": "Dimensions"
    },
    "Document": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "ID of the document (UUID). Send it to change an existing document; leave it out to add a new one."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "When the record was created (ISO 8601)."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "When the record was last changed (ISO 8601)."
        },
        "data_type": {
          "type": "string",
          "description": "File format of the document: `pdf`, `pdfb64` (base64-encoded PDF), `pdfurl`, `zpl`, `epl` or `jpeg`. Required for a new document; use `pdf` for documents you upload."
        },
        "print_copies": {
          "type": "integer",
          "description": "Number of copies the warehouse prints automatically and packs with the shipment, from 0 to 10; defaults to 0 (not printed)."
        },
        "format": {
          "type": "string",
          "description": "Printer the document is printed on: `document` (A4 paper) or `label` (label printer). Required when `print_copies` is greater than 0."
        },
        "internal": {
          "type": "boolean",
          "readOnly": true,
          "description": "Whether byrd generated the document (`true`) or it was uploaded (`false`)."
        },
        "last_printed_at": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "When the document was last printed (ISO 8601); `null` if it has not been printed."
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "format": "url",
          "writeOnly": true,
          "description": "URL the document is downloaded from when it is printed, on an HTTP or FTP server without authentication. Required for a new document."
        },
        "name": {
          "type": "string",
          "minLength": 4,
          "maxLength": 64,
          "pattern": "^[a-zA-Z0-9_\\-]*$",
          "description": "Name of the document: 4 to 64 characters, only letters, digits, `_` and `-` (no spaces)."
        },
        "meta": {
          "type": "object",
          "description": "Additional data about the document, such as the carrier, tracking number and tracking URL of a shipping or return label; the keys depend on `type`.",
          "additionalProperties": {}
        },
        "type": {
          "description": "Type of document. Documents you upload to be printed use `consignment_note`, `delivery_note`, `export_document`, `proforma_invoice`, `supplement` or `other`; documents byrd creates use other types, such as `shipping_label`, `return_label`, `commercial_invoice` or `customs_cn23`.",
          "type": "string",
          "enum": [
            "amazon_fba",
            "amazon_fba_box_label",
            "amazon_fba_pallet_label",
            "batch_packaging_summary",
            "customs_cn22",
            "customs_cn23",
            "commercial_invoice",
            "consignment_note",
            "delivery_note",
            "dhl_export_declaration_label",
            "export_document",
            "generic_large_label",
            "other",
            "pickup_confirmation",
            "pickup_confirmation_template",
            "proforma_invoice",
            "proof_of_delivery",
            "return_label",
            "shipping_label",
            "sku_relabelling",
            "supplement",
            "byrd_label",
            "sequence_number_label",
            "return_slip"
          ]
        },
        "unit_id": {
          "type": "string",
          "description": "ID of the unit (parcel) the document belongs to (UUID); `null` for documents that belong to the whole shipment."
        }
      },
      "required": [
        "name",
        "type"
      ],
      "title": "Document"
    },
    "FuelSurcharge": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$"
        },
        "tax_factor": {
          "type": [
            "number",
            "null"
          ]
        },
        "actual_carrier": {
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "type": "string",
          "readOnly": true
        }
      },
      "title": "Fuel surcharge"
    },
    "Insurance": {
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "description": "Value of the whole shipment it is insured for, in `currency`."
        },
        "currency": {
          "type": "string",
          "description": "Currency of `value` (ISO 4217), for example `EUR`."
        }
      },
      "title": "Insurance"
    },
    "IslandSurcharge": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$"
        },
        "tax_factor": {
          "type": [
            "number",
            "null"
          ]
        },
        "actual_carrier": {
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "type": "string",
          "readOnly": true
        }
      },
      "title": "Island surcharge"
    },
    "Item": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/byrd/refs/heads/main/json-schema/byrd-shipment-schema.json