{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/dhl/json-schema/dhl-shipment-schema.json",
  "title": "Shipment",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/dhl-print-dhl-freight-openapi.yml#/components/schemas/Shipment",
  "required": [
    "id",
    "parties",
    "payerCode",
    "pieces",
    "productCode"
  ],
  "type": "object",
  "properties": {
    "id": {
      "maxLength": 13,
      "type": "string",
      "description": "The shipment's tracking id: The unique global number that ensures that packages are not separated from each other during transport from one point to another.\n"
    },
    "productCode": {
      "maxLength": 3,
      "type": "string",
      "description": "See the product documentation for available options. You can also use GET /products to see available product for your region. With POST /productmatches you can validate which products fit to your shipment details."
    },
    "shippingDate": {
      "type": "string",
      "format": "date"
    },
    "requestedDeliveryDate": {
      "type": "string",
      "description": "Required with **DHL Eurapid** and Commited Delivery Date (CDD).",
      "format": "date"
    },
    "deliveryInstruction": {
      "maxLength": 140,
      "type": "string"
    },
    "totalNumberOfPieces": {
      "maximum": 999,
      "type": "integer",
      "format": "int32"
    },
    "totalWeight": {
      "maximum": 99999,
      "type": "number",
      "description": "The shipment total weight weight in kg",
      "format": "double"
    },
    "totalVolume": {
      "maximum": 999,
      "type": "number",
      "description": "The shipment total volume in m³",
      "format": "double"
    },
    "totalLoadingMeters": {
      "maximum": 99,
      "type": "number",
      "description": "A loading meter (LDM) is 1 meter of the loading space of a truck's width and full height. Usually calculated for goods that cannot be stacked on or with other goods.",
      "format": "double"
    },
    "payerCode": {
      "$ref": "#/$defs/PayerCode"
    },
    "parties": {
      "maxItems": 6,
      "minItems": 2,
      "type": "array",
      "items": {
        "$ref": "#/$defs/Party"
      }
    },
    "pieces": {
      "maxItems": 999,
      "type": "array",
      "items": {
        "$ref": "#/$defs/Piece"
      }
    },
    "additionalServices": {
      "$ref": "#/$defs/AdditionalServicesDTO"
    },
    "additionalInformation": {
      "maxItems": 99,
      "type": "array",
      "items": {
        "$ref": "#/$defs/AdditionalInformation"
      }
    }
  },
  "$defs": {
    "AdditionalInformation": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "EKAER_NUMBER",
            "EKAER_FREE",
            "SENT_REF",
            "SENT_CARKEY"
          ],
          "description": "Contains predefined code values (see enumerator) to handle country specific shipment fields for e.g. Hungarian EKAER and Polish SENT legal requirements.\n"
        },
        "stringValue": {
          "type": "string",
          "description": "Contains the content/value for the respective code. For EKAER_NUMBER: provide the Hungarian EKAER number and omit EKAER_FREE. For EKAER_FREE: provide true or false. If true, omit EKAER_NUMBER. For SENT_REF: provide the Polish SENT system reference value. For SENT_CARKEY: provide the Polish SENT carrier key\n"
        },
        "dateValue": {
          "type": "string",
          "format": "date-time"
        },
        "numericValue": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "AdditionalServicesDTO": {
      "type": "object",
      "properties": {
        "after12Delivery": {
          "type": "boolean"
        },
        "availableDeliveryTime": {
          "$ref": "#/$defs/AvailablePickupDeliveryTimeOptions"
        },
        "availablePickupTime": {
          "$ref": "#/$defs/AvailablePickupDeliveryTimeOptions"
        },
        "cashOnDelivery": {
          "$ref": "#/$defs/CashOnDeliveryOptions"
        },
        "dangerousGoods": {
          "type": "boolean"
        },
        "dropOffByConsignor": {
          "type": "boolean"
        },
        "fixedDeliveryDate": {
          "$ref": "#/$defs/FixedDeliveryDateOptions"
        },
        "highValueShipment": {
          "$ref": "#/$defs/HighValueShipmentOptions"
        },
        "insurance": {
          "$ref": "#/$defs/InsuranceOptions"
        },
        "preAdvice": {
          "type": "boolean"
        },
        "driverPreAdviceDelivery": {
          "type": "boolean"
        },
        "priorityServiceP10": {
          "type": "boolean"
        },
        "priorityServiceP12": {
          "type": "boolean"
        },
        "sideLoadingPickup": {
          "type": "boolean"
        },
        "sideUnloadingDelivery": {
          "type": "boolean"
        },
        "tailLiftLoading": {
          "type": "boolean"
        },
        "tailLiftUnloading": {
          "type": "boolean"
        },
        "temperatureControlled": {
          "$ref": "#/$defs/TemperatureControlledOptions"
        },
        "thermoCold": {
          "$ref": "#/$defs/ThermoColdOptions"
        },
        "timeSlotBookingPickup": {
          "type": "boolean"
        },
        "timeSlotBookingDelivery": {
          "type": "boolean"
        }
      }
    },
    "Address": {
      "required": [
        "street",
        "cityName",
        "postalCode",
        "countryCode"
      ],
      "type": "object",
      "properties": {
        "street": {
          "maxLength": 35,
          "type": "string",
          "description": "Provide both street name and house number in this field."
        },
        "additionalAddressInfo": {
          "maxLength": 35,
          "type": "string"
        },
        "cityName": {
          "maxLength": 35,
          "type": "string"
        },
        "postalCode": {
          "maxLength": 9,
          "type": "string"
        },
        "countryCode": {
          "maxLength": 2,
          "type": "string",
          "description": "ISO 3166-1 are two-letter country codes \n"
        }
      }
    },
    "AvailablePickupDeliveryTimeOptions": {
      "required": [
        "fromTime",
        "toTime"
      ],
      "type": "object",
      "description": "Use this time frame for indicating pickup/delivery location’s opening hours or when your goods are available for pickup.  For a fixed aligned pickup/delivery time slot window, please use the respective additional services time slot booking.    \n",
      "properties": {
        "fromTime": {
          "type": "string",
          "format": "time"
        },
        "toTime": {
          "type": "string",
          "format": "time"
        }
      }
    },
    "CashOnDeliveryOptions": {
      "required": [
        "amount",
        "currency"
      ],
      "type": "object",
      "properties": {
        "amount": {
          "type": "integer",
          "format": "int64"
        },
        "currency": {
          "maxLength": 3,
          "type": "string",
          "description": "ISO 4217 codes are three-letter currency codes\n"
        }
      }
    },
    "FixedDeliveryDateOptions": {
      "required": [
        "date"
      ],
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "HighValueShipmentOptions": {
      "required": [
        "currency",
        "value"
      ],
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "format": "double"
        },
        "currency": {
          "maxLength": 3,
          "type": "string",
          "description": "ISO 4217 codes are three-letter currency codes.\n"
        }
      }
    },
    "InsuranceOptions": {
      "required": [
        "currency",
        "value"
      ],
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "format": "double"
        },
        "currency": {
          "maxLength": 3,
          "type": "string",
          "description": "ISO 4217 codes are three-letter currency codes\n"
        }
      }
    },
    "Party": {
      "required": [
        "address",
        "name",
        "type"
      ],
      "type": "object",
      "properties": {
        "id": {
          "maxLength": 15,
          "type": "string",
          "description": "For a consignor, consignee or freight payer the customer account number. Mandatory for the party that according to the payer code will be freight payer. For an access point, i.e. parcel shop, parcel station etc, this is the identifier of this location."
        },
        "type": {
          "maxLength": 15,
          "type": "string",
          "enum": [
            "Consignor",
            "Pickup",
            "Consignee",
            "Delivery"
          ]
        },
        "vatEoriSocialSecurityNumber": {
          "maxLength": 20,
          "type": "string",
          "description": "Used for customs clearance when importing or exporting with countries outside the EU."
        },
        "name": {
          "maxLength": 35,
          "type": "string"
        },
        "contactName": {
          "maxLength": 35,
          "type": "string"
        },
        "references": {
          "maxItems": 99,
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "address": {
          "$ref": "#/$defs/Address"
        },
        "phone": {
          "maxLength": 64,
          "type": "string"
        },
        "email": {
          "maxLength": 64,
          "type": "string"
        }
      }
    },
    "PayerCode": {
      "required": [
        "code"
      ],
      "type": "object",
      "properties": {
        "code": {
          "maxLength": 3,
          "type": "string",
          "description": "See the product documentation for available options based on selected product. You can also use GET /products {productCode} to see available payer codes for your product."
        }
      }
    },
    "Piece": {
      "required": [
        "id",
        "numberOfPieces",
        "packageType",
        "weight"
      ],
      "type": "object",
      "properties": {
        "id": {
          "type": "array",
          "minItems": 1,
          "maxItems": 999,
          "uniqueItems": true,
          "description": "The SSCC (Serial Shipping Container Code) a unique GS1/GS1-128 number, used to identify a logistic unit, such as a case, pallet or parcel.\n",
          "items": {
            "maxLength": 35,
            "type": "string"
          }
        },
        "goodsType": {
          "maxLength": 70,
          "type": "string",
          "description": "Description of goods on cargo detail level."
        },
        "packageType": {
          "maxLength": 4,
          "type": "string",
          "description": "See the product documentation for available options based on selected product. You can also use GET / packageTypes {productCode} to receive the allowed package types for your selected product\n"
        },
        "marksAndNumbers": {
          "maxLength": 45,
          "type": "string"
        },
        "numberOfPieces": {
          "maximum": 999,
          "minimum": 1,
          "type": "integer",
          "format": "int32"
        },
        "weight": {
          "maximum": 99999,
          "type": "number",
          "description": "Item weight in kg",
          "format": "double"
        },
        "volume": {
          "maximum": 999,
          "type": "number",
          "description": "Item volume in m³",
          "format": "double"
        },
        "loadingMeters": {
          "maximum": 99,
          "type": "number",
          "format": "double"
        },
        "width": {
          "maximum": 999,
          "type": "number",
          "description": "Item width in cm",
          "format": "double"
        },
        "height": {
          "maximum": 999,
          "type": "number",
          "description": "Item height in cm",
          "format": "double"
        },
        "length": {
          "maximum": 9999,
          "type": "number",
          "description": "Item length in cm",
          "format": "double"
        },
        "stackable": {
          "type": "boolean"
        }
      }
    },
    "TemperatureControlledOptions": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/$defs/ThermoType"
        },
        "min": {
          "type": "number",
          "format": "double"
        },
        "max": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "ThermoColdOptions": {
      "type": "object",
      "description": "For “Thermo Cold” deliveries, the temperature is maintained at between +2 and +8°C throughout the transport chain. Different temperature ranges can be provided by special agreement (although max. 15°C).\n",
      "properties": {
        "min": {
          "type": "number",
          "format": "double",
          "minimum": 2
        },
        "max": {
          "type": "number",
          "format": "double",
          "maximum": 15
        }
      }
    },
    "ThermoType": {
      "type": "string",
      "enum": [
        "Cold",
        "Ambient",
        "Custom"
      ],
      "description": "Thermo Type as Cold (2-8 °C), Ambient (15-25 °C), Custom (min-max °C)"
    }
  }
}