QR Invoice REST API (2.0)
The QR Invoice REST API provides various services for creation and processing of Swiss QR Invoices. This API is available as a Cloud Service but is also available as a self-hosted solution.
Product Website
www.qr-invoice.chAPI Key
This API requires an API Key for authorization on the Cloud. You may use the following Demo API Key or request a trial API on our website: QrInvoice - Order Trial Key582c9ea9-741a-4bb6-acae-cf92f8805864
Important: Use of Demo API Key comes with a few restrictions!
Hints
- Please note, that you can retrieve JSON example documents in the «00 Example Data» section using the respective Endpoints. E.g.: https://rest.qr-invoice.cloud/v2/examples/qr-invoice/with-qr-reference
- Handle error responses correctly by checking HTTP status and read detailed error/validation message from response body
- Check all parameters
- Check out length limitation
- Consult official standards / specification if you need more detailed information regarding QR-Bill specification
Standards / Specifications
Overview of official specs www.qr-invoice.ch/dokumentation/standards-merkblaetter/QR Invoice Layers
QR Invoice Model
Product Version: 1.21-SNAPSHOT
https://rest.qr-invoice.cloud/
- Generated server url
https://rest.qr-invoice.cloud/v2/examples/qr-iban
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
https://rest.qr-invoice.cloud/v2/examples/qr-iban \
-H 'X-API-Key: YOUR_API_KEY_HERE'- Generated server url
https://rest.qr-invoice.cloud/v2/examples/invoice-document/mixed-vat
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
https://rest.qr-invoice.cloud/v2/examples/invoice-document/mixed-vat \
-H 'X-API-Key: YOUR_API_KEY_HERE'Invoice Document
The date this invoice is due / is to be paid. Should be invoice date + termOfPaymentDays
Text which is added after the table of invoice positions
Closing text which is added after the table of invoice positions
The positions description
Currency of the invoice which has to match the one specified in QrInvoice
QrInvoice
IBAN or QR-IBAN of the creditor.
Fixed length: 21 alphanumeric characters, only IBANs with CH or LI country code permitted.
Address type
The address type is specified using a code. The following codes are defined:
"S" - structured address
"K" - combined address elements (2 lines). DEPRECATED - discontinued and no longer supported after 21.11.2025
The creditor's name or company according to the account name.
Comment: always matches the account holder
Maximum 70 characters permitted
First name (optional, if available) + last name or company name
Street/P.O. box of the creditor
Maximum 70 characters permitted, may not include any house or building number.
House number of the creditor
Maximum 16 characters permitted
Postal code of the creditor
Maximum 16 characters permitted. The postal code is always to be entered without a country code prefix.
City of the creditor
Maximum 35 characters permitted
Country of the creditor
Two-digit country code according to ISO 3166-1
Address line 1 including street and building number or P.O. Box
Maximum 70 characters permitted
The payment amount
The amount element is to be entered without leading zeroes, including decimal separators and two decimal places.
Decimal, maximum 12-digits permitted, including decimal separators. Only decimal points (".") are permitted as decimal separators.
Reference type (QR, ISO)
The following codes are permitted:
QRR – QR reference
SCOR – Creditor Reference (ISO 11649)
NON – without reference
Maximum four characters, alphanumeric
Must contain the code QRR where a QR-IBAN is used;
where the IBAN is used, either the SCOR or NON code can be entered
Reference number
Structured payment reference
The reference is either a QR reference or a Creditor Reference (ISO 11649)
Maximum 27 characters, alphanumeric;
must be filled if a QR-IBAN is used.
QR reference: 27 characters, numeric, check sum calculation according to Modulo 10 recursive (27th position of the reference)
Creditor Reference (ISO 11649): max 25 characters, alphanumeric
The element may not be filled for the NON reference type.
REST API
On the REST API automatic creation of both QRR and SCOR reference numbers can be used. To do so, wrap the reference number in curly brackets {42}. In case of the QRR, customerId can be passed as well, separated by a colon, e.g. {123456:42}, whereas 123456 is the customerId
{ "sender": { "addressLines": [ … ] }, "recipient": { "addressLines": [ … ] }, "contactPerson": { "name": "John Doe", "email": "john.doe@example.com", "phoneNr": "+41 00 000 00 00" }, "customerNr": "0001839", "customerReference": "string", "invoiceDate": "2020-11-15", "invoiceDueDate": "2020-12-14", "termOfPaymentDays": 30, "invoiceNr": "inv-001532", "title": "Online Order 11.11.2020", "prefaceText": "Dear Sir or Madam\n\nWe thank you for your order.", "endingText": "Please do not hesitate to contact us if you have any questions.\n\nKind regards\n\nJohn Doe", "positions": [ { … } ], "currency": "EUR", "additionalProperties": [ { … } ], "qrInvoice": { "creditorInformation": { … }, "ultimateCreditor": { … }, "paymentAmountInformation": { … }, "ultimateDebtor": { … }, "paymentReference": { … }, "alternativeSchemes": { … } } }
- Generated server url
https://rest.qr-invoice.cloud/v2/examples/invoice-document/gtin
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
https://rest.qr-invoice.cloud/v2/examples/invoice-document/gtin \
-H 'X-API-Key: YOUR_API_KEY_HERE'Invoice Document
The date this invoice is due / is to be paid. Should be invoice date + termOfPaymentDays
Text which is added after the table of invoice positions
Closing text which is added after the table of invoice positions
The positions description
Currency of the invoice which has to match the one specified in QrInvoice
QrInvoice
IBAN or QR-IBAN of the creditor.
Fixed length: 21 alphanumeric characters, only IBANs with CH or LI country code permitted.
Address type
The address type is specified using a code. The following codes are defined:
"S" - structured address
"K" - combined address elements (2 lines). DEPRECATED - discontinued and no longer supported after 21.11.2025
The creditor's name or company according to the account name.
Comment: always matches the account holder
Maximum 70 characters permitted
First name (optional, if available) + last name or company name
Street/P.O. box of the creditor
Maximum 70 characters permitted, may not include any house or building number.
House number of the creditor
Maximum 16 characters permitted
Postal code of the creditor
Maximum 16 characters permitted. The postal code is always to be entered without a country code prefix.
City of the creditor
Maximum 35 characters permitted
Country of the creditor
Two-digit country code according to ISO 3166-1
Address line 1 including street and building number or P.O. Box
Maximum 70 characters permitted
The payment amount
The amount element is to be entered without leading zeroes, including decimal separators and two decimal places.
Decimal, maximum 12-digits permitted, including decimal separators. Only decimal points (".") are permitted as decimal separators.
Reference type (QR, ISO)
The following codes are permitted:
QRR – QR reference
SCOR – Creditor Reference (ISO 11649)
NON – without reference
Maximum four characters, alphanumeric
Must contain the code QRR where a QR-IBAN is used;
where the IBAN is used, either the SCOR or NON code can be entered
Reference number
Structured payment reference
The reference is either a QR reference or a Creditor Reference (ISO 11649)
Maximum 27 characters, alphanumeric;
must be filled if a QR-IBAN is used.
QR reference: 27 characters, numeric, check sum calculation according to Modulo 10 recursive (27th position of the reference)
Creditor Reference (ISO 11649): max 25 characters, alphanumeric
The element may not be filled for the NON reference type.
REST API
On the REST API automatic creation of both QRR and SCOR reference numbers can be used. To do so, wrap the reference number in curly brackets {42}. In case of the QRR, customerId can be passed as well, separated by a colon, e.g. {123456:42}, whereas 123456 is the customerId
{ "sender": { "addressLines": [ … ] }, "recipient": { "addressLines": [ … ] }, "contactPerson": { "name": "John Doe", "email": "john.doe@example.com", "phoneNr": "+41 00 000 00 00" }, "customerNr": "0001839", "customerReference": "string", "invoiceDate": "2020-11-15", "invoiceDueDate": "2020-12-14", "termOfPaymentDays": 30, "invoiceNr": "inv-001532", "title": "Online Order 11.11.2020", "prefaceText": "Dear Sir or Madam\n\nWe thank you for your order.", "endingText": "Please do not hesitate to contact us if you have any questions.\n\nKind regards\n\nJohn Doe", "positions": [ { … } ], "currency": "EUR", "additionalProperties": [ { … } ], "qrInvoice": { "creditorInformation": { … }, "ultimateCreditor": { … }, "paymentAmountInformation": { … }, "ultimateDebtor": { … }, "paymentReference": { … }, "alternativeSchemes": { … } } }