RetailerOffer

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bol-com/json-schema/bol-com-retailer-offer-schema.json",
  "title": "RetailerOffer",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bol-com-openapi.json#/components/schemas/RetailerOffer",
  "required": [
    "condition",
    "ean",
    "fulfilment",
    "notPublishableReasons",
    "offerId",
    "onHoldByRetailer",
    "pricing",
    "stock",
    "store"
  ],
  "type": "object",
  "properties": {
    "offerId": {
      "type": "string",
      "description": "Unique identifier for an offer."
    },
    "ean": {
      "type": "string",
      "description": "The EAN number associated with this product. Note: in case an ISBN is provided, the ISBN will be replaced with the actual EAN belonging to this ISBN."
    },
    "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."
    },
    "onHoldByRetailer": {
      "type": "boolean",
      "description": "This field specifies whether the retailer has temporarily suspended the listing of this offer on the bol.com website. When set to true, the offer becomes invisible to customers and is not available for purchase. The default setting, false, indicates that the offer is active and visible on the website. This feature is useful for managing inventory or making updates to the offer without permanently removing it from the site."
    },
    "economicOperatorId": {
      "type": [
        "string",
        "null"
      ],
      "description": "An identifier referring to the Economic operator entity (manufacturer, authorized party, importer, distributor or other natural person or legal entity for whom the obligations apply with regards to the manufacturing, or making available on the market of the product in line with the applicable EU laws)."
    },
    "unknownProductTitle": {
      "type": [
        "string",
        "null"
      ],
      "description": "In case the item is not known to bol.com you can use this field to identify this particular product. Note: in case the product is known to bol.com, the unknown product title will not be stored."
    },
    "pricing": {
      "$ref": "#/$defs/Pricing"
    },
    "stock": {
      "$ref": "#/$defs/Stock"
    },
    "fulfilment": {
      "$ref": "#/$defs/Fulfilment"
    },
    "store": {
      "$ref": "#/$defs/Store"
    },
    "condition": {
      "$ref": "#/$defs/Condition"
    },
    "notPublishableReasons": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/NotPublishableReason"
      }
    }
  },
  "$defs": {
    "BundlePrice": {
      "required": [
        "quantity",
        "unitPrice"
      ],
      "type": "object",
      "properties": {
        "quantity": {
          "maximum": 24,
          "minimum": 1,
          "type": [
            "integer",
            "null"
          ],
          "description": "The minimum quantity a customer must order in order to receive discount. The element with value 1 must at least be present. In case of using more elements, the respective quantities must be in increasing order.",
          "format": "int32"
        },
        "unitPrice": {
          "maximum": 9999,
          "minimum": 1,
          "type": [
            "number",
            "null"
          ],
          "description": "The price per single unit including VAT in case the customer orders at least the quantity provided. When using more than 1 price, the respective prices must be in decreasing order using 2 decimal precision and dot separated."
        }
      },
      "description": "A set of prices (containing a quantity and selling price) that apply to this offer."
    },
    "Condition": {
      "required": [
        "name"
      ],
      "type": "object",
      "properties": {
        "name": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "The condition of the offered product.",
          "enum": [
            "NEW",
            "AS_NEW",
            "GOOD",
            "REASONABLE",
            "MODERATE"
          ]
        },
        "category": {
          "type": [
            "string",
            "null"
          ],
          "description": "The category of the condition. If not given NEW or SECONDHAND is derived from NAME.",
          "enum": [
            "NEW",
            "SECONDHAND"
          ]
        },
        "comment": {
          "maxLength": 2000,
          "minLength": 0,
          "type": [
            "string",
            "null"
          ],
          "description": "The description of the condition of the product. Only allowed if name is not NEW and may not contain e-mail addresses."
        }
      }
    },
    "Fulfilment": {
      "required": [
        "method"
      ],
      "type": "object",
      "properties": {
        "method": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).",
          "enum": [
            "FBR",
            "FBB"
          ]
        },
        "deliveryCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "The delivery promise that applies to this offer. This value will only be used in combination with fulfilmentMethod 'FBR'.",
          "enum": [
            "24uurs-23",
            "24uurs-22",
            "24uurs-21",
            "24uurs-20",
            "24uurs-19",
            "24uurs-18",
            "24uurs-17",
            "24uurs-16",
            "24uurs-15",
            "24uurs-14",
            "24uurs-13",
            "24uurs-12",
            "1-2d",
            "2-3d",
            "3-5d",
            "4-8d",
            "1-8d",
            "MijnLeverbelofte",
            "VVB"
          ]
        },
        "profileId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Profile ID reference used for custom fulfillment options."
        }
      }
    },
    "NotPublishableReason": {
      "required": [
        "code",
        "description"
      ],
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code signalling that the offer is invalid."
        },
        "description": {
          "type": "string",
          "description": "Error message describing the reason the offer is invalid."
        }
      }
    },
    "OffersCountryCode": {
      "required": [
        "countryCode"
      ],
      "type": "object",
      "properties": {
        "countryCode": {
          "type": "string",
          "description": "Countries in which this offer is currently on sale in the webshop, in ISO-3166-1 format."
        }
      }
    },
    "Pricing": {
      "required": [
        "bundlePrices"
      ],
      "type": "object",
      "properties": {
        "bundlePrices": {
          "maxItems": 4,
          "minItems": 1,
          "type": "array",
          "description": "A set of prices (containing a quantity and selling price) that apply to this offer.",
          "items": {
            "$ref": "#/$defs/BundlePrice"
          }
        }
      }
    },
    "Stock": {
      "required": [
        "managedByRetailer"
      ],
      "type": "object",
      "properties": {
        "amount": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The amount of stock available for the specified product present in the retailers warehouse. Note: this should not be the FBB stock! Defaults to 0.",
          "format": "int32"
        },
        "correctedStock": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The amount of order items in stock minus handled order items and minus open order items. As compared to the stock you sent us. When this reaches 0, your offer will not be for sale on the shop.",
          "format": "int32"
        },
        "managedByRetailer": {
          "type": "boolean",
          "description": "Configures whether the retailer manages the stock levels or that bol.com should calculate the corrected stock based on actual open orders. In case the configuration is set to 'false', all open orders are used to calculate the corrected stock. In case the configuration is set to 'true', only orders that are placed after the last offer update are taken into account."
        }
      }
    },
    "Store": {
      "required": [
        "visible"
      ],
      "type": "object",
      "properties": {
        "productTitle": {
          "type": [
            "string",
            "null"
          ],
          "description": "The product title for the product associated with this offer."
        },
        "visible": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OffersCountryCode"
          }
        }
      }
    }
  }
}