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
header
object
specification
string | null
<= 500 characters
business_process
string | null
<= 500 characters
invoice_number
string | null
<= 255 characters
invoice_type_code
string | null
<= 10 characters
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
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
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
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
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
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
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
attachments
array | null
object
filename
string | null
<= 255 characters
mime_type
string | null
<= 100 characters
description
string | null
<= 255 characters
data
string | null
external_reference

Base64 encoded

string | null
<= 500 characters
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
Example
billing

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. Peppol BIS 3.0 binds to UBL 2.1.

string
ubl_json
required

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

object | null
metadata_json
required

Additional metadata such as delivery details, error info, or processing history.

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
related_invoice_id
required
string | null
payment_status
required
string
total_paid_cents
required
integer
is_test
required
boolean
created_at
required

ISO 8601 timestamp when the invoice was created.

string
updated_at
required

ISO 8601 timestamp when the invoice was last updated.

string
deleted_at
required

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

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