Customer invoices

Invoices document the exchange of goods and services between customers and sellers. An invoice serves as proof of the transaction and provides a list of the goods sold or services rendered along with their price.

It contains detailed information about the sale such as price paid for the products, date and time of the sale, product details, billing and shipment details including the VAT registration number of the provider. Invoices act as a helpful record-keeping tool thereby offering ease of administration.

This functionality allows you to easily provide shipment specific invoices to your customers.

For more information on the invoicing process and sample invoices (Dutch and French), see Factuur zakelijk klanten on Partnerplatform.

How can it help?

These endpoints help you:

  • Proactively upload invoices for each shipment directly into the customer’s account.

  • Automate the processing of all the incoming invoice requests from the customers.

  • Streamline the process of requesting invoices for customers thereby increasing customer satisfaction.

  • Minimize manual effort.

Process flow

The following image shows the process flow for this functionality and how to use the provided endpoints efficiently:

process flow diagram Customer invoices
Figure 1. Process flow diagram for customer invoicing

The following two methods can be used to upload an invoice:

  1. Proactively uploading an invoice for a shipment - This approach allows you to automate your invoicing process and upload an invoice proactively for every shipment. It facilitates a seamless experience for business customers towards the invoicing process.

  2. Responding to an invoice request from a customer - This approach allows you to respond to an invoice request from a customer and process it by uploading an invoice per shipment.

Retrieving and uploading customer invoices

This functionality offers you the following endpoints:

To successfully upload a customer invoice, perform the following steps:

1. Obtaining the shipment ID

  1. Use the Get shipment list endpoint to determine the shipment ID based on the order-id.

For more information on how to retrieve shipments, see Get shipments list.

Customers anticipate invoices per shipment. Hence, it is imperative that invoices are uploaded per shipment rather than per order.

2. Retrieving the invoice requests

  1. Use the Get a list of invoice requests endpoint to retrieve a list of all the open and handled invoice requests from customers in a paginated format.

  2. Specify the shipment-id as an input parameter to get all the invoice request details about a specific shipment.

  3. Specify the filtering option for the invoice request. It offers the following categories to filter your invoice requests:

    • OPEN - Retrieves all invoice requests that are yet to be processed.

    • UPLOAD_ERROR - Retrieves all invoice requests for which the invoice upload was unsuccessful due to virus detection.

    • ALL (default) - Retrieves all invoice requests and shipments having an uploaded invoice.

  4. In the response, this endpoint offers you the following details:

    • Shipment ID.

    • Order ID.

    • Customer’s account number.

    • Customer’s billing details.

    • VAT number.

    • KVK number.

    • Details of the product ordered.

    • Current status of the invoice request:

      • INVOICE_INCORRECT

      • INVOICE_REQUESTED

      • INVOICE_UPLOADED

      • INVOICE_VIRUS_DETECTED

      • FINISHED

    • History of each status, including the time and date.

Customers can request an invoice for upto two years in the past from the current date.

3. Uploading the invoices

  1. Use the Upload an invoice for shipment id endpoint to upload the invoice file for a shipment.

  2. In the response, the processStatusId is returned by this endpoint.

While working with this endpoint, consider the following:

  • While uploading the invoice ensure:

    • The file is of the PDF format.

    • The file size is not bigger than 2 MB.

    • The shipment ID is valid.

    • The shipment ID has no invoice uploaded already.

  • The invoices for business customers must include the KVK/VAT number if it is listed in the billing information.

  • A multiline order spilt in two shipments requires two separate invoice uploads.

  • Proactive uploading of invoices is only possible through the API, not in SDD.

  • The deletion of an uploaded invoice is only possible in SDD, not through the API.

  • The invoice must be provided as per the language of the customers in their country. For example, an invoice for customers in France must be in French.

  • To ensure successful uploading of an invoice, it is essential that your request complies with the standard multipart/form-data conventions, including the inclusion of the multipart boundary string. If you are utilizing an HTTP library, the addition of the boundary string to the request will be handled automatically.

    An example of a request that utilizes the multipart/form-data format with the boundary parameter can be found here.

4. Retrieving process status

  1. Use the processStatusId from the response as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the actual processing status of your request.

    For more information on the Process Status endpoint, see the Process Status documentation.

5. Verifying the status of the uploaded invoice

  1. Use the Get a list of invoice requests endpoint to view the current status of the upload. This step checks if a virus was detected during the upload of the invoice file.

    In the event of virus detection during the initial upload, attempt to upload the invoice file again using the Upload an invoice for shipment id endpoint.

For more information on the request and response body of these endpoints, see the Redoc.