Docs
API reference/Billing

Invoices

Invoices booked in your accounting provider for payments and subscription periods. Void them, mark them paid or email them to the payer.

Invoices are created by Borga when a payment succeeds, a bank invoice is issued or a subscription period ends, and mirrored to PayDay or DK+. See Invoicing. You cannot create or edit them through the API; add one-off charges to a subscription with invoice items. You can void an open invoice, mark one paid when the money arrived outside Borga, and email an invoice to the payer.

The invoice object

idstring
Prefixed inv_.
customerstring | null
paymentstring | null
The payment that paid it, for one-off sales and card-collected subscription invoices.
statusenum
draft, open, paid, void or sync_failed.
subtotalinteger
taxinteger
totalinteger
credit_appliedinteger
Customer credit applied after tax: proration and pause credits the customer was owed. The invoice keeps its full lines and VAT; the credit pays part of it.
amount_dueinteger
total less credit_applied: what is collected. 0 when credit covered the invoice, which is then paid at once.
amount_paidinteger
currencystring
accounting_providerenum | null
payday or dk.
external_invoice_idstring | null
The provider's id.
external_invoice_numberstring | null
The legal invoice number issued by the provider. PayDay can assign it shortly after the invoice is created, so it may be null for up to a minute, including in invoice.created and invoice.finalized events; retrieving the invoice reads it from PayDay.
pdf_urlstring | null
Provider-hosted PDF, when available.
sync_error_messagestring | null
Set when status is sync_failed.
external_referencestring | null
Copied from the payment.
billingobject
name, email, kennitala, vat_number, address used on the invoice.
tax_exemptenum | null
The customer's VAT status when the invoice was built: exempt or reverse when every line booked at 0%, otherwise null.
tax_breakdownarray
Present when retrieving: tax by rate, highest first, each with tax_rate, taxable_amount (the net at that rate) and tax_amount.
linesarray
Present when retrieving: id, description, quantity, unit_amount (including tax), unit_amount_excluding_tax, tax_behavior (exclusive when the line came from a net price, item or line item), tax_rate, tax_amount (the tax inside the line), accounting_code, and for subscription lines the service period as period_start, period_end and proration_factor (1 for a whole period, the fraction billed otherwise; null on one-off lines).
subscriptionstring | null
The subscription it bills, for subscription invoices.
due_datestring | null
YYYY-MM-DD the bank claim is due.
bank_claimobject | null
For invoices collected by bank invoice: payment_reference (KID) and creditor_account (IBAN, when the provider reports it).
paid_out_of_bandboolean
true when it was marked paid outside Borga.
last_sent_attimestamp | null
When Borga last emailed it to the payer.
finalized_attimestamp | null
paid_attimestamp | null
voided_attimestamp | null
created_attimestamp

Retrieve an invoice

GET/v1/invoices/:idSecret key
curl https://api.borga.is/v1/invoices/inv_3Ef5Gh7Ij9Kl1Mn3Op5Qr7St \
  -H "Authorization: Bearer sk_test_…"

List invoices

GET/v1/invoicesSecret key

Query parameters

statusenum
limitintegerdefault: 25
starting_afterstring
Node.jsts
const { data, has_more } = await borga.invoices.list({ status: "paid", limit: 50 });

for (const invoice of data) {
  console.log(invoice.external_invoice_number, invoice.total, invoice.pdf_url);
}

if (has_more) {
  const next = await borga.invoices.list({
    status: "paid",
    starting_after: data[data.length - 1].id,
  });
  console.log(next.data.length);
}

Void an invoice

POST/v1/invoices/:id/voidSecret key

Voids an open invoice so it can no longer be paid, and stops any payment retries for it. A subscription that was past_due because of it becomes active again. Sends invoice.voided.

With PayDay, Borga cancels the invoice in PayDay first, which also cancels its bank claim, so the payer can no longer pay it in their online bank. If the payer has already paid the claim, the request fails with provider_error and Borga marks the invoice paid on its next check of the claim. DK+ invoices are voided in Borga only; cancel the invoice in DK+ as well.

A paid invoice cannot be voided (invoice_not_voidable); refund the payment instead. An invoice that failed to sync and never collected money can be voided.

curl -X POST https://api.borga.is/v1/invoices/inv_3Ef5Gh7Ij9Kl1Mn3Op5Qr7St/void \
  -H "Authorization: Bearer sk_test_…"

Mark an invoice paid

POST/v1/invoices/:id/paySecret key

Records that an open invoice was paid outside Borga, for example by bank transfer or in cash. Nothing is charged. Borga marks the invoice paid in your accounting provider, which also settles a PayDay bank claim, and sends invoice.paid with paid_out_of_band: true. A bank invoice from checkout also sends payment.succeeded for its payment.

Body

paid_out_of_bandbooleanrequired
Must be true.
curl -X POST https://api.borga.is/v1/invoices/inv_3Ef5Gh7Ij9Kl1Mn3Op5Qr7St/pay \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "paid_out_of_band": true }'

Send an invoice

POST/v1/invoices/:id/sendSecret key

Emails the invoice PDF from your accounting provider to the payer's billing email, or the customer's email when the invoice has none. Replies go to your merchant email. For an open invoice the email says how to pay: the bank claim's reference and due date, or a "Pay now" link to the customer portal that works for 24 hours when the invoice can be paid by card there. Works for open and paid invoices, at most once a minute per invoice. In test mode the subject starts with [Test]. Sends invoice.sent.

curl -X POST https://api.borga.is/v1/invoices/inv_3Ef5Gh7Ij9Kl1Mn3Op5Qr7St/send \
  -H "Authorization: Bearer sk_test_…"