Skip to content
Invoro Docs

Create Invoice

POST
/invoices

Create a new invoice from structured JSON data. Requires the invoice:create scope. The invoice is created in draft state. Set calculate_totals to true to have the server compute line and tax totals automatically.

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”
object
calculate_totals
boolean
business_entity_id
string | null format: uuid
related_invoice_id
string | null format: uuid
delivery_network_id
Any of:
DeliveryNetworkType
string
Allowed values: peppol ksef email nav
buyer_contact_id

The address book entry this invoice was issued to. The buyer block stays the authoritative snapshot; this only links them.

string | null format: uuid
save_buyer_contact

Per-invoice override of the save_buyer_contacts setting, so a one-off recipient does not end up in the address book forever.

boolean
branding_profile_id

PDF branding for this invoice. Omitted: the buyer contact’s profile when linked, else the company default. Null: company default.

string | null format: uuid
header
object
specification
string | null
<= 500 characters
business_process
string | null
<= 500 characters
invoice_number
string | null
<= 255 characters
invoice_number_series
string | null
<= 255 characters
invoice_type_code
string | null
<= 10 characters
document_type
string | null
<= 100 characters
Allowed values: invoice credit_note invoice_response mlr mls order order_response order_agreement despatch_advice catalogue catalogue_response punch_out nlcius_invoice nlcius_credit_note xrechnung_ubl_invoice xrechnung_ubl_credit_note xrechnung_cii_invoice ublbe_invoice ublbe_credit_note
issue_date
string | null format: date-time
due_date
string | null format: date-time
tax_point_date
string | null format: date-time
currency
string | null
>= 3 characters <= 3 characters
vat_currency
string | null
>= 3 characters <= 3 characters
accounting_cost
string | null
<= 255 characters
buyer_reference
string | null
<= 255 characters
project_reference
string | null
<= 255 characters
contract_reference
string | null
<= 255 characters
tender_or_lot_reference
string | null
<= 255 characters
rounding_amount
integer | null
notes
array | null
invoice_period
object
start_date
string | null format: date-time
end_date
string | null format: date-time
description
string | null
<= 255 characters
seller
object
endpoint_id
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
identifiers
array | null
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
name
string | null
<= 255 characters
legal_name
string | null
<= 255 characters
trading_name
string | null
<= 255 characters
company_id
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
vat_number
string | null
<= 50 characters
tax_registration_id
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
legal_information
string | null
address
object
street
string | null
<= 255 characters
additional_line
string | null
<= 255 characters
city
string | null
<= 255 characters
subdivision
string | null
<= 255 characters
postal_code
string | null
<= 20 characters
country
string | null
>= 2 characters <= 2 characters
contact
object
name
string | null
<= 255 characters
phone
string | null
<= 50 characters
email
string | null format: email
<= 255 characters
buyer
required
object
endpoint_id
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
identifiers
array | null
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
name
required
string
<= 255 characters
legal_name
string | null
<= 255 characters
trading_name
string | null
<= 255 characters
company_id
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
vat_number
string | null
<= 50 characters
tax_registration_id
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
address
object
street
string | null
<= 255 characters
additional_line
string | null
<= 255 characters
city
string | null
<= 255 characters
subdivision
string | null
<= 255 characters
postal_code
string | null
<= 20 characters
country
string | null
>= 2 characters <= 2 characters
contact
object
name
string | null
<= 255 characters
phone
string | null
<= 50 characters
email
string | null format: email
<= 255 characters
payee
object
name
string | null
<= 255 characters
company_id
object
scheme
string | null
<= 10 characters
value
string | null
<= 255 characters
items
required
Array<object>
>= 1 items
object
id
string | null
<= 50 characters
name
required
string
<= 255 characters
description
string | null
note
string | null
price
required
integer
quantity
required

Price in cents

number
unit_code
string | null
<= 10 characters
base_quantity
number | null
tax_rate
number | null
<= 100
tax_category
string | null
<= 10 characters
tax_exemption_reason_code
string | null
<= 10 characters
tax_exemption_reason
string | null
<= 255 characters
order_line_reference
string | null
<= 255 characters
accounting_cost
string | null
<= 255 characters
origin_country
string | null
>= 2 characters <= 2 characters
period
object
start_date
string | null format: date-time
end_date
string | null format: date-time
identifiers

Item identifiers

object
standard
object
scheme
string | null
<= 50 characters
value
string | null
<= 255 characters
sellers_item_id
string | null
<= 255 characters
buyers_item_id
string | null
<= 255 characters
classifications

Item classification

array | null
object
list_id
string | null
<= 50 characters
list_version
string | null
<= 50 characters
value
string | null
<= 255 characters
attributes

Item attributes

array | null
object
name
string | null
<= 255 characters
value
string | null
<= 255 characters
allowances

Line allowances

array | null
object
reason
string | null
<= 255 characters
reason_code
string | null
<= 10 characters
amount
integer | null
percentage
number | null
<= 100
base_amount
integer | null
charges

Line charges

array | null
object
reason
string | null
<= 255 characters
reason_code
string | null
<= 10 characters
amount
integer | null
percentage
number | null
<= 100
base_amount
integer | null
payment
object
terms
string | null
payments

Multiple payments

array | null
object
means_code
string | null
<= 10 characters
means_text
string | null
<= 255 characters
payment_id
string | null
<= 255 characters
bank_accounts
array | null
object
account_id
string | null
<= 34 characters
iban
string | null
<= 34 characters
bic
string | null
<= 11 characters
account_name
string | null
<= 255 characters
card
object
pan
string | null
<= 20 characters
network
string | null
<= 50 characters
holder_name
string | null
<= 255 characters
direct_debit
object
mandate_id
string | null
<= 255 characters
debited_account
string | null
<= 255 characters
means_code

Legacy single payment (backwards compatible)

string | null
<= 10 characters
means_text
string | null
<= 255 characters
payment_id
string | null
<= 255 characters
bank_account
object
account_id
string | null
<= 34 characters
iban
string | null
<= 34 characters
bic
string | null
<= 11 characters
account_name
string | null
<= 255 characters
card
object
pan
string | null
<= 20 characters
network
string | null
<= 50 characters
holder_name
string | null
<= 255 characters
direct_debit
object
mandate_id
string | null
<= 255 characters
debited_account
string | null
<= 255 characters
delivery
object
date
string | null format: date-time
location_id
string | null
<= 255 characters
party_name
string | null
<= 255 characters
address
object
street
string | null
<= 255 characters
additional_line
string | null
<= 255 characters
city
string | null
<= 255 characters
subdivision
string | null
<= 255 characters
postal_code
string | null
<= 20 characters
country
string | null
>= 2 characters <= 2 characters
references
object
purchase_order
string | null
<= 255 characters
sales_order
string | null
<= 255 characters
preceding_invoices
array | null
object
number
string | null
<= 255 characters
issue_date
string | null format: date-time
allowances
array | null
object
reason
string | null
<= 255 characters
reason_code
string | null
<= 10 characters
amount
integer | null
percentage
number | null
<= 100
base_amount
integer | null
tax_category
string | null
<= 10 characters
tax_rate
number | null
<= 100
tax_exemption_reason_code
string | null
<= 10 characters
tax_exemption_reason
string | null
<= 255 characters
charges
array | null
object
reason
string | null
<= 255 characters
reason_code
string | null
<= 10 characters
amount
integer | null
percentage
number | null
<= 100
base_amount
integer | null
tax_category
string | null
<= 10 characters
tax_rate
number | null
<= 100
tax_exemption_reason_code
string | null
<= 10 characters
tax_exemption_reason
string | null
<= 255 characters
tax_breakdown
array | null
object
category_code
string | null
<= 10 characters
rate
number | null
<= 100
taxable_amount
integer | null
tax_amount
integer | null
exemption_reason
string | null
<= 255 characters
exemption_reason_code
string | null
<= 10 characters
totals
object
line_extension_amount
integer | null
tax_exclusive_amount

Sum of line totals (in cents)

integer | null
tax_inclusive_amount

Before tax

integer | null
tax_amount

After tax

integer | null
allowance_total_amount
integer | null
charge_total_amount
integer | null
paid_amount
integer | null
payable_rounding_amount
integer | null
payable_amount
integer | null
attachments
array | null
object
document_id
string | null format: uuid
filename
string | null
<= 255 characters
mime_type
string | null
<= 100 characters
description
string | null
<= 255 characters
data
string | null
external_reference

Base64 encoded (B2B API compat)

string | null
<= 500 characters
branding_profile_id

UUID of the branding profile used for the invoice PDF (see GET /branding-profiles). When omitted, the linked contact’s profile applies, else the company default; null selects the company default.

string | null format: uuid
header
object
invoice_number_series

Name of the invoice number series to use for auto-numbering. Only used when header.invoice_number is not provided, the server will generate a number from this series when the invoice is sent. Defaults to the company’s default series.

string | null
document_type

Per-invoice override for the Peppol profile to send under (e.g. invoice, credit_note, ublbe_invoice, nlcius_invoice, xrechnung_ubl_invoice). Must match the document category (invoice profiles for type 380, credit-note profiles for 381). When omitted, the company default (set automatically for BE/NL/DE on registration) is used. The chosen profile is verified against the recipient’s SMP record at send time. See the Default Document Type Profile guide in the Invoice API documentation for the resolution and fallback rules.

string | null

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Invoice created successfully.

object
data
required
InvoiceResource
object
id
required

Unique invoice identifier (UUID).

string
company_id
required

UUID of the company that owns this invoice.

string
user_id
required

UUID of the user who created the invoice, if applicable.

string | null
state
required

Current workflow state: draft, approved, sending, sent, delivered, failed, or cancelled.

string
direction
required

Invoice direction: outgoing (sent by company) or incoming (received).

string
amount
required

Invoice total amount in cents.

integer
currency
required

ISO 4217 currency code (e.g. EUR, USD).

string
ubl_version
required

UBL specification version used (2.1, 2.2, or 2.3).

string
ubl_json
required

Full invoice data in structured UBL JSON format (header, seller, buyer, items, totals, etc.).

object | null
delivery_network_id
required

Delivery network used: peppol, ksef, or email.

string | null
business_entity_id
required

UUID of the business entity (seller identity) used for this invoice.

string | null
buyer_contact_id
required

UUID of the address book contact this invoice was issued to, if any.

string | null
branding_profile_id
required

UUID of the branding profile used for the PDF; null means the company default profile.

string | null
related_invoice_id
required
string | null
payment_status
required
string | null
total_paid_cents
required
integer
is_test
required
boolean
metadata_json
required

Public invoice metadata, e.g. the delivery method. Always a JSON object.

object
key
additional properties
delivery_method
required

Delivery method selected when sending: auto, peppol, email, etc.

peppol_response

Final Peppol access-point response for the send attempt.

mlr_sent_at
required

Timestamp the Message Level Response was forwarded, if any.

mls
required

Outbound Message Level Response verdict from the recipient’s access point:

  • verdict: received_ap (delivered) | received_ab (delivered with note) | received_re (rejected)
  • received_at: ISO 8601 timestamp the MLR was processed by the AP
  • error_details: rejection reason if verdict is received_re Null until the recipient AP returns an MLR or 72h elapses.
string | null
documents
Array<object>
DocumentResource
object
id
required
string
type
required
string
status
required
string
original_filename
required
string
mime_type
required
string
size
required
integer
human_size
required
string
has_thumbnail
required
boolean
is_image
required
boolean
tags
Array<object>
TagResource
object
id
required
string
name
required
string
slug
required
string
is_generic
required
boolean
created_at
required
string
documentable_key
required
string | null
documentable_id
required
integer | null
uploaded_by
Array
metadata
required
string
is_deletable
required
boolean
deletable_reason
required
string | null
created_at
required
string
checksum
string
virus_scanned_at
string | null
updated_at
string
created_at
required

ISO 8601 timestamp when the invoice was created.

string | null
updated_at
required

ISO 8601 timestamp when the invoice was last updated.

string | null
deleted_at
required

ISO 8601 timestamp when the invoice was soft-deleted, or null.

string | null
public_access_revoked_at
required

ISO 8601 timestamp when the public (signed-URL) link was revoked, or null if active.

string | null

422

Section titled “422 ”

Validation error or API key not associated with a company.

object
message
required
string
Allowed value: User must belong to a company to create invoices.

500

Section titled “500 ”

Server error during invoice creation.

object
success
required
boolean
message
required
string
data
required
null
errors
required
null