Invoice PDF
The Invoice PDF API allows you to create beautiful PDF invoices in the simplest possible way. The invoice data simply needs to be sent to the API as JSON data and a high-quality PDF invoice is created. If desired, an EPC QR code or a Swiss QR Invoice can also be added. Four different templates are currently available.
A complete PDF invoice including EPC QR code is visible on the right-hand side.
Endpoints
The API is available via POST request. The endpoint returns a PDF document with content type application/pdf.
POST/v1/invoice-pdf
curl -X POST https://api.apistax.io/v1/invoice-pdf \
-o 'Invoice.pdf' \
-H 'Authorization: Bearer API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"sender": [ "ACME Holding SE" ],
"recipient": [ "Vehement Capital Partners" ],
"items": [
{
"description": "Product A",
"sumPrice": 10
}
],
"contextItems": [
{
"title": "Order Date",
"value": "13.05.2024"
}
]
}'Parameters
template: String = DEFAULT
The template in which the invoice is to be rendered. The different layouts available can be seen
under templates. Defaults to DEFAULT.
sender: Array<String>
The address of the sender of the invoice. Each entry in the array represents one line of the address.
recipient: Array<String>
The address of the recipient of the invoice. Each entry in the array represents one line.
logo: String
The logo of the invoice sender which is added to the header of the document encoded as base64.
items: Array<Object>
The list of items that are to be invoiced. At least one item must be provided.
Either unitPrice or sumPrice must be set. If the unitPrice field is set, the sumPrice is calculated.
description: String
The description of the invoice item
amount: Float = 1
The amount of the invoice item. Defaults to 1.
unit: String
The optional unit, for example, kilogram or piece.
unitPrice: Float
The price per unit
sumPrice: Float
The total price of the invoice item. If the field is not set, it is calculated using the unit price and amount.
feeTaxItems: Array<Object>
The list of fee and tax items. An element to add any tax and/or fees in addition to the invoice items. When using
the percent field, the value is calculated from the sum of the invoice items including any previous taxes and fees.
The values are calculated in the order passed. Either value or percent must be set.
title: String
The element title for example "20% VAT" or "Dunning charge".
percent: String
The item percent. The resulting value is calculated from the sum of the invoice items including any previous taxes and fees. The values are calculated in the order passed.
value: String
The item value. A fixed value instead of the calculated percent value.
contextItems: Array<Object>
The list of context items. An informative element that is shown in the content of the invoice, for example to display detailed information such as the invoice number for the respective invoice.
title: String
The item title
value: String
The item value
footerItems: Array<Object>
The list of footer items. An informative element that is shown in the footer of the invoice, for example, to display information about the company.
title: String
The item title
values: Array<String>
A list of values
locale: String = de-AT
The country or language according to which the values are to be formatted. Defaults to de-AT.
currency: String = EUR
The currency according to ISO 4217. Defaults to EUR.
notice: String
A note that is printed at the end of the invoice.
currencyFormat: String = CODE
The currency format to be used. SYMBOL for the currency symbol e.g. €, CODE for the currency abbreviation e.g. EUR
and NAME for the name of the currency which is translated using the 'locale' variable, e.g. Euro. Defaults to CODE.
labels: Object
This object can be used to overwrite standard invoice texts.
invoice: String = Invoice
subtotal: String = Subtotal
total: String = Total
amount: String = Amount
description: String = Description
unitPrice: String = Unit price
sumPrice: String = Sum price
numberOfPages: String = {current} | {total}
Use the placeholders {current} and {total} for the current page and the total number of pages respectively.
epcQrCode: Object
The information for creating an EPC QR code. If this object is provided, a QR code will be printed on the invoice. Detailed information can be found in the documentation for the EPC QR code API
iban: String
The international bank account number of the recipient.
bic: String
The bank identifier code of the recipient bank.
recipient: String
The recipients name. The name can be maximum 70 characters long.
reference: String
The payment reference. Can be maximum 35 characters long.
text: String
The bank transfer text. The text can be up to 140 characters long and may not be used in the banking app if
the reference parameter is set.
message: String
A user hint which can be maximum 70 characters long.
swissQrInvoice: Object
The information for creating a Swiss QR invoice. If this object is provided, a Swiss QR invoice code will be printed on the invoice. For more details see Swiss QR invoice documentation.
creditor: String
iban: String
The international bank account number of the creditor. All spaces between the blocks are removed. The IBAN must originate from Switzerland or Lichtenstein and thus must begin with CH or LI.
name: String
The creditors name. The name must not exceed 70 characters in length.
street: String
The creditors street name. The street must not exceed 70 characters in length.
postalCode: String
The creditors postal code. The code must not exceed 16 characters in length.
city: String
The creditors city name. The city must not exceed 35 characters in length.
country: String = CH
The creditors country code as ISO 3166-1 alpha-2 code. Defaults
to CH.
debtor: Object
Debtor information. This object is optional, but if it is provided, at least name, postalCode and city must be
specified.
name: String
The debtors name. The name must not exceed 70 characters in length.
street: String
The debtors street name. The street must not exceed 70 characters in length.
postalCode: String
The debtors postal code. The code must not exceed 16 characters in length.
city: String
The debtors city name. The city must not exceed 35 characters in length.
country: String = CH
The debtors country code as ISO 3166-1 alpha-2 code. Defaults
to CH.
information: String
Unstructured information which can be used for example for payment purpose. The information must not exceed 140 characters in length.
structuredInformation: String
Structured information contains coded information for automated booking of the payment. The syntax definition in the latest version can be found at swico.ch.
reference: String
The reference is either a QR reference (if a QR-IBAN is used in swissQrInvoice.creditor.iban) or
an ISO 11649 creditor reference.
If most parameters are utilized, an example curl request could look like this:
curl -X POST https://api.apistax.io/v1/invoice-pdf \
-o 'Invoice 9032.pdf' \
-H 'Authorization: Bearer API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"template": "DEFAULT",
"sender": [
"ACME Holding SE",
"Champ de Mars",
"5. Av. Anatole France",
"75007 Paris"
],
"recipient": [
"Vehement Capital Partners",
"119 Eaton Square",
"London SW1W 9AL",
"United Kingdom"
],
"items": [
{
"description": "Water Carafe JUAN\n*L / YELLOW*",
"unitPrice": 11.49,
"amount": 3
}
],
"feeTaxItems": [
{
"title": "20% VAT",
"percent": 20
}
],
"contextItems": [
{
"title": "Order Date",
"value": "13.05.2024"
}
],
"footerItems": [
{
"title": "Social Media",
"values": [
"Instagram @acme_holding",
"X @acme"
]
}
],
"labels": {
"invoice": "Invoice #9032",
"amount": "Qty",
"unitPrice": "Price",
"numberOfPages": "Page {current} of {total}"
},
"epcQrCode": {
"iban": "FR8012739000409912873776J11",
"recipient": "ACME Holding SE",
"text": "Test! Do not transfer!"
},
"locale": "fr-FR",
"currencyFormat": "SYMBOL",
"notice": "If you have any questions, please do get in contact.\n**Thanks for your trust!**\n\n**Attention:** This is an example invoice to illustrate the possibilities of the [APIstax](https://apistax.io) invoice generation API."
}'Templates
Default template
A traditional invoice with a clean layout and clear typography for easy readability.
Use constant DEFAULT in field template.
Classic template
A classic invoice with good contrast and clearly separated areas. The information is arranged vertically.
Use constant CLASSIC in field template.
Modern template
A modern layout with clear lines and good demarcation.
Use constant MODERN in field template.
Minimalistic template
The minimalistic invoice template prioritizes a clean and straightforward design.
Use constant MINIMALISTIC in field template.
Possible errors
| Identifier | Description |
|---|---|
message.unknownCurrency |
Parameter currency must be valid and provided as an ISO 4217 currency code. |
message.unitPriceOrSumPriceMustNotBeNull |
Parameter unitPrice or sumPrice is required in items. |
message.descriptionMustNotBeNull |
Parameter description is required in items. |
message.templateMustNotBeNull |
Parameter template is required. |
message.itemsMustNotBeEmpty |
Parameter items must contain at least one element. |
message.senderMustNotBeNull |
Parameter sender is required. |
message.recipientMustNotBeNull |
Parameter recipient is required. |
message.percentOrValueMustNotBeNull |
Parameter percent or value is required in feeTaxItems. |
If an EPC QR code is additionally created, errors of this endpoint can also happen. The same applies to the Swiss QR Invoice. Possible error codes can be found here.
It should be noted that there are a number of common error messages, which can be found in the "Possible errors" section of the general documentation.