Replenishments with Fulfillment By Bol.com

The Replenishments API for Fulfillment by Bol.com (FBB) creates shipments to the bol.com warehouse and retrieves information on the status of your shipment. This ensures that your stock levels are managed, and handles the shipment of your inventory to our warehouse for the products that you want to sell through the FBB network.

V5 of the Replenishments API (previously the Inbounds API) featured significant design improvements and will require users on v4 to redesign their API integration. It is therefore out of scope of a standard migration guide.

Any Replenishments (Inbound shipments) in v4 that are currently in the Draft state will not be retrieved in v6, since Replenishments in v6 start in the Announced state. We recommend completing your existing inbound orders before using the v6 Replenishments. If you move to v5 or v6 before updating your inbound orders, you should create new Replenishments in v6 for them to ensure they are properly handled.

replenishments process

bol.com’s pickup service

The bol.com pickup service with PostNL for FBB is a value-added proposition where we arrange the collection of your packages to our distribution centers on your behalf. For more information on this service, including the prices, see this article. To arrange pickups through bol.com, see Create replenishments via bol.com pickup service.

If you do not use the bol.com pickup service, you can arrange your own form of delivery and scheduling to the warehouse. See Create your own replenishment delivery for more information. The process for creating a replenishment via the bol.com pickup service has some common elements with creating your own replenishment, but there are key differences that should be observed. For example, attempting to use the transporterCode in a bol.com pickup service message will result in an error.

Stock tracking

Retrieve inventory endpoint: returns the current inventory levels in the warehouse.

The first step of inventory management begins when you are notified that your stock needs to be replenished. This will happen through another resource, such as the GET Inventory endpoint. For example, the stock parameter with value INSUFFICIENT will return all of your FBB inventory where the regular stock level is 0.

Graded stock in the warehouse has been rated by us as unsellable. For more information on managing these items, see Unsellable stock (Dutch).

Replenishing stock

The Replenishments API endpoints manage the process of replenishing your stock at the bol.com distribution centre. See below for more information about sending new stock to the warehouse through the API.

Create replenishments

Create replenishment endpoint: creates a new replenishment. The information you supply here can be obtained with the use of other endpoints, detailed below.

Depending on whether you are using bol.com’s pickup service, you should supply the following details:

Create replenishments via bol.com pickup service

To use the bol.com pickup service, you must provide the following parameters:

  • reference

  • labelingByBol: For more information, see Product labels

  • numberOfLoadCarriers: For more information, see Load carriers

  • pickupAppointment and pickupTimeSlot: For more information, see Pickup timeslots.

  • lines

You should not use the deliveryInfo fields.

Pickup timeslots

The Pickup timeslots endpoint is used to schedule a pickup collection via the bol.com pickup service. Enter your pickup address and the number of load carriers. You will receive back the list of available timeslots for collection, for three days into the future.

Once you know your timeslot, you can supply it in the body of the replenishment when you create it using the pickupTimeSlot field. The Create replenishment request will automatically derive the fact that you are using Pickup by bol.com from this field.

Add the shipping labels for pickup

Using the bol.com pickup service requires you to use both the Transport and Load carrier labels. Once you have a replenishmentId, you can use it to generate a Transport label and a Warehouse label using the Load carrier labels endpoint, and apply it to the load carrier for collection. Both labels are required.

Create your own replenishment delivery

To create your own delivery, you must provide the following parameters:

  • reference

  • deliveryInfo (with transporterCode and expectedDeliveryDate)

  • labelingByBol: For more information, see Product labels

  • numberOfLoadCarriers: For more information, see Load carriers

  • lines

You should not use the pickupAppointment fields.

Add the shipping label for delivery

Creating your own replenishment only requires you to use a Warehouse label. Once you have a replenishmentId, you can use it to generate a Warehouse label using the Load carrier labels endpoint, and apply it to the load carrier for delivery.

Product labels

Product labels are identified per EAN and used to sort and manage your goods in the warehouse. For more information, see Label your articles (Dutch). There are two possible options for product labelling, indicated by the labelingByBol field in the replenishments order:

  1. Let bol.com label your articles: If you choose this option you should send the goods without product labels and bol.com will apply them at the warehouse. This option has an associated cost, which can be found in the related article.

  2. Print them yourself: Use the Retrieve replenishment product labels endpoint to fetch the labels for your packages. See Label your articles for some guidelines about self-labelling. It is important to label items correctly, or there is a risk of them being incorrectly scanned at the warehouse.

Load carriers

A load carrier is a single parcel or pallet with which you are delivering items to bol.com warehouse. If you are delivering on pallets, the number of load carriers should be the number of pallets. If you are delivering with parcels, the number of load carriers should be the number of parcels.

The maximum number of load carriers per shipment is different depending on whether you are using the bol.com pickup service:

  • If you are using the bol.com pickup service, the maximum number is 20

  • If you are creating your own replenishment, the maximum number is 50.

To update the load carriers in a replenishment, see Changing the number of load carriers.

Packing your goods

Get pick list endpoint: returns the packing list for the replenishment.

The PDF you receive from this endpoint is used to confirm that you have correctly packed the items in your shipment.

Track replenishments

The following endpoints allow you to view and track your replenishments:

The single replenishment endpoint provides slightly more detailed feedback on an item than the replenishments endpoint. For example, the stockLevel is only provided in the single replenishment.

If you are using bol.com pickup service, the replenishment information will contain the pickupAppointment element.

Track replenishments invalid lines

The response for GET Replenishment(s) includes the invalidLines element which lists the product lines that could not be verified. There are two possible scenarios with their own error messages:

  • UNKNOWN_FBB_PRODUCT: If you send a shipment to the warehouse that includes items that were not previously pre-announced, and the warehouse has not yet created a listing for them, they will return this error.

  • UNKNOWN_EAN_INVENTORY_RELATION: If we were unable to map the product to an EAN, they will return this error.

We will not expose the EANs in the payload. To resolve your invalid replenishment lines, you should contact Partner Service to assist you to analyze these cases.

Updates on status transitions

You can periodically check the GET Replenishments endpoint to view the status of your shipment. The API updates asynchronously and will change whenever either bol.com or you change the replenishment details.

Updating replenishments

The PUT replenishment endpoint updates the details of a replenishment. You can perform the following actions on an existing replenishment:

Updating the expected delivery date

The expected delivery date can only be changed for replenishments that do not use bol.com’s pickup service. Use the Pickup time slots endpoint to find a valid list of dates.

Cancelling the delivery

If the delivery is still in an Announced state, it can still be cancelled by using the Put replenishment endpoint to change the state to Cancelled.

  • Once it is In transit (or older than the changeable time period), it can no longer be cancelled.

  • Once a replenishment has been cancelled, it can no longer be updated and you must create a new replenishment if you wish to send it again.

Changing the number of load carriers

You can change the number of load carriers through the Put replenishment endpoint. If you increase the amount of load carriers, you only need to supply the new number of load carriers.

Your provided number of load carriers must always be greater than the current amount of load carriers in the replenishment. If you provide a lesser amount, bol.com will automatically assume that you want to decrease the amount of load carriers.

If you want to decrease the amount of load carriers, you should resupply the SSCC codes of the load carriers you want to keep. The SSCC codes can be obtained from the Get replenishments or Get replenishment endpoint. An

Example 1. Decreasing the amount of load carriers to 2 for a replenishment that has currently 3 SSCCs in it
{
  "numberOfLoadCarriers": 2,
  "loadCarriers": [
    {
      "sscc": "100000010000000013"
    },
    {
      "sscc": "020001200000007710"
    }
  ]
}