Invoices

You can use the Invoices API to obtain details of your bol.com invoices. This allows you to:

  • Get an overview of your bol.com income and costs over a certain period.

  • Administer your bookkeeping.

The Invoices API does not import any details of your orders. For more information about those, see Orders and shipments.

How does invoicing work at bol.com?

Bol.com regularly issues a set of invoices to its partners, depending on their configuration and requirements:

  • A retailer invoice is sent out at the end of every month, except to certain partners who receive it twice a month. On this invoice we bundle the retailer’s income and costs for the period to calculate the net-payout for the period (excluding BRMG costs, see below). All of the retailer’s sales from the period are added together and their costs, such as commission and shipping labels, are subtracted. Please refer to the invoice type line table below for all the different line items that could be included on a retailer invoice.

  • The BRMG invoice is only applicable to partners who make use of bol.com’s advertising services. This invoice relates to the services rendered by the Bol.com Retail Media Group, who mostly perform marketing and advertising activities.

You can distinguish these two invoices by looking at the invoiceType field which can have the following values:

  • Retailer invoice: ALL_IN_ONE

  • BRMG invoice: BOL_RETAIL_MEDIA_GROUP

Settlement

If the amount to be received by the retailer as per the retailer invoice is higher than the amount to be paid, the to-be-paid invoice is settled against the to-be-received invoice. This amount can also be seen in the payableAmount field, which is owed by the retailer if the amount is positive, and owed to the retailer if the amount is negative. If the amount to be received is lower than the amount to be paid, the retailer needs to pay the invoice separately. Please note, no settlement will be done if the to-be-paid amount is higher than the to-be-received amount.

Invoices API

The demo endpoints show an example of the fields you would receive back from an invoice request.

The following endpoints are available for invoicing:

Field mapping for invoices

This image shows how the fields in bol.com invoices are used by the various endpoints.

Invoice mapping example

Retrieve all invoices

Returns a minimal summary of all invoices in a defined period of time. The default time is 4 weeks and the maximum is 32 days. This summary is a list and follows our pagination standards.

The following information is returned about every invoice:

  • Invoice ID

  • Issue date

  • Invoice type

  • Currency ID

  • Amount excluding VAT

  • Amount including VAT

  • Invoice media types

Retrieve an invoice by invoice id

Using the invoices-id from Retrieve all invoices, you can obtain a single detailed invoice. You can request this either in PDF - in which case it will be the same as the invoice from CashBoard - or in HTML/JSON format, in which case it will be sent in SI-UBL 1.1. format. This format is described on http://www.simplerinvoicing.org/ and is based on the larger specification UBL 2.1, which can be found at http://docs.oasis-open.org/ubl/UBL-2.1.html.

The invoices contain detailed information such as:

  • Information about bol.com and the retailer: Information such as the company name, address, KvK number, VAT scheme, and contact number.

  • Invoice totals: The total of the invoice, both including and excluding VAT.

  • Details about individual line items: The aggregated details of each type of retailer transaction is provided. This includes information such as the total amount (both including and excluding VAT) and a description of the line item. For a full specification of the different invoice line item types, please refer to the Invoice line details. Examples of line items include:

    • Turnover

    • Commission

    • Packaging costs

    • Delivery costs

Retrieve an invoice specification by invoice id

This provides the details of all transactions that are included within a specific invoice. Examples of the information in specifications include:

Field Full field name Additional information

Invoice number

InvoiceLineRef

Please note the invoice number and the description are split with a #.

Order ID

Item.AdditionalItemProperty.name<OrderId>.value

Description of transaction

item.description.value

EAN of product sold

AdditionalItemProperty.Name<EAN>.value

Only applicable for costs charged on a product level.

Track and trace number

AdditionalItemProperty.Name<TrackandTrace>.value

Only applicable for logistics services.

Quantity

InvoicedQuantity

VAT amount

TaxTotal.value

Price

Price.PriceAmount.value

Invoice line details

The following are the types of line items you can see on an invoice:

BRMG invoice

Invoice line type Explanation

SPONSORED_PRODUCTS

Costs for sponsored products on the bol.com website.

SPONSORED_PRODUCTS_CORRECTION

Cost correction for sponsored products on the bol.com website.

SPONSORED_PRODUCTS_DISCOUNT

Discounts on costs for sponsored products on the bol.com website.

ONLINE_MAGAZINES

Costs to include advertisements in an online magazine.

ONLINE_MAGAZINES_CORRECTION

Cost corrections to include advertisements in an online magazine.

ONLINE_MAGAZINES_DISCOUNT

Discounts on costs relating to advertisements in an online magazine.

DAY_OFFER_BOOSTER

Costs to include a daily offer on the website.

DAY_OFFER_BOOSTER_CORRECTION

Corrections of costs to include a daily offer on the website.

DAY_OFFER_BOOSTER_DISCOUNT

Discounts on costs to include a daily offer on the website.

DISPLAY_ONSITE

Costs for a banner on the bol.com website.

DISPLAY_ONSITE_CORRECTION

Correction for costs for a banner on the bol.com website.

DISPLAY_ONSITE_DISCOUNT

Discounts on costs for a banner on the bol.com website.

DISPLAY_OFFSITE

Costs for a banner on a third party’s website.

DISPLAY_OFFSITE_CORRECTION

Correction for costs for a banner on a third party’s website.

DISPLAY_OFFSITE_DISCOUNT

Discounts on costs for a banner on a third party’s website.

SOCIAL_ADVERTISING

Costs for advertising on social media.

SOCIAL_ADVERTISING_CORRECTION

Correction of costs for advertising on social media.

SOCIAL_ADVERTISING_DISCOUNT

Discounts on costs for advertising on social media.

PROMO_BOOSTER_PLUS

Costs for a specific promotion.

PROMO_BOOSTER_PLUS_CORRECTION

Correction of costs for a specific promotion.

PROMO_BOOSTER_PLUS_DISCOUNT

Discounts on costs for a specific promotion

PROMO_BOOSTER_PLUS_HALF

Costs for a specific promotion.

PROMO_BOOSTER_PLUS_HALF_CORRECTION

Correction of costs for a specific promotion.

PROMO_BOOSTER_PLUS_HALF_DISCOUNT

Discounts on costs for a specific promotion.

Retailer invoice

Invoice line type Explanation

COMMISSION

Commission for an article sold and shipped.

CORRECTION_COMMISSION

Correction of initially charged commission.

COMPENSATION

Compensation.

COMPENSATION_LOST_GOODS

Compensation for lost items.

FIRST_MILE

Costs for pick-up of inventory into the bol.com warehouse (FBB).

CORRECTION_FIRST_MILE

Correction of initially charged first mile costs (FBB).

LOGISTICAL_CHARGE

Costs for either: labeling incoming inventory, orders to destroy inventory, or sending back unsellable inventory (FBB).

NCK_STOCK

Costs for not-saleable-inventory (FBB).

OUTBOUND

Costs for an FBB shipment.

CORRECTION_OUTBOUND

Correction of initially charged outbound.

PICK_PACK

Picking & packing costs (FBB).

CORRECTION_PICK_PACK

Correction on initially charged pick & packing costs (FBB).

PLAZA_RETURN_SHIPPING_LABEL

Costs for a return label.

CORRECTION_PLAZA_RETURN_SHIPPING_LABEL

Correction of initially charged return labels.

RETAILER_AUTHORIZATION

Costs for authorization of brands.

CORRECTION_RETAILER_AUTHORIZATION

Correction of initially charged retailer authorization.

SHIPMENT_LABEL

Costs for a shipping label.

CORRECTION_SHIPMENT_LABEL

Correction of initially charged shipment labels.

SHIPMENT_LABEL_POST

Costs for a shipping label from PostNL. PostNL is VAT-exempt and all other transporters have the standard high Tax rate.

CORRECTION_SHIPMENT_LABEL_POST

Correction of initially charged PostNL labels.

STOCK

Costs that are made for your inventory (FBB).

TURNOVER

Price of the item you sold and shipped.

CORRECTION_TURNOVER

Correction on turnover in case of a return.

CORRECTION_CORRECTION*

This can be due to a wide variety of reasons. Some possible examples are: NCO (Non Commercial Order), URO (Unsellable Return Order), bSKU labelling, or stock corrections.

(*) This invoice line is not used anymore today but may still appear in older invoices.