Replenishments with Fulfillment by bol

The Replenishments API for Fulfillment by bol (FBB) creates shipments to the bol 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.

replenishments-process-updated

bol’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 warehouses on your behalf. For more information on this service, including the prices, see this article (Dutch and French). To arrange pickups through bol, see Creating replenishments via bol pickup service.

If you do not use the bol pickup service, you can arrange your own form of delivery and scheduling to the warehouse. See Creating your own replenishment delivery for more information. The process for creating a replenishment via the bol 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 pickup service message will result in an error.

Stock tracking

Get LVB/FBB 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 LVB/FBB 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 warehouse. See below for more information about sending new stock to the warehouse through the API.

Identifying product destinations by EAN

Since bol has multiple warehouses, you will need to identify which specific bol warehouse your products should go to before creating your replenishments. The following endpoints assist you in retrieving a list of product destinations by providing a list of EANs:

To identify which of your products should go to which bol warehouse:

  1. Use the endpoint Request product destinations to provide a list of EANs.

    A minimum of one and maximum of fifty EANs can be provided to this endpoint.

  2. Use the processStatusId from the response to retrieve the actual process status of your request.

  3. Once the operation of your request has been processed successfully, you will receive an entityId that is equal to the productDestinationsId.

  4. Retrieve the product destinations by providing the productDestinationsId as an input parameter to the Get product destinations by product destinations id.

  5. After retrieving the list of product destinations and having identified which product should go to which bol warehouse, you can create your replenishments accordingly.

Creating replenishments

Create a replenishment endpoint: Creates a new replenishment. This endpoint can be used to schedule both pickup and drop-off shipments using the fields pickupAppointment and deliveryInfo respectively.

Depending on whether you are using bol’s pickup service or not, you must only provide any one of the following parameters in the request body of this endpoint:

Creating replenishments via bol pickup service

To create replenishments using bol’s pickup service, you must provide the following parameters to this endpoint:

Do not use the deliveryInfo parameter if you are using the bol pickup service.

In case the specified pickup slot is not available, this endpoint returns the following error:

Requested pick up timeslot not available.

Scheduling pickup timeslots

The Post pickup time slots endpoint provides you a list of available timeslots that can be used to schedule a pickup collection via the bol pickup service. Enter your pickup address and the number of load carriers. You will receive back the list of available timeslots for collection, for upto 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 a replenishment request will automatically derive the fact that you are using pickup by bol from this field.

Adding the shipping labels for pickup

Using the bol 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 Get load carrier labels endpoint, and apply it to the load carrier for collection. Both labels are required.

Creating your own replenishment delivery

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

Do not use the pickupAppointment parameter if you are creating your own delivery.

In case the specified delivery date is not available, the Create a replenishment endpoint returns an error providing the next available dates. An example of the error message is shown below:

Requested delivery date currently not available. First available delivery dates for the selected shipment contents: 2022-07-28; 2022-07-29; 2022-08-01; 2022-08-02; 2022-08-03

Scheduling the delivery

Get delivery dates endpoint: Returns a list of available delivery windows for inbound shipments. The delivery window is the time when it can arrive at the bol warehouse.

Once you have received the list of available delivery windows from this call, you can schedule the shipment using the deliveryInfo.expectedDeliveryDate field in Create a replenishment endpoint.

Adding 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 the warehouse label using the Get 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 label your articles: If you choose this option you should send the goods without product labels and bol 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 Post 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 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 pickup service:

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

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

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.

Tracking 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 pickup service, the replenishment information will contain the pickupAppointment element.

Tracking replenishments invalid lines

The response from Get replenishments 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.

Tracking 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 or you change the replenishment details.

Updating replenishments

The Update a replenishment by replenishment id 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’s pickup service.

While updating the expected delivery date, if the specified delivery date is not available, the endpoint Update a replenishment by replenishment id notifies the available dates through an error message. An example of the error message is given below:

Requested delivery date currently not available. First available delivery dates for the selected warehouse and shipment contents: 2022-07-28; 2022-07-29; 2022-08-01

Cancelling the delivery

If the delivery is still in an announced state, it can still be cancelled by using the Update a replenishment by replenishment id 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 Update a replenishment by replenishment id 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 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 a replenishment by replenishment id endpoint.

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"
    }
  ]
}