Invoices¶
One endpoint for everything. Every invoice your client issues or receives comes through here. Which of them Noja finances is Noja's decision, taken against the facility the client already agreed to.
What the client chooses, and what Noja decides¶
This is the part most integrations get wrong, because it differs from selective invoice finance. Noja's standard agreement is a whole-turnover facility: every receivable the client issues is assessed, at the advance rate agreed with them at onboarding.
The client does not pick which invoices go forward — Noja decides that, invoice by invoice. What the client can do is ask for a different share of a particular invoice: a higher or lower advance rate than their usual one.
| Decision | Who makes it |
|---|---|
| Whether an invoice reaches Noja | Nobody — all of them must |
| Whether an invoice is financed | Noja |
| What share of it is advanced | Client may request; Noja sets what applies |
| Field | Values | What it changes |
|---|---|---|
direction |
receivable · payable |
Whether your client issued the invoice or received it. Both are required — receivables are the collateral, payables complete the net cash-flow picture. Only receivables can be financed. |
credited |
true · false |
false (default) is an invoice. true marks it a credit note. |
requestedAdvanceRate |
omit · 0–100 |
Ask for a different share of this invoice. Omit it and the client's facility rate applies. |
financingIntent |
omit · exclude · include |
Overrides the client's facility for this one invoice. Omit it — that is the standard case. |
Requesting a different advance rate
Omitting requestedAdvanceRate is the normal case: the client's facility rate applies, and most invoices never deviate from it.
Send a number to ask for more or less on one invoice — a strong debtor the client wants more cash against, or an invoice they only need part-funded. It is a request. Noja may apply a lower rate than asked, or the facility rate, and the response tells you which was used.
Read financing.advanceRate on the response for what actually applied, never the rate you sent. A higher requested rate also draws more headroom, so it can be the reason a later invoice in the same batch no longer fits.
Send each invoice as it is issued. POST /invoices/batch exists for the onboarding backfill, not as the steady state.
What financingIntent is for
Two arrangements exist outside the standard facility, and this field is how you express them. Most integrations never set it.
Client's financingMode |
Omitted | exclude |
include |
|---|---|---|---|
whole_book (standard) |
Assessed | Withheld from financing, stays as collateral | — |
selective (by agreement) |
Not assessed | — | Assessed |
exclude covers a client who wants one invoice kept out — a disputed amount, or a debtor they would rather handle themselves. The invoice still reaches Noja, still counts as collateral, and is still collected.
include only applies to clients Noja has put on a selective arrangement, which is not the standard product. If you are not sure which mode a client is on, read financingMode from their facility terms.
Eligibility closes at the due date
A receivable is assessable only while its due date has not passed, which is why invoices should reach Noja as they are issued rather than in a nightly sweep.
An overdue receivable is not a financing candidate — it is a collection matter. It still belongs in the book as collateral; it simply will not be advanced against, and no later event makes it eligible again.
Send an invoice¶
Request¶
| Field | Type | Notes | |
|---|---|---|---|
client |
object | Required | countryCode + registrationNumber |
invoiceNumber |
string | Required | Your number. Unique per client; resending updates. |
direction |
enum | Required | receivable or payable |
counterparty |
object | Required | The debtor for receivables, the supplier for payables |
counterparty.name |
string | Required | Always required |
counterparty.type |
enum | Required | company, association, public_institution or person |
counterparty.registrationNumber |
string | Optional | Company registration number when you have it — materially improves scoring |
counterparty.countryCode |
string | Optional | Defaults to the client's country |
amount |
money | Required | Gross, minor units |
issueDate |
date | Required | |
dueDate |
date | Required | |
requestedAdvanceRate |
number | Optional | 0–100. Omit to use the client's facility rate |
financingIntent |
enum | Optional | exclude or include. Omit for the standard facility behaviour |
credited |
boolean | Optional | true if this document is a credit note. Defaults to false |
partnerStatus |
string | Optional | Your own status label — stored, echoed back, never interpreted |
document |
object | Optional | The invoice PDF or image — see Attaching the document |
vatAmount |
money | Optional | |
paymentStatus |
enum | Optional | open, paid, partially_paid, credited, written_off |
paymentDate |
date | Optional | Required when paymentStatus is paid |
paidAmount |
money | Optional | Required when paymentStatus is partially_paid |
reference |
string | Optional | Payment reference as printed on the invoice |
currency |
string | Optional | Defaults to EUR; carried inside each money object |
lineItems |
array | Optional | See Line items |
{
"client": { "countryCode": "NL", "registrationNumber": "68123456" },
"invoiceNumber": "2026-0417",
"direction": "receivable",
"counterparty": {
"name": "Bouwgroep Rotterdam B.V.",
"type": "company",
"registrationNumber": "24398871",
"countryCode": "NL"
},
"amount": { "amount": 424250, "currency": "EUR" },
"vatAmount": { "amount": 73625, "currency": "EUR" },
"issueDate": "2026-08-30",
"dueDate": "2026-09-29",
"paymentStatus": "open",
"credited": false,
"reference": "0417 2026 VDI",
"partnerStatus": "sent"
}
{
"client": { "countryCode": "NL", "registrationNumber": "68123456" },
"invoiceNumber": "INK-2026-0912",
"direction": "payable",
"counterparty": {
"name": "Technische Unie B.V.",
"type": "company",
"registrationNumber": "30031444"
},
"amount": { "amount": 187300, "currency": "EUR" },
"issueDate": "2026-09-01",
"dueDate": "2026-09-15",
"paymentStatus": "paid",
"paymentDate": "2026-09-12"
}
Response · 201¶
{
"invoiceId": "0193f31a-77bd-7c02-bb14-9e0f2a4c8d31",
"invoiceNumber": "2026-0417",
"direction": "receivable",
"paymentStatus": "open",
"credited": false,
"partnerStatus": "sent",
"financing": {
"state": "pending",
"requestedAdvanceRate": null,
"advanceRate": 80,
"amountFinanceable": { "amount": 339400, "currency": "EUR" },
"expectedDecisionBy": "2026-09-14T10:05:00Z"
},
"createdAt": "2026-09-14T09:47:12Z"
}
amountFinanceable is the invoice amount multiplied by advanceRate — the rate Noja will apply, which is the client's facility rate unless this invoice requested another and Noja accepted it. requestedAdvanceRate echoes what you asked for, or null if you asked for nothing. Both are estimates until a decision lands, at which point amountApproved is authoritative.
Line items¶
Optional, but they improve scoring on financed invoices and are what a reviewer looks at when an invoice is queued for manual attention.
| Field | Type | Notes | |
|---|---|---|---|
description |
string | Required | What was sold |
quantity |
number | Optional | Decimals allowed |
unitPrice |
money | Optional | Minor units, excluding VAT |
vatRate |
number | Optional | Percentage, e.g. 21 |
unit |
string | Optional | Free text, e.g. hour, piece |
productCode |
string | Optional | Your article or SKU code |
{
"lineItems": [
{
"description": "Installation labour",
"quantity": 18.5,
"unitPrice": { "amount": 8500, "currency": "EUR" },
"vatRate": 21,
"unit": "hour"
},
{
"description": "Heat pump — model WP-240",
"quantity": 1,
"unitPrice": { "amount": 268000, "currency": "EUR" },
"vatRate": 21,
"productCode": "WP-240"
}
]
}
Line items are not reconciled against amount. If they disagree, amount wins — it is the figure financing is calculated from.
Attaching the document¶
Send the invoice PDF or image inline. Optional, and only worth doing for invoices you may want financed — a reviewer can then see the document without asking you for it.
| Field | Type | Notes | |
|---|---|---|---|
document.contentBase64 |
string | Required | Base64-encoded file bytes |
document.mediaType |
string | Required | application/pdf, image/jpeg, image/png or image/tiff |
document.filename |
string | Optional | Shown to reviewers |
{
"document": {
"filename": "2026-0417.pdf",
"mediaType": "application/pdf",
"contentBase64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9..."
}
}
Maximum 10 MB decoded. A base64 payload inflates by roughly a third, so keep the encoded string under about 13 MB and stay inside the 256 KB body cap by sending documents on the single-invoice endpoint rather than in a batch.
Credit notes¶
Set credited: true and send the credit note as its own invoice, with amount as a positive number. Link it to what it credits with creditsInvoiceNumber:
{
"invoiceNumber": "2026-0417-CN",
"credited": true,
"creditsInvoiceNumber": "2026-0417",
"amount": { "amount": 42425, "currency": "EUR" },
"direction": "receivable"
}
A credit note against a financed invoice reduces the amount outstanding. Credit notes cannot themselves be financed — financingIntent: include on one returns 422 validation_failed.
Invoice states¶
An invoice carries two independent statuses. Keeping them apart matters: an invoice can be overdue and financed at the same time.
paymentStatus — the debtor payment lifecycle. You set it; Noja also updates it from bank reconciliation once an invoice is financed.
| Value | Meaning |
|---|---|
open |
Issued, not yet paid |
partially_paid |
Part of the amount received |
paid |
Paid in full |
overdue |
Past due and not settled |
credited |
Cancelled by a credit note |
written_off |
Abandoned |
financing.state — the financing lifecycle. Noja owns it entirely.
| Value | Meaning |
|---|---|
not_assessed |
In the book as collateral, not put forward for financing. |
pending |
Being assessed, decision not yet made. Covers both scoring in progress and waiting on client approval. |
financing_approved |
Approved. financing.amountApproved is payable. |
financing_rejected |
Declined for this invoice. financing.reason explains why. |
financed |
Paid out to the client. |
rejected |
Declined terminally — do not resubmit. |
Settlement is not a financing state. Once the debtor pays a financed invoice, paymentStatus becomes paid and financing.settledAt is stamped.
Payables are required, but never financed
A payable invoice stays at financing.state: not_assessed for life. Setting financingIntent: include on one returns 422 validation_failed.
They are still mandatory. Payables are what turn gross receivables into a net cash-flow position, and the limit is set on the net figure.
Backfilling the book¶
The call you use once per client at onboarding, to load the twelve months behind them. Up to 1,000 invoices per request, processed asynchronously. Partial success is normal: valid rows land, invalid rows are reported individually.
This is not the steady-state path. Once a client is live, send each invoice through POST /invoices as it is issued — a nightly batch leaves the book, and therefore every exposure figure, a day stale.
{
"client": { "countryCode": "NL", "registrationNumber": "68123456" },
"invoices": [
{ "invoiceNumber": "2026-0388", "direction": "receivable", "...": "..." },
{ "invoiceNumber": "2026-0389", "direction": "receivable", "...": "..." }
]
}
{
"jobId": "0193f33c-1a02-7d55-8e77-4b1c9f0a2e88",
"status": "processing",
"received": 284,
"pollAfter": "2026-09-14T09:33:00Z"
}
Backfilled invoices are never assessed for financing, regardless of what you send: a backfill is historical, and historical invoices are past their due date. They land as collateral and payment history, which is what the backfill is for.
Check a batch¶
{
"jobId": "0193f33c-1a02-7d55-8e77-4b1c9f0a2e88",
"status": "completed",
"received": 284,
"accepted": 281,
"rejected": 3,
"errors": [
{
"invoiceNumber": "2026-0402",
"code": "validation_failed",
"fields": { "dueDate": "before_issue_date" }
}
],
"completedAt": "2026-09-14T09:34:48Z"
}
Fix and resend only the rejected rows. Accepted rows are already stored.
Update an invoice¶
Two uses. Flip an existing invoice to financing, or correct the payment outcome of a historical one.
Change a financing intent or advance rate¶
Withholds an invoice that would otherwise be assessed, puts one forward on a selective client, or revises the share requested. Only while the due date has not passed, and only before a decision has been made — once Noja has decided, the rate is fixed and a change returns 409 not_financeable.
Returns 409 not_financeable if the due date has passed, or if the invoice is settled, credited, or already financed. The due-date case is terminal.
Where this belongs in your product
For a standard whole-turnover client, nowhere. There is no decision for the user to make at invoice time, and offering one invites them to cherry-pick, which is what the facility exists to prevent.
Show them what the facility is doing instead: which invoices were advanced, at what rate, and how much headroom is left.
Update your own status¶
Free text. Noja stores it, returns it, and lets you filter on it, but never acts on it.
Attach the document later¶
Send the same document object accepted on create. Useful when the PDF is generated after the invoice record.
Correct a historical invoice¶
{
"paymentStatus": "paid",
"paymentDate": "2026-09-08",
"paidAmount": { "amount": 424250, "currency": "EUR" }
}
Optional. We treat history as a snapshot, so a stale payment status on a closed invoice degrades scoring only marginally — keeping it current is a refinement, not an obligation.
What you cannot change
financing.state, the decision fields, and every credit field are Noja-owned and read-only. Attempting to set them returns 422 naming the field.
You also cannot change amount, issueDate, or counterparty on an invoice that has already been financed — send a credit note as a new invoice instead.
List invoices¶
Filters¶
| Parameter | Accepts | Example |
|---|---|---|
client |
country and registration number | NL/68123456 |
direction |
receivable, payable |
receivable |
paymentStatus |
any payment status, repeatable | overdue |
financingState |
any financing state, repeatable | financing_approved |
financingIntent |
exclude, include |
exclude |
advanceRateApplied |
number, exact match | 60 |
credited |
true, false |
false |
counterpartyType |
company, association, public_institution, person |
company |
counterpartyRegistrationNumber |
exact match | 24398871 |
partnerStatus |
exact match on your own label | sent |
issuedFrom / issuedTo |
dates | 2026-01-01 |
dueFrom / dueTo |
dates | 2026-09-30 |
updatedSince |
timestamp | 2026-09-14T00:00:00Z |
Repeatable parameters are OR-ed within themselves and AND-ed across: ?paymentStatus=open&paymentStatus=overdue&direction=receivable returns open or overdue receivables.
Pagination¶
Cursor-based. Follow nextCursor until hasMore is false; page size is fixed by us and may change, so never assume a count.
cursor=""
while :; do
page=$(curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.noja.fi/partner/v1/invoices?client=NL/68123456&cursor=$cursor")
echo "$page" | jq -r '.invoices[].invoiceNumber'
[ "$(echo "$page" | jq -r .hasMore)" = "true" ] || break
cursor=$(echo "$page" | jq -r .nextCursor)
done
A cursor is valid for one hour and encodes the filters it was created with — changing a filter mid-walk invalidates it. Use this to reconcile, not to poll: webhooks carry changes as they happen.
Read one invoice¶
{
"invoiceId": "0193f31a-77bd-7c02-bb14-9e0f2a4c8d31",
"invoiceNumber": "2026-0417",
"client": { "countryCode": "NL", "registrationNumber": "68123456" },
"direction": "receivable",
"paymentStatus": "open",
"credited": false,
"partnerStatus": "sent",
"amount": { "amount": 424250, "currency": "EUR" },
"issueDate": "2026-08-30",
"dueDate": "2026-09-29",
"daysOverdue": 0,
"counterparty": {
"name": "Bouwgroep Rotterdam B.V.",
"type": "company",
"registrationNumber": "24398871"
},
"hasDocument": true,
"financing": {
"state": "financing_approved",
"requestedAdvanceRate": null,
"advanceRate": 80,
"decidedAt": "2026-09-14T10:02:47Z",
"amountApproved": { "amount": 339400, "currency": "EUR" },
"fee": { "amount": 10182, "currency": "EUR" },
"expectedPayoutAt": "2026-09-14T16:00:00Z"
}
}
You can also fetch by your own number: GET /invoices?client=NL/68123456&invoiceNumber=2026-0417.