{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postnl/json-schema/postnl-confirm-shipment-request-schema.json",
  "title": "ConfirmShipmentRequest",
  "description": "The details of a shipment to be created",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postnl-shipment-api-openapi.yml#/components/schemas/ConfirmShipmentRequest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "receiver",
    "sender",
    "shipmentType"
  ],
  "properties": {
    "receiver": {
      "description": "The receiver of the shipment",
      "allOf": [
        {
          "$ref": "#/$defs/Receiver"
        }
      ]
    },
    "sender": {
      "description": "The sender of the shipment",
      "allOf": [
        {
          "$ref": "#/$defs/Customer"
        }
      ]
    },
    "deliveryLocation": {
      "description": "Can be used to specify an alternative delivery location, overriding the receiver address",
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryLocation"
        }
      ]
    },
    "returnOptions": {
      "description": "The return options for the shipment",
      "allOf": [
        {
          "$ref": "#/$defs/ReturnOptions"
        }
      ]
    },
    "itemCount": {
      "type": "integer",
      "description": "The number of items in the shipment, with a maximum of 50",
      "maximum": 50.0,
      "minimum": 1.0
    },
    "items": {
      "type": "array",
      "description": "The details per item in the shipment",
      "items": {
        "$ref": "#/$defs/ConfirmShipmentItem"
      }
    },
    "shipmentType": {
      "allOf": [
        {
          "$ref": "#/$defs/ShipmentType"
        }
      ]
    },
    "services": {
      "description": "The services that can be used for the shipment",
      "allOf": [
        {
          "$ref": "#/$defs/Services"
        }
      ]
    },
    "handoverDate": {
      "type": "string",
      "description": "The date on which the shipment is handed over",
      "format": "date"
    },
    "internationalShipmentData": {
      "description": "Data necessary for international shipments",
      "allOf": [
        {
          "$ref": "#/$defs/InternationalConfirmShipmentData"
        }
      ]
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "A postal address",
      "additionalProperties": false,
      "required": [
        "countryIso"
      ],
      "properties": {
        "city": {
          "type": "string",
          "description": "A city is a recognized area within a particular country that has a common name",
          "maxLength": 35
        },
        "countryIso": {
          "type": "string",
          "description": "A countryIso is a recognized ISO2 code for an area that has a common name",
          "maxLength": 2,
          "minLength": 2,
          "pattern": "^[A-Z]{2}$"
        },
        "houseNumber": {
          "type": "string",
          "description": "A houseNumber is an identifying indicator that identifies a particular building on a street or road",
          "maxLength": 10
        },
        "houseNumberAddition": {
          "type": "string",
          "description": "A houseNumberAddition is an identifying indicator that identifies a particular part of a building on a street or road\n            in case there are multiple residents living at the same address",
          "maxLength": 10
        },
        "postalCode": {
          "type": "string",
          "description": "A postalCode is a code of letters and digits that identifies a geographical area that is added to an address and is used by the postal service to sort mail",
          "maxLength": 17
        },
        "street": {
          "type": "string",
          "description": "A street is an identifying name that is given to a street or road",
          "maxLength": 95
        },
        "addressLine": {
          "type": "string",
          "description": "An addressLine is a combination of the elements that identifies a particular address within a city.\n            Can only be used for a combination of Street, HouseNumber and HouseNumberAddition"
        },
        "companyName": {
          "type": "string",
          "description": "Name of the company at this address",
          "maxLength": 35
        },
        "departmentName": {
          "type": "string",
          "description": "Name of the department at this address",
          "maxLength": 35
        },
        "internationalAddressData": {
          "description": "Fields specific to international shipment addresses",
          "allOf": [
            {
              "$ref": "#/$defs/InternationalAddress"
            }
          ]
        }
      }
    },
    "AssociatedDocument": {
      "type": "object",
      "description": "Fill in if applicable. Mandatory for Parcel shipments with the transactionCode 11, 21, or 32",
      "additionalProperties": false,
      "properties": {
        "type": {
          "description": "Fill in if applicable. Mandatory for Parcel shipments with the transactionCode 11, 21, or 32",
          "allOf": [
            {
              "$ref": "#/$defs/AssociatedDocumentType"
            }
          ]
        },
        "number": {
          "type": "string",
          "description": "Fill in if applicable. Mandatory for Parcel shipments with the transactionCode 11, 21, or 32",
          "minLength": 1
        }
      }
    },
    "AssociatedDocumentType": {
      "type": "string",
      "x-extensible-enum": [
        "certificate",
        "invoice",
        "license"
      ]
    },
    "Bundle": {
      "type": "string",
      "x-extensible-enum": [
        "track_trace",
        "insured",
        "insured_plus",
        "untracked"
      ]
    },
    "ConfirmShipmentItem": {
      "type": "object",
      "description": "The details per item in the shipment",
      "additionalProperties": false,
      "required": [
        "barcode"
      ],
      "properties": {
        "barcode": {
          "type": "string",
          "description": "The barcode of the item, generated or provided by the customer. This could be a 3S (domestic shipments) or S10 (international shipments) barcode.",
          "maxLength": 15,
          "minLength": 12
        },
        "dimensions": {
          "description": "The dimensions of the shipment item",
          "allOf": [
            {
              "$ref": "#/$defs/Dimensions"
            }
          ]
        },
        "customerReferences": {
          "description": "The customer references for the shipment item",
          "allOf": [
            {
              "$ref": "#/$defs/CustomerReferences"
            }
          ]
        },
        "codingText": {
          "type": "string"
        }
      }
    },
    "Contact": {
      "type": "object",
      "description": "Contact information of a person",
      "additionalProperties": false,
      "properties": {
        "email": {
          "type": "string",
          "description": "The email address of the contact person",
          "maxLength": 50
        },
        "firstName": {
          "type": "string",
          "description": "The first name of the contact person",
          "maxLength": 35
        },
        "lastName": {
          "type": "string",
          "description": "The last name of the contact person",
          "maxLength": 35
        },
        "mobileNumber": {
          "type": "string",
          "description": "The mobile number of the contact person",
          "maxLength": 17,
          "minLength": 7
        }
      }
    },
    "Customer": {
      "type": "object",
      "description": "The details of a customer",
      "additionalProperties": false,
      "required": [
        "customerNumber",
        "customerCode",
        "address"
      ],
      "properties": {
        "customerNumber": {
          "type": "string",
          "maxLength": 10,
          "minLength": 1
        },
        "customerCode": {
          "type": "string",
          "maxLength": 4,
          "minLength": 1
        },
        "address": {
          "description": "The address of the customer",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "undeliverableReturnAddress": {
          "description": "The undeliverable return address for the customer",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "contact": {
          "description": "The contact information of the customer",
          "allOf": [
            {
              "$ref": "#/$defs/Contact"
            }
          ]
        }
      }
    },
    "CustomerReferences": {
      "type": "object",
      "description": "The references of a shipment used by the customer",
      "additionalProperties": false,
      "properties": {
        "costCenter": {
          "type": "string",
          "description": "The cost center reference of the shipment"
        },
        "shipmentReference": {
          "type": "string",
          "description": "The customer reference of the shipment"
        },
        "returnReference": {
          "type": "string",
          "description": "The customer reference of the return shipment"
        },
        "shipmentRemark": {
          "type": "string",
          "description": "An additional remark for the shipment"
        }
      }
    },
    "Customs": {
      "type": "object",
      "description": "Object used when customs information is needed for the import or export of items",
      "additionalProperties": false,
      "properties": {
        "transactionCode": {
          "description": "The transactionCode describing the type of shipment this is. Refer to reference table to find correct value",
          "allOf": [
            {
              "$ref": "#/$defs/TransactionCode"
            }
          ]
        },
        "currency": {
          "type": "string",
          "description": "The currency used for all values of the items in the customs section based on ISO3",
          "maxLength": 3,
          "minLength": 3,
          "pattern": "^[A-Z]{3}$"
        },
        "handleAsNonDeliverable": {
          "type": "boolean",
          "description": "Determines what to do when the shipment cannot be delivered the first time\n            (if this is set to true,the shipment will be returned after the first failed attempt)",
          "default": false
        },
        "senderIdentification": {
          "type": "string",
          "description": "Use only when available. Is related to the ITMATT sender.identification.reference field.\n            Depending on the destination with this ID the customs process can be faster.\n            Only fill in this reference number if the sender is registered as Trusted Shipper in the country of destination.\n            Example:VOEC-number in Norway.",
          "maxLength": 50
        },
        "receiverIdentification": {
          "type": "string",
          "description": "Use only when available. Is related to the ITMATT addressee.identification.reference field.\n            Depending on the destination with this ID the customs process can be faster.\n            Only fill in this reference number if the sender is registered in the country of destination.\n            Example:BSN in Brazil."
        },
        "content": {
          "type": "array",
          "description": "Array used to declare items in shipment for customs purposes",
          "items": {
            "$ref": "#/$defs/CustomsContent"
          }
        },
        "associatedDocument": {
          "description": "Fill in if applicable. Mandatory for Parcel shipments with the transactionCode 11, 21, or 32",
          "allOf": [
            {
              "$ref": "#/$defs/AssociatedDocument"
            }
          ]
        }
      }
    },
    "CustomsContent": {
      "type": "object",
      "description": "Item declaration used for customs purposes",
      "additionalProperties": false,
      "required": [
        "countryOfOrigin",
        "description",
        "hsTariffNumber",
        "quantity",
        "value",
        "weight"
      ],
      "properties": {
        "countryOfOrigin": {
          "type": "string",
          "description": "Country where the shipped item was produced based on ISO2",
          "maxLength": 2,
          "minLength": 2,
          "pattern": "^[A-Z]{2}$"
        },
        "description": {
          "type": "string",
          "description": "Description of the shipped items",
          "maxLength": 35,
          "minLength": 2
        },
        "hsTariffNumber": {
          "type": "string",
          "description": "The Harmonized System number of the shipped item with 6, 8 or 10 characters",
          "maxLength": 10,
          "minLength": 6,
          "pattern": "^\\d{6}$|^\\d{8}$|^\\d{10}$"
        },
        "quantity": {
          "type": "integer",
          "description": "Number of the items within the shipment. Cannot be negative",
          "minimum": 1.0
        },
        "value": {
          "type": "number",
          "description": "Fill the total value of the item(s)",
          "format": "decimal",
          "minimum": 0.01
        },
        "weight": {
          "type": "integer",
          "description": "Total net weight of the item(s) in grams. Max weight allowed of 32000",
          "maximum": 32000.0,
          "minimum": 1.0
        }
      }
    },
    "DeliveryConfirmation": {
      "type": "string",
      "x-extensible-enum": [
        "signature",
        "deliverycode"
      ]
    },
    "DeliveryLocation": {
      "type": "object",
      "description": "Can be used to specify an alternative delivery location, overriding the receiver address",
      "additionalProperties": false,
      "properties": {
        "pickupLocationId": {
          "type": "string",
          "description": "The pickup point id of the location where the shipment should be delivered, for example a PostNL location or automated parcel locker"
        }
      }
    },
    "DeliveryWindow": {
      "type": "object",
      "description": "The delivery window service that can be used for the shipment",
      "additionalProperties": false,
      "properties": {
        "service": {
          "description": "The delivery window service that can be used for the shipment",
          "allOf": [
            {
              "$ref": "#/$defs/Service"
            }
          ]
        },
        "guaranteedBefore": {
          "description": "The time before which the delivery is guaranteed to be delivered, using the Guaranteed Before service",
          "allOf": [
            {
              "$ref": "#/$defs/GuaranteedBefore"
            }
          ]
        },
        "duration": {
          "description": "The duration of the delivery window service",
          "allOf": [
            {
              "$ref": "#/$defs/Duration"
            }
          ]
        }
      }
    },
    "Dimensions": {
      "type": "object",
      "description": "The dimensions of the shipment item",
      "additionalProperties": false,
      "properties": {
        "height": {
          "type": "integer",
          "description": "The height of the parcel in mm",
          "minimum": 0.0
        },
        "length": {
          "type": "integer",
          "description": "The length of the parcel in mm",
          "minimum": 0.0
        },
        "volume": {
          "type": "integer",
          "description": "The volume of the parcel in cubic cm",
          "minimum": 0.0
        },
        "weight": {
          "type": "integer",
          "description": "The weight of the parcel in grams",
          "minimum": 0.0
        },
        "width": {
          "type": "integer",
          "description": "The width of the parcel in mm",
          "minimum": 0.0
        }
      }
    },
    "Duration": {
      "type": "string",
      "x-extensible-enum": [
        "24hours",
        "non24hours"
      ]
    },
    "GuaranteedBefore": {
      "type": "string",
      "x-extensible-enum": [
        "10:00",
        "12:00",
        "17:00"
      ]
    },
    "InternationalAddress": {
      "type": "object",
      "description": "Fields specific to an international shipment address",
      "additionalProperties": false,
      "properties": {
        "area": {
          "type": "string",
          "description": "Area of the address",
          "maxLength": 35
        },
        "buildingName": {
          "type": "string",
          "description": "Buildingname of the address",
          "maxLength": 35
        },
        "doorCode": {
          "type": "string",
          "description": "Doorcode of the address",
          "maxLength": 35
        },
        "floor": {
          "type": "string",
          "description": "Floor of the address",
          "maxLength": 35
        },
        "region": {
          "type": "string",
          "description": "Region of the address",
          "maxLength": 35
        }
      }
    },
    "InternationalConfirmShipmentData": {
      "type": "object",
      "description": "Data necessary for international shipments",
      "additionalProperties": false,
      "properties": {
        "pudo": {
          "type": "boolean",
          "description": "A boolean to indicate whether or not a dropOff should be used or not"
        },
        "partnerId": {
          "type": "string",
          "description": "The Id of the selected Partner for shipping provided when a label is generated."
        },
        "partnerBarcode": {
          "type": "string",
          "description": "The barcode provided by the partner when a label is generated."
        },
        "bundle": {
          "description": "The type of service bundle that is used for the shipment",
          "allOf": [
            {
              "$ref": "#/$defs/Bundle"
            }
          ]
        },
        "customs": {
          "description": "Object used when customs information is needed for the import or export of items",
          "allOf": [
            {
              "$ref": "#/$defs/Customs"
            }
          ]
        }
      }
    },
    "MinimalAgeCheck": {
      "type": "string",
      "x-extensible-enum": [
        "18+"
      ]
    },
    "Receiver": {
      "type": "object",
      "description": "The details of the receiver of the shipment",
      "additionalProperties": false,
      "required": [
        "address"
      ],
      "properties": {
        "contact": {
          "allOf": [
            {
              "$ref": "#/$defs/Contact"
            }
          ]
        },
        "address": {
          "$ref": "#/$defs/Address"
        },
        "type": {
          "description": "Define the kind of receiver, possibly used to plan delivery times inside business hours. Only used for parcel shipments send to EU countries",
          "allOf": [
            {
              "$ref": "#/$defs/ReceiverType"
            }
          ]
        }
      }
    },
    "ReceiverType": {
      "type": "string",
      "x-extensible-enum": [
        "business",
        "consumer"
      ]
    },
    "ReturnOptions": {
      "type": "object",
      "description": "The return options for the shipment",
      "additionalProperties": false,
      "properties": {
        "returnBarcode": {
          "type": "string",
          "description": "This field contains the return barcode that will be used for the label in the box",
          "maxLength": 15,
          "minLength": 12
        },
        "returnPeriod": {
          "description": "The number of days the shipment can be returned to the sender. Options are 35, 100, 200, 365",
          "allOf": [
            {
              "$ref": "#/$defs/ReturnPeriod"
            }
          ]
        },
        "returnAddress": {
          "description": "The address to which the shipment can be returned",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "valuableReturn": {
          "type": "boolean",
          "description": "Indicates if the return shipment contains valuable goods.."
        }
      }
    },
    "ReturnPeriod": {
      "type": "string",
      "x-extensible-enum": [
        "35",
        "100",
        "200",
        "365"
      ]
    },
    "Service": {
      "type": "string",
      "x-extensible-enum": [
        "evening"
      ]
    },
    "Services": {
      "type": "object",
      "description": "The services that can be used for the shipment",
      "additionalProperties": false,
      "properties": {
        "insuredValue": {
          "type": "number",
          "description": "The value of the shipment in EUR, used to insure the shipment when provided",
          "format": "decimal"
        },
        "deliveryWindow": {
          "description": "The delivery window service that can be used for the shipment",
          "allOf": [
            {
              "$ref": "#/$defs/DeliveryWindow"
            }
          ]
        },
        "statedAddressOnly": {
          "type": "boolean",
          "description": "When set to true, the shipment will only be delivered to the stated address"
        },
        "returnWhenNotHome": {
          "type": "boolean",
          "description": "When set to true, the shipment will be returned to the sender when the shipment cannot be delivered to the stated address"
        },
        "minimalAgeCheck": {
          "description": "The age that the receiver must be to receive the shipment",
          "allOf": [
            {
              "$ref": "#/$defs/MinimalAgeCheck"
            }
          ]
        },
        "deliveryConfirmation": {
          "description": "The type of confirmation that is required for the delivery, either a signature or a deliverycode",
          "allOf": [
            {
              "$ref": "#/$defs/DeliveryConfirmation"
            }
          ]
        },
        "adrLq": {
          "type": "boolean",
          "description": "When a contract exists for goods that have Limited Quantity hazardous materials then set this to true if this is an ADR LQ shipment"
        },
        "registered": {
          "type": "boolean",
          "description": "When set to true, the shipment will be sent as a registered parcel or mail item"
        },
        "idCheck": {
          "type": "boolean",
          "description": "Add ID check to registered letters"
        }
      }
    },
    "ShipmentType": {
      "type": "string",
      "x-extensible-enum": [
        "parcel",
        "letterbox",
        "packet",
        "parcelnonstandard",
        "letter"
      ]
    },
    "TransactionCode": {
      "type": "string",
      "x-extensible-enum": [
        "11",
        "21",
        "32",
        "91"
      ]
    }
  }
}