Create a concept purchase invoice

reference

String (max 100 characters)

Required

Internal identifier for the concept purchase invoice, assigned by the caller. Used to reference the invoice in later requests.

externalIdentifier

String (max 100 characters)

Optional

External identifier supplied by the caller, used by the integrating system to reference this invoice outside Bloxs.

ownerReference

String (max 100 characters)

Required

Reference to the owner, the administration the invoice is booked against.

relationReference

String (max 100 characters)

Required

Reference to the relation, the supplier the invoice was received from.

subject

String (max 512 characters)

Optional

Free text subject describing the invoice as a whole, shown as a reference on the invoice overview.

invoiceDate

Date (ISO 8601, format YYYY-MM-DD)

Optional

Date on the incoming invoice. Example: 2026-08-14.

expiryDate

Date (ISO 8601, format YYYY-MM-DD)

Optional

Date by which the invoice is expected to be paid or settled. Example: 2026-09-14.

paymentMethod

Integer (enum)

Optional

How the invoice is settled. Allowed values: 1 = DirectDebit, 2 = BankTransfer.

fromBankAccountIban

String (max 34 characters)

Optional

IBAN of the account the payment is made from. Example: NL02ABNA0123456789.

toBankAccountIban

String (max 34 characters)

Optional

IBAN of the account the payment is made to, typically the supplier's account. Example: NL18RABO0123459876.

verifyInvoiceTotalAmount

Decimal

Optional

Total invoice amount, in major currency units, supplied by the caller. Used by Bloxs to validate against the amount calculated from the invoice lines.

financialPeriodModel.financialYear

Integer

Optional

Financial year the invoice is booked in, used as the invoice level default financial period for lines that do not specify an alternative period.

financialPeriodModel.financialIndex

Integer

Optional

Financial period index within the financial year the invoice is booked in.

financialPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods used to spread the invoice amount over multiple financial periods.

serviceCostsPeriodModel.financialYear

Integer

Optional

Financial year used for service charge allocation of this invoice, independent of the general ledger booking period.

serviceCostsPeriodModel.financialIndex

Integer

Optional

Service charge period index within the service charge financial year.

serviceCostsPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods used to spread the service charge allocation over multiple periods.

lines

Array of objects

Optional

The invoice lines that together build up the invoice totals. Each line can be allocated to a ledger account, a real estate object and a tax rate.

lines[].lineIndex

Integer

Optional

Sequence number of the line within the invoice.

lines[].description

String (max 512 characters)

Optional

Free text description of the line item.

lines[].ledgerAccountCode

String (max 12 characters)

Optional

Code of the ledger account the line amount is booked to.

lines[].realEstateObjectReference

String (max 100 characters)

Optional

Reference to the real estate object the line amount is allocated to, when the cost relates to a specific object.

lines[].taxRateCode

String (max 100 characters)

Optional

Code of the tax rate applied to the line, determines the VAT treatment of the line amount. Example: 5b - Te vorderen laag (9%).

lines[].amountExcl

Decimal

Optional

Line amount excluding VAT, the net amount, in major currency units.

lines[].amountVAT

Decimal

Optional

VAT amount calculated for the line, based on amountExcl and the applied tax rate. Holds an amount, not a rate.

lines[].amountIncl

Decimal

Optional

Line amount including VAT, the gross amount, in major currency units. Equals amountExcl plus amountVAT.

lines[].useAlternativeFinancialPeriod

Boolean

Optional

Indicates whether alternateFinancialPeriodModel holds the financial year and index applied to this line, as opposed to the invoice level financialPeriodModel.financialYear and financialPeriodModel.financialIndex. In the current implementation this value is always true, so alternateFinancialPeriodModel always holds the financial year and index applied to the line. This does not mean the line uses a different financial period than the invoice. The values in alternateFinancialPeriodModel can be equal to or different from financialPeriodModel.financialYear and financialPeriodModel.financialIndex at invoice level.

lines[].alternateFinancialPeriodModel.financialYear

Integer

Optional

Financial year applied to this line. Always populated, since useAlternativeFinancialPeriod is always true in the current implementation. Can be equal to or different from financialPeriodModel.financialYear at invoice level.

lines[].alternateFinancialPeriodModel.financialIndex

Integer

Optional

Financial period index applied to this line. Always populated, since useAlternativeFinancialPeriod is always true in the current implementation. Can be equal to or different from financialPeriodModel.financialIndex at invoice level.

lines[].alternateFinancialPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods used to spread this line's amount over multiple financial periods.

lines[].useAlternativeServiceCostsPeriod

Boolean

Optional

Indicates whether alternateServiceCostsPeriodModel holds the service charge financial year and index applied to this line, as opposed to the invoice level serviceCostsPeriodModel.financialYear and serviceCostsPeriodModel.financialIndex. In the current implementation this value is always true, so alternateServiceCostsPeriodModel always holds the service charge financial year and index applied to the line. This does not mean the line uses a different service charge period than the invoice. The values in alternateServiceCostsPeriodModel can be equal to or different from serviceCostsPeriodModel.financialYear and serviceCostsPeriodModel.financialIndex at invoice level.

lines[].alternateServiceCostsPeriodModel.financialYear

Integer

Optional

Service charge financial year applied to this line. Always populated, since useAlternativeServiceCostsPeriod is always true in the current implementation. Can be equal to or different from serviceCostsPeriodModel.financialYear at invoice level.

lines[].alternateServiceCostsPeriodModel.financialIndex

Integer

Optional

Service charge period index applied to this line. Always populated, since useAlternativeServiceCostsPeriod is always true in the current implementation. Can be equal to or different from serviceCostsPeriodModel.financialIndex at invoice level.

lines[].alternateServiceCostsPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods used to spread this line's service charge allocation when useAlternativeServiceCostsPeriod is true.

reference

String (max 100 characters)

Required

Internal identifier of the created concept purchase invoice.

externalIdentifier

String (max 100 characters)

Optional

External identifier of the invoice, as supplied on creation.

ownerReference

String (max 100 characters)

Required

Reference to the owner, the administration the invoice is booked against.

relationReference

String (max 100 characters)

Required

Reference to the relation, the supplier the invoice was received from.

subject

String (max 512 characters)

Optional

Subject describing the invoice as a whole.

invoiceDate

Date (ISO 8601, format YYYY-MM-DD)

Optional

Date on the invoice. Read only in the response.

expiryDate

Date (ISO 8601, format YYYY-MM-DD)

Optional

Date by which the invoice is expected to be paid or settled. Read only in the response.

paymentTermName

String

Optional

Name of the payment term applied to the invoice.

paymentMethod

Integer (enum)

Optional

How the invoice is settled. Allowed values: 1 = DirectDebit, 2 = BankTransfer, 3 = Withdrawal, 4 = Cash, 5 = iDEAL.

totalAmountExcl

Decimal

Optional

Total invoice amount excluding VAT, in major currency units. The sum of amountExcl across all lines.

totalAmountVAT

Decimal

Optional

Total VAT amount for the invoice, in major currency units. The sum of amountVAT across all lines.

totalAmountIncl

Decimal

Optional

Total invoice amount including VAT, in major currency units. Equals totalAmountExcl plus totalAmountVAT.

fromBankAccountIban

String (max 34 characters)

Optional

IBAN of the account the payment is made from.

toBankAccountIban

String (max 34 characters)

Optional

IBAN of the account the payment is made to, typically the supplier's account.

verifyInvoiceTotalAmount

Decimal

Optional

Total amount that was supplied on creation, used to validate against the calculated invoice total.

financialPeriodModel.financialYear

Integer

Optional

Financial year the invoice is booked in.

financialPeriodModel.financialIndex

Integer

Optional

Financial period index within the financial year the invoice is booked in.

financialPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods the invoice amount is spread over.

serviceCostsPeriodModel.financialYear

Integer

Optional

Financial year used for service charge allocation of this invoice.

serviceCostsPeriodModel.financialIndex

Integer

Optional

Service charge period index within the service charge financial year.

serviceCostsPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods the service charge allocation is spread over.

lines

Array of objects

Optional

The invoice lines that build up the invoice totals.

lines[].lineIndex

Integer

Optional

Sequence number of the line within the invoice.

lines[].description

String (max 512 characters)

Optional

Description of the line item.

lines[].ledgerAccountCode

String (max 12 characters)

Optional

Code of the ledger account the line amount is booked to.

lines[].realEstateObjectReference

String (max 100 characters)

Optional

Reference to the real estate object the line amount is allocated to.

lines[].taxRateCode

String (max 100 characters)

Optional

Code of the tax rate applied to the line.

lines[].amountExcl

Decimal

Optional

Line amount excluding VAT, the net amount, in major currency units.

lines[].amountVAT

Decimal

Optional

VAT amount for the line. Holds an amount, not a rate.

lines[].amountIncl

Decimal

Optional

Line amount including VAT, the gross amount, in major currency units. Equals amountExcl plus amountVAT.

lines[].useAlternativeFinancialPeriod

Boolean

Optional

Indicates whether alternateFinancialPeriodModel holds the financial year and index applied to this line, as opposed to the invoice level financialPeriodModel.financialYear and financialPeriodModel.financialIndex. In the current implementation this value is always true, so alternateFinancialPeriodModel always holds the financial year and index applied to the line. This does not mean the line uses a different financial period than the invoice. The values in alternateFinancialPeriodModel can be equal to or different from financialPeriodModel.financialYear and financialPeriodModel.financialIndex at invoice level.

lines[].alternateFinancialPeriodModel.financialYear

Integer

Optional

Financial year applied to this line. Always populated, since useAlternativeFinancialPeriod is always true in the current implementation. Can be equal to or different from financialPeriodModel.financialYear at invoice level.

lines[].alternateFinancialPeriodModel.financialIndex

Integer

Optional

Financial period index applied to this line. Always populated, since useAlternativeFinancialPeriod is always true in the current implementation. Can be equal to or different from financialPeriodModel.financialIndex at invoice level.

lines[].alternateFinancialPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods for this line's service charge allocation when useAlternativeFinancialPeriod is true.

lines[].useAlternativeServiceCostsPeriod

Boolean

Optional

Indicates whether alternateServiceCostsPeriodModel holds the service charge financial year and index applied to this line, as opposed to the invoice level serviceCostsPeriodModel.financialYear and serviceCostsPeriodModel.financialIndex. In the current implementation this value is always true, so alternateServiceCostsPeriodModel always holds the service charge financial year and index applied to the line. This does not mean the line uses a different service charge period than the invoice. The values in alternateServiceCostsPeriodModel can be equal to or different from serviceCostsPeriodModel.financialYear and serviceCostsPeriodModel.financialIndex at invoice level.

lines[].alternateServiceCostsPeriodModel.financialYear

Integer

Optional

Service charge financial year applied to this line. Always populated, since useAlternativeServiceCostsPeriod is always true in the current implementation. Can be equal to or different from serviceCostsPeriodModel.financialYear at invoice level.

lines[].alternateServiceCostsPeriodModel.financialIndex

Integer

Optional

Service charge period index applied to this line. Always populated, since useAlternativeServiceCostsPeriod is always true in the current implementation. Can be equal to or different from serviceCostsPeriodModel.financialIndex at invoice level.

lines[].alternateServiceCostsPeriodModel.amountOfTransitoricPeriods

Integer

Optional

Number of transitoric periods for this line's service charge allocation when useAlternativeServiceCostsPeriod is true.