Skip to content

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

POST /invoices Partner writes

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
A receivable, financing wanted
{
  "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"
}
A payable
{
  "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

POST /invoices/batch Partner writes

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.

Request
{
  "client": { "countryCode": "NL", "registrationNumber": "68123456" },
  "invoices": [
    { "invoiceNumber": "2026-0388", "direction": "receivable", "...": "..." },
    { "invoiceNumber": "2026-0389", "direction": "receivable", "...": "..." }
  ]
}
Response · 202
{
  "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

GET /invoices/batch/{jobId} Noja writes
{
  "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

PATCH /invoices/{invoiceId} Partner writes

Two uses. Flip an existing invoice to financing, or correct the payment outcome of a historical one.

Change a financing intent or advance rate

{ "financingIntent": "exclude" }
{ "requestedAdvanceRate": 60 }

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

{ "partnerStatus": "credited" }

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

GET /invoices Noja writes

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.

{
  "invoices": [ "..." ],
  "nextCursor": "eyJvZmZzZXQiOjEwMH0",
  "hasMore": true
}
Walking every page
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

GET /invoices/{invoiceId} Noja writes
{
  "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.