Skip to main content
POST
Create invoice

​
Creating a customer invoice

Invoices belong to a template and are addressed to a contact (or a free-text recipient). They are made up of an ordered list of positions, each of which has a discriminator type:
  • product — a standard billable line with a quantity, singleAmount, and contraAccount
  • discount — reduces the preceding positions, by either a percentage or an absolute amount (exactly one of the two must be set)
  • text — a non-billable text line
  • subtotal — renders the running subtotal of the preceding positions

​
Draft vs. posted

The isDraft flag controls whether the new invoice is posted immediately:
  • isDraft: true — saves the invoice as a draft. No accounting transactions are created.
  • isDraft: false — posts the invoice and creates the underlying transactions on openingDate. The transaction date must fall within an editable fiscal year and VAT period.

​
Foreign-currency invoices

To issue an invoice in a non-primary currency, provide originalCurrency (3-character ISO 4217 code). The currency must already be enabled in the organisation. exchangeRate is optional. When omitted, the invoice inherits the organisation’s stored exchange rate for that currency, the same behaviour as foreign-currency ledger entries. When provided, it is expressed as 1 originalCurrency = X primaryCurrency (e.g. 0.98 if 1 EUR = 0.98 CHF). An exchangeRate without originalCurrency is rejected.

​
External reference

Use the optional externalReference string to retain an id that belongs outside Infinity. It is capped at 128 characters, returned on create, get, and list responses, and can be used as an exact-match filter when you find invoices. The reference must be unique among the organisation’s invoices. A duplicate returns 409 Conflict with error code customer-invoices/external-reference-already-exists.

​
Example

The following payload creates a posted CHF invoice with two product lines and a 10% discount:

​
Retrying safely with idempotency keys

If a request fails or times out, you may not know whether the invoice was created. To retry safely without creating a duplicate invoice, provide a unique Idempotency-Key header (for example a UUID) with your request:
When you retry a request with the same key and payload, the API returns the status and response of the original request – including the invoice it created – instead of creating the invoice again.
  • Keys are scoped to your organisation, API key and endpoint. The same key can be used once for an invoice and once for an estimate.
  • Keys are retained for 24 hours. After that, a key can be used again and will create a new invoice.
  • Reusing a key with a different payload returns 409 Conflict with error code rest-api/idempotency-key-payload-mismatch.
  • While a request is still being processed, concurrent requests with the same key return 409 Conflict with error code rest-api/idempotency-key-request-in-progress.
  • If a request fails, its key is released, so the same key can be used to retry.
Generate a new idempotency key for every new invoice, and reuse it only when retrying the same request.

Authorizations

​
x-api-token
string
header
required

API token for authentication. Obtain from your Infinity account settings.

Headers

​
Idempotency-Key
string

A unique key that makes this request idempotent, for example a UUID. If a request fails or times out, it can safely be retried with the same key without creating a duplicate: a retry with the same key and payload returns the status and response of the original request, including the resource it created.

Keys are scoped to your organisation and API key, and are retained for 24 hours. Reusing a key with a different payload returns 409 Conflict. While a request is still being processed, other requests with the same key also return 409 Conflict.

Required string length: 1 - 200

Body

application/json

The invoice payload.

Request body for creating a customer invoice.

​
openingDate
string<date>
required

The opening date (issue date) of the document in YYYY-MM-DD format. For invoices, this is also the date used for the posted accounting transactions.

​
positions
(ProductPosition · object | DiscountPosition · object | TextPosition · object | SubtotalPosition · object)[]
required

The ordered list of positions on the document. At least one position is required, and discount positions must specify exactly one of percentage or amount.

A standard billable line item with a quantity, single amount, and contra account. Most invoice and estimate positions are of this type.

​
isDraft
boolean
required

When true the invoice is created in draft state and no transactions are posted. Set to false to immediately post the invoice.

​
template
string

The id of the invoice template to render the document with. When omitted while creating an invoice or estimate, the organisation's default template is used. Use the invoice templates endpoint to list the available templates.

​
recipient
string

The id of the contact this document is addressed to. Required unless customRecipientText is provided.

​
customRecipientText
string

An ad-hoc recipient text used when no contact is associated with the document.

Maximum string length: 2000
​
externalReference
string

An optional reference for this document in an external system.

Maximum string length: 128
​
title
string

Optional document title displayed on the rendered output.

Maximum string length: 128
​
payableInDays
integer

Payment terms for this document in days from the opening date. Defaults to 30 on create.

Required range: 0 <= x <= 365
​
introductoryText
string

Text rendered above the positions.

Maximum string length: 2000
​
closingText
string

Text rendered below the positions.

Maximum string length: 2000
​
amountMode
enum<string>

Whether position amounts are entered gross (including VAT) or net (excluding VAT).

Available options:
gross,
net
​
language
enum<string>

The language used to render the document.

Available options:
de,
en,
fr,
it
​
columns
enum<string>[]

The columns to render in the positions table. If not provided the template default is used.

A column that can be shown on the rendered invoice or estimate.

Available options:
quantity,
unit,
articleNumber,
name,
date,
vatDebt,
vatRate,
singleAmount,
totalAmount,
discountRate,
positionNumber,
customTextColumn1,
customTextColumn2,
customTextColumn3
​
originalCurrency
string

For foreign-currency documents: the 3-character ISO 4217 currency code the document is denominated in. Must be a currency code that is enabled in the organisation. When set without exchangeRate, the organisation's stored exchange rate for that currency is used.

Required string length: 3
​
exchangeRate
number

For foreign-currency documents: the conversion rate from the original currency to the primary accounting currency, expressed as 1 originalCurrency = X primaryCurrency. Optional when originalCurrency is set; if omitted, defaults to the organisation's stored exchange rate for that currency. Cannot be set without originalCurrency.

​
isQrInvoice
boolean

When true the document is rendered as a QR-bill (Swiss QR-Rechnung). Defaults to false.

Response

The invoice was created successfully.

​
invoice
Invoice · object

The full representation of a customer invoice.