Create invoice

POST https://api.invunion.com/api/v1/invoices invoices:write Markdown

Create an issued invoice or credit note.

Creates an issued invoice or credit note. invoice_type is always issued. invoiceNumber, invoiceDate, amountExclVat, and amountInclVat are required. sourceId is optional and defaults to invoiceNumber. If no counterpartyId is sent, identity fields are used to look up or create a counterparty. Expected payment is computed from the due date and this customer’s previous paid invoices. If no schedule is sent, Invunion creates a single payment. Issued invoices may auto-apply unused credit notes and unapplied cash.

Body parameters

Name	Type	Required
`invoiceNumber` Invoice number. Unique per tenant. This is how you identify the invoice later. Example: INV-2026-0042	string Max 100	Required
`invoiceDate` Invoice date (YYYY-MM-DD). Example: 2026-09-01	string No maximum	Required
`amountExclVat` Amount excluding VAT, in major currency units unless the tenant stores minor units and sourceType is api. Example: 10000	number	Required
`amountInclVat` Amount including VAT. Example: 12000	number	Required
`kind` invoice or credit_note. Default invoice. Allowed values`invoicecredit_note`	string No maximum	Recommended
`sourceType` Origin of the record. Use api for integrations. Default manual. Example: api	string Max 50	Recommended
`recipientName` Recipient display name. Defaults from the resolved counterparty when omitted. Example: Leones Cars	string Max 255	Recommended
`paymentScheduleCode` Payment-schedule template code. If omitted, Invunion creates a single payment unless useDefaultPaymentSchedule is true. Example: NET-30	string Max 50	Recommended
`vatAmount` VAT amount. If omitted, Invunion stores the difference of the two amounts. Example: 2000	number	Optional
`currency` ISO 4217 currency. Default EUR. Example: EUR	string Max 3	Recommended
`dueDate` Due date (YYYY-MM-DD). When present, paymentTermDays is not stored on the invoice. Example: 2026-10-01	string No maximum	Recommended
`sourceId` Optional idempotency key from your system. Together with sourceType this is unique per tenant. Defaults to invoiceNumber — you do not need a separate source id. Example: INV-2026-0042	string Max 255	Optional
`externalReference` Your order or billing reference. Example: LC-SO-9081	string Max 255	Optional
`description` Line description. Example: Fleet maintenance — September 2026	string Max 1000	Optional
`paymentMethod` Expected payment channel.	string No maximum	Optional
Allowed values`cardtransferdirect_debitcashcheckcryptoother`
`paymentTermDays` Used only when dueDate is omitted, to compute due date from the invoice date. Not stored if dueDate is sent. Example: 30	integer	Optional
`counterpartyId` Existing counterparty code (`account_code`). If omitted, identity fields below are used to look up or create one. Example: CPT-042	string No maximum	Optional
`counterpartyAccountCode` Counterparty account_code for identity lookup (for example CPT-042). Example: CPT-042	string Max 50	Recommended
`counterpartyExternalReference` Counterparty external reference. Example: ERP-1842	string Max 255	Optional
`counterpartyVatNumber` Counterparty VAT number. Example: FR12345678901	string Max 30	Optional
`counterpartyEmail` Counterparty email. Example: carl@leonescars.fr	string Max 255	Optional
`counterpartyIban` Optional catalog IBAN to attach after the counterparty is resolved. Example: FR7630006000011234567890189	string Max 64	Optional
`counterpartyBic` BIC for the catalog instrument. Example: BNPAFRPP	string Max 11	Optional
`paymentMethodId` Existing catalog payment-method code to attach. Example: PM-001	string No maximum	Optional
`originInvoiceId` For credit notes, the invoice number of the invoice being credited. Example: INV-2026-0042	string No maximum	Optional
`useDefaultPaymentSchedule` If true, apply the tenant default schedule. If omitted or false, Invunion creates a single payment. Allowed values`truefalse`	boolean	Optional
`installments` Exact installment plan. When present, this replaces any template. Each item needs dueDate and amount.	array	Optional
`dueDate` Installment due date (YYYY-MM-DD). Example: 2026-10-01	string No maximum	Required
`amount` Installment amount, zero or greater. Example: 12000	number	Required
`sequence` 1-based sequence. Example: 1	integer	Optional
`label` Optional label. Example: Balance	string Max 100	Optional
`analytic1` Analytic axis 1. Example: SALES-EU	string Max 100	Optional
`analytic2` Analytic axis 2. Example: CHANNEL-DIRECT	string Max 100	Optional
`metadata` JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. Example: {"erp_id":"INV-1842"}	object	Optional

Errors

This operation can return the following errors in addition to generic HTTP failures.

Error	HTTP code	Description
`Missing Bearer token`	401	The Authorization header is missing or is not a Bearer token.
`Invalid or revoked API key`	401	The API key is unknown, malformed, expired, or has been revoked.
`API key is missing scope invoices:write`	403	The key does not include invoices:write. A write scope does not imply the matching read scope.
`Too many requests, please try again later`	429	Wait and retry. The Retry-After header is the number of seconds to wait.
`Tenant ID required`	400	The authenticated credential is not bound to a tenant.
`Validation failed`	400	The body failed schema validation. details lists field and message.
`Unknown or inactive payment schedule.`	400	paymentScheduleId or paymentScheduleCode did not match an active template.
`duplicate_invoice`	409	An invoice with this invoice_number already exists. The message includes the number and existing_invoice_id.
`Internal server error`	500	Unexpected server error. The JSON body includes correlationId. Retry with backoff.

Previous: Get invoice Next: Cancel invoice