Invoices

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

  • Get an overview of your bol 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?

bol 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 Avb costs, see below). All 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 Avb invoice is only applicable to partners who utilize the advertising services of bol. This invoice relates to the services provided by Advertising via bol, which primarily engages in marketing and advertising activities.

By examining the invoiceType field, which can take one of the following values, you can distinguish these two invoices apart:

  • ALL_IN_ONE - Specifies the retailer’s invoice.

  • ADVERTISING_VIA_BOL - Specifies the Avb invoice.

From v9 of the Retailer API onward, the invoice type BOL_RETAIL_MEDIA_GROUP (BRMG) is renamed to ADVERTISING_VIA_BOL (Avb).

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 invoices are used by the various endpoints.

Invoice mapping example

Retrieving all invoices

Get 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

Retrieving an invoice by invoice id

Get an invoice by invoice id

Using the invoices-id from Get 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 2.1 format. This format is described on at http://docs.oasis-open.org/ubl/UBL-2.1.html.

The invoices contain detailed information such as:

  • Information about bol 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

Retrieving an invoice specification by invoice id

Use the Get an invoice specification by invoice id endpoint to retrieve an invoice specification with a paginated list of transactions. It retrieves the details of the retailer and Avb invoices through the invoices-id. It provides details of all the transactions within an invoice in the JSON or Excel format for up to 2 years in the past.

The invoice specification can be classified into the following categories:

  • dealType - Specifies a mandatory reference type for each transaction within the invoice specification.

    The supported dealType references are mentioned below:

    Table 1. Supported deal type references
    Type of invoice Supported deal type references

    Avb Invoices

    • Campagnenaam

    Retailer Invoices

    • Bestelnummer

    • Track and Trace

    • Product titel

    • Collectie referentie

    • Paklijst referentie

    • Casenummer

    • Toelichting

    For example, if an order has been shipped through the VvB service, the invoice specification will exhibit the following transactions detailing the financial break-up of the order:

    • TURNOVER

    • COMMISSION

    • DISTRIBUTION_BY_BOLCOM_LABEL

    In this case, the dealType for the TURNOVER and COMMISSION transaction will be the Bestelnummer. The dealType of the DISTRIBUTION_BY_BOLCOM_LABEL transaction will be the Track and Trace.

  • dealDetailsType - Specifies an optional reference type that provides a deeper level of categorization for the transactions in the invoice specification.

    The supported dealDetailsType references are mentioned below:

    Table 2. Supported deal details type references
    Type of invoice Supported deal details type references

    Avb Invoices

    • ON-number

    Retailer Invoices

    • EAN

    In the aforementioned example, dealDetailsType for the TURNOVER and COMMISSION transaction will be the EAN. The DISTRIBUTION_BY_BOLCOM_LABEL transaction will have no dealDetailsType available since the only supported dealDetailsType, EAN is not applicable to the transaction.

An invoice specification details the following information for each of its transaction:

Property Name Field name Category Description

Invoice number

InvoiceLineRef

N/A

Specifies the transactions belonging to a certain invoice line. For example, all TURNOVER transactions in an invoice specification will have an identical InvoiceLineRef and will be represented by a concatenation of the invoice number and the transaction type. The total sum of the amounts correspond to the invoice line amount for that particular transaction type.

NOTE: The invoice number and the description are split with a # symbol.

Order ID

Item.AdditionalItemProperty.name<Bestelnummer>.value

dealType

Specifies the order number linked to the transaction.

NOTE: Applicable only for order related transactions. For example, TURNOVER and COMMISSION transactions.

Description of transaction

item.description.value

N/A

Specifies the transaction type in Dutch.

Track and Trace number

AdditionalItemProperty.Name<TrackandTrace>.value

dealType

Specifies the track and trace number.

NOTE: Applicable only for logistic services. For example, all shipment label transactions such as RETURN_SHIPMENT_LABEL, SHIPMENT_LABEL, DISTRIBUTION_BY_BOLCOM_LABEL.

Product title

AdditionalItemProperty.Name<Product titel>.value

dealType

Specifies the product title used to list the product on the bol.

NOTE: Applicable only for inbounds and stock services.

Collection reference

AdditionalItemProperty.Name<Collectie referentie>.value

dealType

Specifies the collection reference linked to the transaction.

NOTE: Applicable only when VvB collection services are used.

Delivery ID

AdditionalItemProperty.Name<Paklijst referentie>.value

dealType

Specifies the delivery ID linked to the transaction.

NOTE: Applicable only for first mile services.

Case number

AdditionalItemProperty.Name<Casenummer>.value

dealType

Specifies the case number linked to the transaction.

NOTE: Applicable only for compensations.

Remark

AdditionalItemProperty.Name<Toelichting>.value

dealType

Specifies the remark mentioned in the transaction.

NOTE: Applicable only for manual corrections.

EAN of product sold

AdditionalItemProperty.Name<EAN>.value

dealType

Specifies the EAN number linked to the transaction.

NOTE: Applicable only for costs charged on a product level.

Campaign name (Avb)

AdditionalItemProperty.Name<Campagnenaam>.value

dealType

Specifies the actual campaign name in which the advertising costs were incurred. Available for all advertising transactions.

NOTE: Applicable only for Avb invoices.

ON-number (Avb)

dealDetailsType

Specifies which transactions belong to which display campaigns.

NOTE: Applicable only for Avb invoices.

Quantity

InvoicedQuantity

N/A

Specifies the invoiced quantity in the transaction.

Price

Price.PriceAmount.value

N/A

Specifies the total price excluding VAT.

VAT amount

TaxTotal.value

N/A

Specifies the total price including VAT.
The properties belonging to dealType category will not be reflected in all transactions.

Invoice line details

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

Avb invoice

Invoice line type Explanation

SPONSORED_PRODUCTS

Costs for sponsored products on the bol website.

SPONSORED_PRODUCTS_CORRECTION

Cost correction for sponsored products on the bol website.

SPONSORED_PRODUCTS_DISCOUNT

Discounts on costs for sponsored products on the bol 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 website.

DISPLAY_ONSITE_CORRECTION

Correction for costs for a banner on the bol website.

DISPLAY_ONSITE_DISCOUNT

Discounts on costs for a banner on the bol 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 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.