Create a custom invoice provider

In Picqer, you can create a custom invoice provider (JSON Push). If an order hasn’t been invoiced yet, you can generate an invoice for it once an invoice provider has been configured.

You can create a custom invoice provider by clicking here.
On this page you have the button to connect a new invoice provider, here you can choose JSON push.

Pre-requisites

To configure the integration we need the following:

Name of the invoice provider
URL endpoint to create a invoice
Invoice URL prefix (for example: https://example.com/invoices/)
Authentication method via username and password

We currently only support HTTP Basic Auth for authentication. For the endpoints we currently only support HTTPS connections with TLS 1.1 or later.

Creating a invoice

Once the user has created the provider, they can use it to create a invoice.

When the user creates a invoice, we send a POST request to the URL you have provided. In this request you will receive details about the customer, order and products. We expect only an invoice identifier as a response

POST to for example:

POST https://example.com/picqer-integration/invoices

{ "customer": { "idcustomer": 999, "customerid": 1234, "name": "Klaas", "contactname": "", "address": "teststraat 5", "address2": "", "zipcode": "7891PG", "city": "Utrecht", "region": "", "country": "NL", "emailaddress": "test@example.com", "telephone": "", "vatnumber": null, "language": "nl" }, "order": { "idorder": 236652831, "orderid": "O2025-4045", "orderdate": "2025-12-17 10:36:09", "idpicklist": 166719038, "picklistid": "P2025-3036", "picklistclosedate": "2025-12-24T10:30:16.000000Z", "invoicename": "Klaas", "invoiceaddress": "teststraat 5", "invoiceaddress2": "", "invoicezipcode": "7891PG", "invoicecity": "Utrecht", "invoiceregion": "", "invoicecountry": "NL", "reference": "", "discountpercentage": 0, "calculatevat": true }, "products": [ { "productcode": "12345677", "name": "Stroopwafels", "remarks": null, "price": 5.99, "amount": 1, "vatpercentage": 21 } ] }

In you request above you will find all the information necessary to create an invoice

{ { "identifier": "Invoice123456" } }

In Picqer this identifier is used to let the user open the invoice via the invoice URL prefix provided in the configuration (for example: https://example.com/invoices/{invoiceIdentifier})

The processing of the request should take a maximum of 20 seconds, otherwise we will regard this invoice as failed.

Errored response

When you send an HTTP Status Code within the 4xx range, we will pick up the error message and show it to the user. You can do this in the format as follows:

{ "version": "1.0", "error_messages": [ "Unable to create a invoice because of an unknown productcode" ] }

Responses with a status code in the 5xx range will trigger a generic response in Picqer, this should not be used in regular circumstances.