{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/byrd/main/json-schema/byrd-delivery-with-metrics-schema.json", "title": "Delivery with metrics", "x-generated": "2026-10-14", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/byrd-apis-openapi.yml#/components/schemas/DeliveryWithMetrics", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (UUID)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was last changed (ISO 8601)." }, "customsMRN": { "type": [ "string", "null" ], "pattern": "^[0-9]{2}GB[A-Z0-9]{14}\\Z", "description": "UK customs Movement Reference Number (MRN) of the goods: 18 characters, two digits for the year, `GB`, then 14 uppercase letters or digits. Only allowed for deliveries to a warehouse in the United Kingdom; you can set it while the delivery is `announced` or `atWarehouse`, including with a partial update after arrival. `null` when not provided." }, "description": { "type": [ "string", "null" ], "description": "Free-text summary of the contents of the delivery; `null` when not provided." }, "expectedDeliveryDateFrom": { "type": "string", "format": "date-time", "description": "Start of the window in which the delivery is expected to arrive at the warehouse (ISO 8601, UTC). For `container` deliveries it must equal `expectedDeliveryDateTo`. Customers can only change it while the delivery is `announced`." }, "expectedDeliveryDateTo": { "type": "string", "format": "date-time", "description": "End of the window in which the delivery is expected to arrive at the warehouse (ISO 8601, UTC). For `container` deliveries it must be a business day at least 10 business days from now. Customers can only change it while the delivery is `announced`." }, "expressInbounding": { "type": "boolean", "description": "Whether express inbounding is requested. Always send `false`." }, "isInternational": { "type": [ "boolean", "null" ], "description": "Whether the goods cross a border into the warehouse's country. Only for deliveries to a warehouse in the United Kingdom, where it is required when announcing or fully updating the delivery. When `true`, `senderName` and `senderAddress` are required and the warehouse cannot inbound the delivery until `customsMRN` is provided. Customers can still declare it `true` with a partial update after the delivery has left `announced`, but not change it back once the goods have arrived. `null` when it does not apply." }, "referenceNumber": { "type": [ "string", "null" ], "description": "Your own reference for the delivery, such as a purchase order number; `null` when not provided." }, "requiresCounting": { "type": [ "boolean", "null" ], "description": "Whether the warehouse counts every item on arrival; charges may apply. When `false`, stock is booked as announced and byrd is not liable for discrepancies. Defaults to `true`; cannot be `true` together with `requiresSampling`. Customers can only change it while the delivery is `announced`." }, "requiresSampling": { "type": [ "boolean", "null" ], "description": "Whether the warehouse checks a representative sample of the goods on arrival instead of counting every item. Defaults to `false`; cannot be `true` together with `requiresCounting`. Customers can only change it while the delivery is `announced`." }, "senderAddress": { "type": [ "string", "null" ], "description": "Address the delivery is sent from; required for international deliveries, otherwise `null` when not provided. Part of the customs declaration, so customers can still change it with a partial update after the delivery has left `announced`." }, "senderName": { "type": [ "string", "null" ], "description": "Name of the sender of the delivery; required for international deliveries, otherwise `null` when not provided. Part of the customs declaration, so customers can still change it with a partial update after the delivery has left `announced`." }, "stocktaking": { "type": "boolean", "description": "Always send `true`." }, "unmixedDelivery": { "type": [ "boolean", "null" ] }, "containerSizeAnnounced": { "type": [ "string", "null" ], "enum": [ "20ft", "40ft", null ], "description": "Size of the shipping container, as you announced it. Only for `container` deliveries; `null` otherwise.\n\n- `20ft`: 20-foot container\n- `40ft`: 40-foot container" }, "isPalletizedAnnounced": { "type": [ "boolean", "null" ], "description": "Whether the goods in the shipping container are on pallets, as you announced it. Only for `container` deliveries; `null` otherwise." }, "deletedDate": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the delivery was cancelled (ISO 8601, UTC); `null` when it was not." }, "identifier": { "type": "string", "readOnly": true, "description": "Short human-readable identifier of the delivery, shown in the dashboard and printed as a barcode on the delivery note." }, "statusUpdatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the status of the delivery last changed (ISO 8601, UTC)." }, "inboundedDateTime": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the delivery was completed and its stock became available (ISO 8601, UTC); `null` until then." }, "inProcessingDateTime": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the warehouse started processing the delivery, moving it to `inProcessing` (ISO 8601, UTC); `null` until then." }, "atWarehouseDateTime": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the warehouse accepted the delivery, moving it to `atWarehouse` (ISO 8601, UTC); `null` until then." }, "aggregatedContainerStatus": { "type": [ "string", "null" ], "readOnly": true, "description": "Tracking status of the delivery as a whole, combined from the tracking statuses of its containers; `null` when none of them is tracked.\n\n- `pick_up`: waiting to be picked up by the carrier\n- `in_transit`: on the way to the warehouse\n- `out_for_delivery`: out for delivery to the warehouse\n- `partially_delivered`: some containers were delivered, others not yet\n- `delivered`: all containers were delivered\n- `delayed`: delivery is delayed\n- `failed_delivery`: the carrier failed to deliver" }, "customsMRNProvidedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the customs MRN was first provided (ISO 8601, UTC); `null` while there is none. The inbound deadline of an international delivery is not counted before this." }, "subStatus": { "type": [ "string", "null" ], "readOnly": true, "description": "Detail on the current status; `null` when there is none.\n\n- `waitingOnMRN`: the delivery needs a customs MRN before the warehouse can inbound it; provide it in `customsMRN`" }, "originConfirmedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the warehouse last recorded where the goods came from (`warehouseOriginIsUK`) (ISO 8601, UTC); `null` when it has not." }, "deliveryContainers": { "readOnly": true, "description": "Parcels or pallets the delivery arrives in, one per tracking number; at least one is required when announcing. A full update replaces them all.", "type": "array", "items": { "$ref": "#/$defs/DeliveryContainer" } }, "warehouseID": { "type": "string", "format": "uuid", "writeOnly": true, "description": "ID of the warehouse receiving the delivery (UUID)." }, "warehouse": { "readOnly": true, "description": "Warehouse receiving the delivery: its ID and country code.", "allOf": [ { "$ref": "#/$defs/StorageWarehouse" } ] }, "deliveryStandards": { "readOnly": true, "description": "Results of the delivery standards the warehouse checked on arrival; empty until they are checked.", "type": "array", "items": { "$ref": "#/$defs/DeliveryStandard" } }, "deviation": { "type": "boolean", "readOnly": true }, "deliverDate": { "type": "string", "format": "date-time", "readOnly": true }, "type": { "type": "string", "default": "regular", "enum": [ "container", "regular", "unknown" ], "description": "Type of delivery. Defaults to `regular`.\n\n- `container`: arriving in a shipping container; the expected dates must be equal, a business day, and at least 10 business days from now\n- `regular`: every other delivery\n- `unknown`: type not recorded" }, "acceptanceFee": { "readOnly": true, "description": "Fee charged for accepting the delivery at the warehouse; `null` when none was charged.", "allOf": [ { "$ref": "#/$defs/AcceptanceFee" } ] }, "customsPaid": { "readOnly": true, "description": "Customs charges the warehouse paid on your behalf when receiving the delivery; `null` when none were paid.", "allOf": [ { "$ref": "#/$defs/AcceptanceFee" } ] }, "damages": { "type": "string", "readOnly": true, "description": "Description of the overall damage the warehouse found on the delivery; `null` when none was recorded." }, "deleted": { "type": "boolean", "readOnly": true, "description": "Whether the delivery was cancelled." }, "deliveryCostsPaid": { "readOnly": true, "description": "Delivery costs the warehouse paid on your behalf when receiving the delivery; `null` when none were paid.", "allOf": [ { "$ref": "#/$defs/AcceptanceFee" } ] }, "deliveryNotes": { "type": "string", "readOnly": true, "description": "Other comments the warehouse recorded when accepting the delivery; `null` when there are none." }, "putawayFee": { "readOnly": true, "description": "Fee charged for putting the stock of the delivery away into storage; `null` when none was charged.", "allOf": [ { "$ref": "#/$defs/AcceptanceFee" } ] }, "status": { "type": "string", "enum": [ "announced", "atWarehouse", "inProcessing", "completed", "deleted" ], "readOnly": true, "description": "Current status of the delivery.\n\n- `announced`: announced and not yet arrived\n- `atWarehouse`: arrived and accepted by the warehouse\n- `inProcessing`: being counted and put away\n- `completed`: inbounded; the stock is available\n- `deleted`: cancelled" }, "userID": { "type": "string", "readOnly": true, "description": "ID of the user the delivery belongs to (UUID)." }, "deliveredBoxes": { "type": "integer", "readOnly": true, "minimum": 0, "description": "Number of loose boxes (parcels) the warehouse counted on arrival; `null` until the delivery has been counted." }, "deliveredPallets": { "type": "integer", "readOnly": true, "minimum": 0, "description": "Number of full pallets the warehouse counted on arrival; `null` until the delivery has been counted." }, "containerSizeConfirmed": { "type": [ "string", "null" ], "enum": [ "20ft", "40ft", null ], "readOnly": true, "description": "Size of the shipping container, as confirmed by the warehouse on arrival. Only for `container` deliveries; `null` otherwise.\n\n- `20ft`: 20-foot container\n- `40ft`: 40-foot container" }, "isPalletizedConfirmed": { "type": [ "boolean", "null" ], "readOnly": true, "description": "Whether the goods in the shipping container are on pallets, as confirmed by the warehouse on arrival. Only for `container` deliveries; `null` otherwise." }, "palletizationMinutes": { "type": [ "integer", "null" ], "readOnly": true, "minimum": 0, "description": "Time the warehouse spent putting the goods of the shipping container onto pallets, in minutes. Only for `container` deliveries; `null` otherwise." }, "meetsEUOrganicRequirements": { "type": [ "boolean", "null" ], "readOnly": true, "description": "Whether the delivery meets the EU organic requirements, as checked by the warehouse; `null` when it was not checked." }, "warehouseOriginIsUK": { "type": [ "boolean", "null" ], "readOnly": true, "description": "Whether the goods came from within the United Kingdom, as found by the warehouse on arrival. Only recorded for deliveries to a UK warehouse not declared international; `false` means an MRN is needed before inbounding. `null` when not recorded." }, "standardsCompliance": { "type": [ "string", "null" ], "readOnly": true, "description": "How far the delivery met the delivery standards checked by the warehouse on arrival.\n\n- `compliant`: all standards were met\n- `partially_compliant`: some standards were met\n- `non_compliant`: no standard was met\n- `compliance_not_checked`: the standards were not checked yet" }, "sortedBoxesCount": { "type": [ "integer", "null" ], "readOnly": true, "minimum": 0, "description": "Number of boxes the warehouse had to sort while processing the delivery; `null` until recorded." }, "sortedItemsCount": { "type": [ "integer", "null" ], "readOnly": true, "minimum": 0, "description": "Number of items the warehouse had to sort while processing the delivery; `null` until recorded." }, "deliveryItems": { "readOnly": true, "description": "Products in the delivery and their announced amounts; at least one is required when announcing, and each product may appear only once. A full update replaces them all.", "type": "array", "items": { "$ref": "#/$defs/DeliveryItem" } }, "inboundingDeadline": { "description": "Date by which the warehouse is due to inbound the delivery, and how that date was set. Calculated by byrd; ignored when sent.", "allOf": [ { "$ref": "#/$defs/InboundingDeadline" } ] }, "totalItems": { "type": "string", "readOnly": true, "description": "Total number of units announced across all items of the delivery." }, "totalSKUs": { "type": "string", "readOnly": true, "description": "Number of different products announced in the delivery." }, "totalContainers": { "type": "string", "readOnly": true, "description": "Number of containers (parcels or pallets) announced for the delivery." }, "newSKUCount": { "type": "string", "readOnly": true, "description": "Number of items whose product was new to the warehouse when the delivery was announced." }, "totalDocuments": { "type": "string", "readOnly": true, "description": "Number of documents attached to the delivery, by you or by the warehouse." }, "totalCustomerDocuments": { "type": "string", "readOnly": true, "description": "Number of documents attached to the delivery by you." }, "containerType": { "type": "string", "readOnly": true, "description": "Kind of containers the delivery arrives in; `null` when it has none.\n\n- `pallet`: all containers are pallets or EUR-pallets\n- `parcel`: all containers are parcels\n- `mixed`: both pallets and parcels" } }, "required": [ "expectedDeliveryDateFrom", "expectedDeliveryDateTo", "expressInbounding", "stocktaking", "warehouseID" ], "$defs": { "AcceptanceFee": { "type": "object", "properties": { "value": { "type": "number", "description": "Amount, as a string with two decimals separated by a dot." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency (ISO 4217 code, e.g. `EUR`)." }, "taxFactor": { "type": [ "number", "null" ], "readOnly": true, "description": "Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set." } }, "required": [ "currency", "value" ], "title": "Acceptance fee" }, "Barcode": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 48, "description": "Value encoded in the barcode, 1 to 48 characters; which characters are allowed depends on `barcodeType`." }, "barcodeType": { "description": "Symbology of the barcode; required when `value` is set.\n\n- `ean_13`: EAN-13\n- `code_128`: Code 128\n- `gs1_128`: GS1-128\n- `qr_code`: QR code", "type": "string", "enum": [ "ean_13", "code_128", "gs1_128", "qr_code" ] }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary barcode of the product, mirrored in its `barcode` and `barcodeType` fields. At most one barcode can be primary. Defaults to `false`." } }, "required": [ "value" ], "title": "Barcode" }, "DeliveryContainer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (UUID)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was last changed (ISO 8601)." }, "sequenceNumber": { "type": "integer", "minimum": 0, "description": "Position of the container within the delivery, used to order the containers; 0 or greater." }, "type": { "type": "string", "enum": [ "euroPallet", "pallet", "parcel" ], "description": "How the container arrives. Use the same type for all containers of a delivery.\n\n- `parcel`: a parcel\n- `pallet`: a pallet\n- `euroPallet`: a EUR-pallet (Euro-pallet)" }, "exchangeablePallet": { "type": "boolean", "description": "Whether the delivery is on exchangeable EUR-pallets (Euro-pallets, EPAL), which the warehouse exchanges for empty ones with the carrier on arrival. Set it to `false` when the pallet type is unknown or different." }, "carrier": { "type": "string", "enum": [ "DHL", "DHL_Express", "DPD", "FedEx", "GLS", "Hellmann", "Hermes", "PostAT", "PostDE", "UPS", "amazon", "chronopost", "colissimo_fr", "db_schenker", "dpd_de", "dpd_gb", "fiege", "gls_global", "post_at", "post_de", "post_it", "post_nl", "royalmail_gb", "tnt", "dsv_global", "dachser_global", "maersk_global", "strecktransport_global", "nacex_es", "correosexpress_global", "brt_it", "seur_es", "fercam_global", "unknown" ], "description": "Carrier bringing the container to the warehouse. Use `unknown` for any carrier not listed and give its name in `unknownCarrierName`." }, "unknownCarrierName": { "type": [ "string", "null" ], "description": "Name of the carrier when `carrier` is `unknown`; an empty string or `null` otherwise." }, "trackingNumber": { "type": [ "string", "null" ], "description": "Tracking number of the container with its carrier, used to track it on its way to the warehouse; `null` when there is none. Must not be a URL." }, "trackingURL": { "type": [ "string", "null" ], "description": "URL where the container can be tracked; `null` or empty when there is none." }, "arrived": { "type": "boolean", "description": "Whether the container has arrived at the warehouse, as recorded by the warehouse." }, "status": { "type": [ "string", "null" ], "enum": [ "pick_up", "in_transit", "out_for_delivery", "delivered", "delayed", "failed_delivery", null ], "readOnly": true, "description": "Tracking status of the container, updated from the carrier tracking of its `trackingNumber`; `null` until the first tracking update.\n\n- `pick_up`: waiting to be picked up by the carrier\n- `in_transit`: on the way to the warehouse\n- `out_for_delivery`: out for delivery to the warehouse\n- `delivered`: delivered to the warehouse\n- `delayed`: delivery is delayed\n- `failed_delivery`: the carrier failed to deliver" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the carrier delivered the container to the warehouse, according to its tracking (ISO 8601, UTC); `null` until then." } }, "required": [ "carrier", "exchangeablePallet", "sequenceNumber", "trackingNumber", "trackingURL", "type", "unknownCarrierName" ], "title": "Delivery container" }, "DeliveryItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (UUID)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was last changed (ISO 8601)." }, "sequenceNumber": { "type": "integer", "minimum": 0, "description": "Position of the item within the delivery, used to order the items; 0 or greater." }, "amount": { "type": "integer", "minimum": 1, "description": "Number of units of the product announced in the delivery; at least 1." }, "amountArrivedDamaged": { "type": "integer", "readOnly": true, "description": "Number of units that arrived damaged, as counted by the warehouse; `null` until recorded." }, "amountArrivedFinished": { "type": "integer", "readOnly": true, "description": "Number of units that arrived intact, as counted by the warehouse; `null` until recorded." }, "boxcode": { "type": "string", "description": "Your identifier of the box or boxes the product arrives in. Separate several box codes with commas." }, "hasExistingStorage": { "type": "boolean", "readOnly": true, "description": "Whether the product already has a storage location in the warehouse receiving the delivery." }, "newSKU": { "type": "boolean", "readOnly": true, "description": "Whether the product had no stock location in the warehouse when the delivery was announced, making it new to that warehouse." }, "receivedAmount": { "type": "integer", "readOnly": true, "description": "Number of units put away into stock from this item so far." }, "product": { "readOnly": true, "description": "Product announced in this item.", "allOf": [ { "$ref": "#/$defs/DeliveryItemProduct" } ] }, "productID": { "type": "string", "format": "uuid", "writeOnly": true, "description": "ID of the product announced in this item (UUID). The product must be active and cannot be a bundle or an alias." } }, "required": [ "amount", "boxcode", "productID", "sequenceNumber" ], "title": "Delivery item" }, "DeliveryItemProduct": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the product (UUID)." }, "bsku": { "type": [ "string", "null" ], "default": null, "readOnly": true, "pattern": "^BSKU-([A-Z0-9]){10}$", "description": "Unique SKU byrd generates for the product, unrelated to your `sku`." }, "sku": { "type": [ "string", "null" ], "minLength": 1, "description": "Your stock keeping unit (SKU) for the product, unique among your products. It must match the SKU your sales channel sends on order lines." }, "name": { "type": "string", "minLength": 1, "description": "Name of the product; at least one character." }, "description": { "type": [ "string", "null" ], "description": "Free-text description of the product." }, "organic": { "type": [ "boolean", "null" ], "description": "Whether the product is organic and needs special storage and shipping conditions. Bundles cannot be organic. Defaults to `false`." }, "grs": { "type": [ "boolean", "null" ], "description": "Whether the product complies with the Global Recycled Standard (GRS) and needs specific storage conditions. Defaults to `false`." }, "productType": { "type": [ "string", "null" ], "description": "Type of the product. Defaults to `product`; `bundle`, `supplementary` and `packaging_material` cannot be changed afterwards.\n\n- `product`: a regular physical product\n- `bundle`: a group of other products sold under one SKU, see `bundleIngredients`\n- `prepacked_product`: a product shipped in its own packaging\n- `packaging_material`: packaging material, such as boxes or fillers\n- `branding`: branded material packed into shipments, not counted as a product item\n- `supplementary`: a product only shipped together with another product\n- `alias`: another SKU for an existing product, sharing its stock\n- `marketing`: marketing material" }, "lotsEnabled": { "type": "boolean", "description": "Whether lots (batches) of the product are tracked when it is inbounded and shipped. Bundles cannot be lot tracked. Defaults to `false`." }, "barcode": { "type": [ "string", "null" ], "maxLength": 48, "description": "Value of the primary barcode printed on the product, at most 48 characters; mirrors the primary entry of `barcodes`. `null` when the product has no barcode." }, "barcodes": { "description": "All barcodes printed on the product, at most one of them primary. When you send both `barcode` and `barcodes`, `barcode` must match the primary entry.", "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Barcode" } } }, "required": [ "name" ], "title": "Delivery item product" }, "DeliveryStandard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the standard check (UUID)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was last changed (ISO 8601)." }, "deliveryID": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the delivery the check belongs to (UUID)." }, "label": { "description": "Standard the delivery was checked against.\n\n- `ANNOUNCED_BEFORE_ARRIVAL`: the delivery was announced before it arrived\n- `ARRIVED_WITH_BYRD_ID`: the parcels or pallets carried the delivery ID\n- `ARRIVED_WITH_DELIVERY_NOTE`: the delivery arrived with its delivery note", "type": "string", "enum": [ "ANNOUNCED_BEFORE_ARRIVAL", "ARRIVED_WITH_BYRD_ID", "ARRIVED_WITH_DELIVERY_NOTE" ] }, "isFulfilled": { "type": "boolean", "description": "Whether the delivery met the standard." } }, "required": [ "isFulfilled", "label" ], "title": "Delivery standard" }, "InboundingDeadline": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (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)." }, "date": { "type": [ "string", "null" ], "format": "date", "description": "Date by which the warehouse is due to inbound the delivery (ISO 8601 date); `null` when there is no deadline yet." }, "type": { "type": "string", "description": "How the deadline was set.\n\n- `not-applicable`: there is no deadline yet\n- `sla`: calculated from the warehouse's inbound service level, counted from the arrival of the delivery\n- `special-arrangement`: a date specially agreed with byrd" } }, "required": [ "date" ], "title": "Inbounding deadline" }, "StorageWarehouse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (UUID)." }, "countryCode": { "type": "string", "readOnly": true, "description": "Country the warehouse is in (ISO 3166-1 alpha-2)." } }, "title": "Storage warehouse" } } }