{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bol-com/json-schema/bol-com-shipment-schema.json",
  "title": "Shipment",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bol-com-shipments-api-openapi.yml#/components/schemas/Shipment",
  "required": [
    "order",
    "shipmentId",
    "shipmentItems",
    "shipmentReference"
  ],
  "type": "object",
  "properties": {
    "shipmentId": {
      "type": "string",
      "description": "A unique identifier for this shipment."
    },
    "shipmentDateTime": {
      "type": [
        "string",
        "null"
      ],
      "description": "The date and time in ISO 8601 format when the order item was shipped.",
      "format": "date-time"
    },
    "shipmentReference": {
      "type": "string",
      "description": "Reference supplied by the user when this item was shipped."
    },
    "pickupPoint": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Indicates whether this order is shipped to a Pick Up Point."
    },
    "order": {
      "$ref": "#/$defs/ShipmentOrder"
    },
    "shipmentDetails": {
      "allOf": [
        {
          "$ref": "#/$defs/ShipmentDetails"
        }
      ]
    },
    "billingDetails": {
      "allOf": [
        {
          "$ref": "#/$defs/BillingDetails"
        }
      ]
    },
    "shipmentItems": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ShipmentItem"
      }
    },
    "transport": {
      "allOf": [
        {
          "$ref": "#/$defs/ShipmentTransport"
        }
      ]
    }
  },
  "$defs": {
    "BillingDetails": {
      "required": [
        "city",
        "countryCode",
        "email",
        "firstName",
        "houseNumber",
        "salutation",
        "streetName",
        "surname",
        "zipCode"
      ],
      "type": "object",
      "properties": {
        "salutation": {
          "type": "string",
          "description": "The salutation of the customer.",
          "enum": [
            "MALE",
            "FEMALE",
            "UNKNOWN"
          ]
        },
        "firstName": {
          "type": "string",
          "description": "The first name of the customer."
        },
        "surname": {
          "type": "string",
          "description": "The surname of the customer."
        },
        "streetName": {
          "type": "string",
          "description": "The street name."
        },
        "houseNumber": {
          "type": "string",
          "description": "The house number."
        },
        "houseNumberExtension": {
          "type": [
            "string",
            "null"
          ],
          "description": "The extension on the house number."
        },
        "extraAddressInformation": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additional information related to the address that helps in delivering the package."
        },
        "zipCode": {
          "type": "string",
          "description": "The ZIP code in '1234AB' format for NL orders and '0000' format for BE orders."
        },
        "city": {
          "type": "string",
          "description": "The name of the city."
        },
        "countryCode": {
          "type": "string",
          "description": "The country code."
        },
        "email": {
          "type": "string",
          "description": "A scrambled email address that can be used to contact the customer."
        },
        "company": {
          "type": [
            "string",
            "null"
          ],
          "description": "The company name."
        },
        "vatNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Value Added Tax (VAT) / BTW number for business sellers situated in the Netherlands."
        },
        "kvkNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Kamer van Koophandel (kvk) number for organizations situated in the Netherlands or ondernemingsnummer for organizations situated in Belgium."
        },
        "orderReference": {
          "type": [
            "string",
            "null"
          ],
          "description": "The order reference specified by the customer when ordering a product."
        }
      },
      "description": "The details of the customer that is responsible for the financial fulfillment of this order."
    },
    "OrderOffer": {
      "type": "object",
      "properties": {
        "offerId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Unique identifier for an offer."
        },
        "reference": {
          "type": [
            "string",
            "null"
          ],
          "description": "A user-defined reference that helps you identify this particular offer when receiving data from us. This element can optionally be left empty and has a maximum amount of 100 characters."
        }
      }
    },
    "OrderProduct": {
      "required": [
        "ean",
        "title"
      ],
      "type": "object",
      "properties": {
        "ean": {
          "type": "string",
          "description": "The EAN number associated with this product."
        },
        "title": {
          "type": "string",
          "description": "Title of the product as shown on the webshop."
        }
      }
    },
    "ShipmentDetails": {
      "required": [
        "city",
        "countryCode",
        "firstName",
        "houseNumber",
        "salutation",
        "streetName",
        "surname",
        "zipCode"
      ],
      "type": "object",
      "properties": {
        "pickupPointName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name of Pick Up Point location this order needs to be shipped to."
        },
        "salutation": {
          "type": "string",
          "description": "The salutation of the customer.",
          "enum": [
            "MALE",
            "FEMALE",
            "UNKNOWN"
          ]
        },
        "firstName": {
          "type": "string",
          "description": "The first name of the customer."
        },
        "surname": {
          "type": "string",
          "description": "The surname of the customer."
        },
        "streetName": {
          "type": "string",
          "description": "The street name."
        },
        "houseNumber": {
          "type": "string",
          "description": "The house number."
        },
        "houseNumberExtension": {
          "type": [
            "string",
            "null"
          ],
          "description": "The extension on the house number."
        },
        "extraAddressInformation": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additional information related to the address that helps in delivering the package."
        },
        "zipCode": {
          "type": "string",
          "description": "The ZIP code in '1234AB' format for NL orders and '0000' format for BE orders."
        },
        "city": {
          "type": "string",
          "description": "The name of the city."
        },
        "countryCode": {
          "type": "string",
          "description": "The country code."
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "A scrambled email address that can be used to contact the customer."
        },
        "company": {
          "type": [
            "string",
            "null"
          ],
          "description": "The company name."
        },
        "deliveryPhoneNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The delivery phone number of the customer. Filled in case the order requires an appointment for delivering the goods."
        },
        "language": {
          "type": [
            "string",
            "null"
          ],
          "description": "The language of the customer in case of contact.",
          "enum": [
            "nl, nl-BE, fr, fr-BE",
            null
          ]
        }
      },
      "description": "The address details where this order needs to be shipped to. This can be the customers' own address, a (company) business address or a Pick Up Point address."
    },
    "ShipmentFulfilment": {
      "required": [
        "method"
      ],
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "description": "The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).",
          "enum": [
            "FBR",
            "FBB"
          ]
        },
        "distributionParty": {
          "type": [
            "string",
            "null"
          ],
          "description": "The party that manages the distribution, either bol.com or the retailer itself.",
          "enum": [
            "RETAILER",
            "BOL",
            null
          ]
        },
        "latestDeliveryDate": {
          "type": [
            "string",
            "null"
          ],
          "description": "The ultimate delivery date at which this order must be delivered at the customer's shipping address. This field is empty in case the exactDeliveryDate is filled.",
          "format": "date"
        }
      }
    },
    "ShipmentItem": {
      "required": [
        "orderItemId",
        "quantity",
        "unitPrice"
      ],
      "type": "object",
      "properties": {
        "orderItemId": {
          "type": "string",
          "description": "A unique identifier for the item of the order that was shipped in this shipment."
        },
        "fulfilment": {
          "allOf": [
            {
              "$ref": "#/$defs/ShipmentFulfilment"
            }
          ]
        },
        "offer": {
          "allOf": [
            {
              "$ref": "#/$defs/OrderOffer"
            }
          ]
        },
        "product": {
          "allOf": [
            {
              "$ref": "#/$defs/OrderProduct"
            }
          ]
        },
        "quantity": {
          "type": "integer",
          "description": "Amount of ordered products for this order item id.",
          "format": "int32"
        },
        "quantityShipped": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Amount of shipped products for this order item id.",
          "format": "int32"
        },
        "unitPrice": {
          "type": "number",
          "description": "The selling price to the customer of a single unit including VAT."
        },
        "commission": {
          "type": [
            "number",
            "null"
          ],
          "description": "The commission."
        }
      }
    },
    "ShipmentOrder": {
      "required": [
        "orderId"
      ],
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string",
          "description": "A unique identifier for the order this shipment is related to."
        },
        "orderPlacedDateTime": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date and time in ISO 8601 format when the order was placed.",
          "format": "date-time"
        }
      }
    },
    "ShipmentTransport": {
      "type": "object",
      "properties": {
        "transportId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The transport id."
        },
        "transporterCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "Specify the transporter that will carry out the shipment."
        },
        "trackAndTrace": {
          "type": [
            "string",
            "null"
          ],
          "description": "The track and trace code that is associated with this transport."
        },
        "shippingLabelId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The shipping label id."
        },
        "transportEvents": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/TransportEvent"
          }
        }
      }
    },
    "TransportEvent": {
      "required": [
        "eventCode",
        "eventDateTime"
      ],
      "type": "object",
      "properties": {
        "eventCode": {
          "type": "string",
          "description": "The transport event code indicates the location of the parcel within the distribution process.",
          "enum": [
            "PRE_ANNOUNCED, AT_TRANSPORTER, IN_TRANSIT, DELIVERED_AT_NEIGHBOURS, DELIVERED_AT_CUSTOMER, PICKED_UP_AT_PICK_UP_POINT, AT_PICK_UP_POINT, RETURNED_TO_SENDER, INBOUND_COLLECT"
          ]
        },
        "eventDateTime": {
          "type": "string",
          "description": "The date time of the transport event.",
          "format": "date-time"
        }
      }
    }
  }
}