Offer API use case guide

This API is currently in beta. If you have any questions or remarks that can improve this API, mail us at retailerapi-beta@bol.com. Updates to this beta will be communicated via our developers portal.

This guide shows common use case examples.

Create a single offer

Create an offer by using this endpoint.

Use case 1: Create a Fulfilment By Bol (FBB) offer

This example creates a fulfilment by bol (fbb) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is handled by bol.

{
  "ean": "4015211100803",
  "condition": {
    "category": "NEW"
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 4.99
      }
    ]
  },
  "countryAvailabilities": [
    {
      "countryCode": "NL"
    }
  ],
  "fulfilment": {
    "method": "FBB"
  }
}

Use case 2: Create a Fulfilment By Retailer (FBR) refurbished offer

This example creates a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a refurbished product with grade A.
One single price applies (no volume discount).
For sale in the Netherlands and Belgium.
The fulfilment is handled by the retailer itself, using a delivery promise defined by bol (within 24-hour; if ordered before 10 PM)
With a stock level of 5.
Where the stock levels are managed by bol.

{
  "ean": "4015211100803",
  "condition": {
    "category": "REFURBISHED",
    "grade": "A",
    "margin": false
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 9.99
      }
    ]
  },
  "countryAvailabilities": [
    {
      "countryCode": "NL"
    },
    {
      "countryCode": "BE"
    }
  ],
  "fulfilment": {
    "method": "FBR",
    "schedule": "BOL_DELIVERY_PROMISE",
    "deliveryPromise": {
      "minimumDaysToCustomer": 0,
      "maximumDaysToCustomer": 1,
      "ultimateOrderTime": "22:00"
    }
  },
  "stock": {
    "amount": 5,
    "managedByRetailer": false
  }
}

Use case 3: Create a Fulfilment By Retailer (FBR) second hand offer

This example creates a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a second hand product with a product state that is as good as new.
With volume discount in case the customer buys at least 2 quantities.
For sale in Belgium only.
The fulfilment is handled by the retailer itself, using its own defined delivery schedule.
With a stock level of 2.
Where the stock levels are managed by the retailer itself.

{
  "ean": "4015211100803",
  "condition": {
    "category": "SECONDHAND",
    "state": "AS_NEW",
    "comment": "An optional comment. If you don't want to include a comment, you can omit this field entirely."
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 9.99
      },
      {
        "quantity": 2,
        "unitPrice": 4.99
      }
    ]
  },
  "countryAvailabilities": [
    {
      "countryCode": "BE"
    }
  ],
  "fulfilment": {
    "method": "FBR",
    "schedule": "MY_DELIVERY_PROMISE"
  },
  "stock": {
    "amount": 2,
    "managedByRetailer": true
  }
}

Use case 4: Create a Fulfilment By Retailer (FBR) offer using shipping via bol

This example creates a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is done via shipment via bol.
With a stock level of 44.

{
  "ean": "4015211100803",
  "condition": {
    "category": "NEW"
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 9.99
      }
    ]
  },
  "countryAvailabilities": [
    {
      "countryCode": "NL"
    }
  ],
  "fulfilment": {
    "method": "FBR",
    "schedule": "SHIPPING_VIA_BOL"
  },
  "stock": {
    "amount": 44,
    "managedByRetailer": false
  }
}

Retrieve a single offer

Retrieve a single offer by using this endpoint.

Use case 1: Retrieve an FBB offer

This example retrieve a fulfilment by bol (fbb) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is handled by bol.
Has a stock level of 10 quantities and a corrected stock level of 8 (meaning there are currently 2 orders pending with both a quantity of 1).

{
  "offerId": "6f9478d7-2b2f-4156-b694-758506a3fdcc",
  "ean": "4015211100803",
  "lastModifiedDateTime": "2025-10-14T09:09:43.904312+02:00",
  "onHoldByRetailer": false,
  "stock": {
    "amount": 10,
    "correctedStock": 8,
    "managedByRetailer": false
  },
  "countryAvailabilities": [
    {
      "countryCode": "NL",
      "forSale": true
    }
  ],
  "condition": {
    "category": "NEW"
  },
  "product": {
    "bolProductId": "9200000066291279"
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 9.99
      }
    ]
  },
  "fulfilment": {
    "method": "FBB"
  }
}

Use case 2: Retrieve a refurbished FBR offer

This example retrieve a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a refurbished product with grade C.
One single price applies (no volume discount).
For sale in the Netherlands and Belgium.
The fulfilment is handled by the retailer itself, using a delivery promise defined by bol (within 24-hour; if ordered before 10 PM).
Has a stock level of 5 and no current pending orders.

{
  "offerId": "11561569-24c9-470e-9f81-d32e3500c64b",
  "ean": "4015211100803",
  "lastModifiedDateTime": "2025-10-14T09:14:04.101703+02:00",
  "onHoldByRetailer": false,
  "stock": {
    "amount": 5,
    "managedByRetailer": false
  },
  "countryAvailabilities": [
    {
      "countryCode": "NL",
      "forSale": true
    },
    {
      "countryCode": "BE",
      "forSale": true
    }
  ],
  "condition": {
    "category": "REFURBISHED",
    "grade": "C",
    "margin": false
  },
  "product": {
    "bolProductId": "9200000066291279"
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 9.99
      }
    ]
  },
  "fulfilment": {
    "method": "FBR",
    "schedule": "BOL_DELIVERY_PROMISE",
    "deliveryPromise": {
      "minimumDaysToCustomer": 0,
      "maximumDaysToCustomer": 1,
      "ultimateOrderTime": "22:00"
    }
  }
}

Use case 3: Retrieve a secondhand FBR offer

This example retrieve a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a second hand product with a product that is in a good condition.
With volume discount in case the customer buys at least 2 quantities.
For sale in Belgium only.
The fulfilment is handled by the retailer itself, using its own defined delivery schedule.
Has a stock level of 2 and currently 1 pending order with a quantity of 1.

{
  "offerId": "f90ac33c-2e7a-43cb-83e5-378afc9a40de",
  "ean": "4015211100803",
  "lastModifiedDateTime": "2025-10-14T09:16:04.181827+02:00",
  "onHoldByRetailer": false,
  "stock": {
    "amount": 2,
    "correctedStock": 1,
    "managedByRetailer": false
  },
  "countryAvailabilities": [
    {
      "countryCode": "BE",
      "forSale": true
    },
    {
      "countryCode": "NL",
      "forSale": false
    }
  ],
  "condition": {
    "category": "SECONDHAND",
    "comment": "An optional comment. If you don't want to include a comment, you can omit this field entirely.",
    "state": "GOOD"
  },
  "product": {
    "bolProductId": "9200000066291279"
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 9.99
      },
      {
        "quantity": 2,
        "unitPrice": 4.99
      }
    ]
  },
  "fulfilment": {
    "method": "FBR",
    "schedule": "MY_DELIVERY_PROMISE"
  }
}

Use case 4: Retrieve an FBR offer using shipping via bol

This example retrieve a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is done via shipment via bol.
Has a stock level of 44 and no current pending orders.

{
  "offerId": "efb32ecb-5d06-42ca-a812-3ad29619cf73",
  "ean": "4015211100803",
  "lastModifiedDateTime": "2025-10-14T09:18:02.455809+02:00",
  "onHoldByRetailer": false,
  "stock": {
    "amount": 44,
    "managedByRetailer": false
  },
  "countryAvailabilities": [
    {
      "countryCode": "NL",
      "forSale": true
    }
  ],
  "condition": {
    "category": "NEW"
  },
  "product": {
    "bolProductId": "9200000066291279"
  },
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 9.99
      }
    ]
  },
  "fulfilment": {
    "method": "FBR",
    "schedule": "SHIPPING_VIA_BOL"
  }
}

Update a single offer

Update an offer by using this endpoint.

Use case 1: Set your offer on hold (pause offer)

You can pause your offer by sending the following payload

{
  "onHoldByRetailer": true
}

Use case 2: Remove a previous set field value

{
  "reference": null
}

Use case 3: Update the economic operator and set a reference

{
  "economicOperatorId": "0c6573a2-a80c-48b7-a03e-d5939f1173fa",
  "reference": "This is my new reference"
}

Use case 4: Put your offer for sale in both NL and BE

{
  "countryAvailabilities": [
    {
      "countryCode": "BE"
    },
    {
      "countryCode": "NL"
    }
  ]
}

Use case 5: Put your offer for sale in countries based on your account setting

{
  "countryAvailabilities": null
}

Use case 6: Update the price of your offer

Update your offer to set the unitPrice to 4.99 euro in case the customer buys a quantity of 1.

{
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 4.99
      }
    ]
  }
}

Update your offer to set the unitPrice to 8.99 euro in case the customer buys a quantity of 1 and 7.99 in case the customer buys a quantity of 2.

{
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 8.99
      },
      {
        "quantity": 2,
        "unitPrice": 7.99
      }
    ]
  }
}

Use case 7: Update your stock levels for an (FBR) offer

Update your stock level for this offer to 8.

{
  "stock": {
    "amount": 8
  }
}

Use case 8: Update your price and stock levels for an (FBR) offer

Update your stock level for this offer to 12 and set a unit price of 7.99 and manage the stock levels yourself.

{
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 7.99
      }
    ]
  },
  "stock": {
    "amount": 12,
    "managedByRetailer": true
  }
}

Use case 9: Update your price, stock levels and fulfilment for an FBR offer

The following scenario updates:

Your stock level for this offer to 12.
Your unit price to 7.99 when a customer buys 1 item and 6.99 when a customer buys 3 items.
The fulfilment schedule to my custom created calendar. In this scenario, the current offer was already an FBR offer.

{
  "pricing": {
    "bundlePrices": [
      {
        "quantity": 1,
        "unitPrice": 7.99
      },
      {
        "quantity": 3,
        "unitPrice": 6.99
      }
    ]
  },
  "fulfilment": {
    "method": "FBR",
    "schedule": "MY_DELIVERY_PROMISE"
  },
  "stock": {
    "amount": 12
  }
}

Use case 10: Switch an FBB offer to an FBR offer

The following scenario:

Switches your offer to an FBR offer while it was previously set as an FBB offer.
With a stock level of 12.
The fulfilment is handled by the retailer itself, using a delivery promise defined by bol (within 24-hour; if ordered before 6 PM)

{
  "fulfilment": {
    "method": "FBR",
    "schedule": "BOL_DELIVERY_PROMISE",
    "deliveryPromise": {
      "minimumDaysToCustomer": 0,
      "maximumDaysToCustomer": 1,
      "ultimateOrderTime": "18:00"
    }
  },
  "stock": {
    "amount": 12,
    "managedByRetailer": false
  }
}

Use case 11: Switch an FBR offer to an FBB offer

The following scenario:

Switches your offer to an FBB offer while it was previously set as an FBR offer.

{
  "fulfilment": {
    "method": "FBB"
  }
}

Delete a single offer

Delete an offer by using this endpoint.

Deleting an offer does not require a payload. The offerId is part of the path parameter.

Get not for sale reasons

Get not for sale reasons by using this endpoint.

Use case 1: NL offer that is currently not for sale

The following response is an offer that is only sold in the Netherlands (countryCode = NL) and is offline due to missing Dutch product content. Specifically for code equal to 4004-2 the missingAttributes array is added, to know what specific attributes are missing.

{
  "offerId": "ffccfa1f-1360-43c9-a9d7-b457c9d2b949",
  "countries": [
    {
      "countryCode": "NL",
      "reasons": [
        {
          "category": "CONTENT",
          "code": "4004-2",
          "description": "This offer is offline because mandatory product attributes (content) in Dutch are missing.",
          "missingAttributes": [
            {
              "name": "Manufacturer Address"
            },
            {
              "name": "Manufacturer Email"
            }
          ]
        }
      ]
    }
  ]
}

Use case 2: NL and BE offer that are both currently not for sale

The following response is an offer that is sold in the Netherlands (countryCode = NL) and Belgium (countryCode = BE), but the offer is offline in both countries because there is no stock available anymore.

{
  "offerId": "ffccfa1f-1360-43c9-a9d7-b457c9d2b949",
  "countries": [
    {
      "countryCode": "NL",
      "reasons": [
        {
          "category": "STOCK",
          "code": "4003-3",
          "description": "This offer is offline because there is no more stock left to fulfil a potential future order."
        }
      ]
    },
    {
      "countryCode": "BE",
      "reasons": [
        {
          "category": "STOCK",
          "code": "4003-3",
          "description": "This offer is offline because there is no more stock left to fulfil a potential future order."
        }
      ]
    }
  ]
}

Use case 3: NL and BE offer that is partially for sale

The following response is an offer that is sold in the Netherlands (countryCode = NL) and Belgium (countryCode = BE), but that is only for sale in the Netherlands, but not for sale in Belgium.

{
  "offerId": "ffccfa1f-1360-43c9-a9d7-b457c9d2b949",
  "countries": [
    {
      "countryCode": "BE",
      "reasons": [
        {
          "category": "SELLING_RIGHTS",
          "code": "3000-1",
          "description": "This offer is offline because selling rights apply to this product."
        }
      ]
    }
  ]
}

Use case 4: NL and BE offer that is for sale in both countries

When an offer is for sale in both the Netherlands (countryCode = NL) and Belgium (countryCode = BE), you will receive a 204 No content.