Invoices
List invoices
Credential: a company's API key or OAuth token.
Returns a paginated list of invoices for your company, optionally filtered by status, customer, billing group and subscription.
Filtering by subscriptionId returns every invoice the subscription was billed on — including the invoices
addressed to another subscription that carry its lines, which is how an add-on is billed: on its parent's
invoice. Each line of a single invoice names the subscription it was billed for in its own subscriptionId.
Required Scope
invoices-read
query Parameters
cursorOpaque cursor from the previous response's nextCursor. Returns the rows after it, in the same order. Send the same filters and sort as the request that produced it, and do not send page. The preferred way to page through a list.
pageDeprecated: page with cursor instead. Page number (1-indexed). From 2026-12-31, a page past the first of a list with more than 10,000 matching rows is refused.
limitNumber of items per page
searchFree-text search (invoice number, description)
statusFilter invoices by status
customerIdFilter invoices for a specific customer
billingGroupIdFilter to the shared invoices issued to one billing group
subscriptionIdFilter to the invoices a subscription was billed on: the ones addressed to it, and the ones that carry its lines while addressed to another subscription or to a billing group. An add-on bills on its parent’s invoice, so filtering by the add-on returns the parent’s invoices that carry the add-on’s lines. An unknown subscription returns an empty list.
List invoices › Responses
Paginated list of invoices
Invoices on this page (line items omitted; GET one invoice for lines)
totalTotal invoices matching the query
limitItems per page
nextCursorCursor for the next page; pass it as cursor. null on the last page, and on every page of a sort that cannot page by cursor — hasMore then says whether another page follows by page number.
hasMoreWhether more rows follow this page.
pageDeprecated: page with nextCursor instead. Current page (1-indexed).
totalPagesDeprecated: page with nextCursor instead. Total pages.
Create a draft invoice
Credential: a company's API key or OAuth token.
Creates a draft invoice. The invoice number is allocated at booking time (when sent), so a draft has no number yet.
Negative totals
An invoice cannot have a negative total. When the lines add up to less than 0
(VAT included), the request fails with 400 and INVOICE_INVALID_SIGN, and
no invoice is created. The document for a negative total is a credit note —
create it with POST /v1/credit-notes. A total of exactly 0 is accepted.
Required Scope
invoices-write
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Create a draft invoice › Request Body
customerIdCustomer ID this invoice is for. Required — every invoice must reference a customer (this mirrors the gated app, which also requires a customer).
dateInvoice date (ISO date, YYYY-MM-DD)
Invoice lines
customerDepartmentIdCustomer department ID (for EAN-based e-invoicing and address override)
customerContactIdCustomer contact ID (invoice recipient)
dueDateDue date for payment (ISO date). Derived from payment terms when omitted.
currencyCurrency code (ISO 4217). Defaults to the company default currency.
paymentTermsPayment terms in days
referenceReference / PO number ("PO-nr.")
ourReferenceOur reference ("Vores ref.")
descriptionInternal description for your own reference. Never printed on the PDF or shown to the customer: put text for the customer in subject and notes.
subjectHeading printed in bold on the PDF, directly above notes. The customer sees it on the document.
notesMessage printed on the PDF under subject. The customer sees it on the document.
tagIdsTag/Dimension value IDs to attach to the journal entry when this invoice is booked. A dimension value here applies to every line, and counts toward a dimension the line's account requires. Use the per-line tagIds for a dimension that differs between lines.
discountIdsDocument-scope discount records to apply once to the whole document, after every line discount, reducing the lines whose product each applies to (every line when it names no product). Each id is a discount record (see GET /discounts). The order sent is the order they apply in. Each is checked for the line's product, the document's customer and the document date; a document converted from a quote is checked at the quote's date. A fixed or per-unit discount takes its amount in the document's currency: a discount with no amount in that currency is refused, never converted at an exchange rate. One applies when it applies to the customer and to at least one line's product. Refused with: DISCOUNT_NOT_APPLICABLE (no such discount in your company, inactive, not assigned to this product and customer, or outside its dates on the document date; details.reason says which), DISCOUNT_WRONG_SCOPE, DISCOUNT_REFERENCED_TWICE, DISCOUNT_NOT_COMBINABLE, DISCOUNT_NO_AMOUNT_IN_CURRENCY, DISCOUNT_LINE_WITHOUT_PRODUCT, DISCOUNT_EXCEEDS_LINE and DISCOUNT_EXCEEDS_DOCUMENT.
discountCodesDiscount codes the customer gave, the same list sent to POST /discounts/check, matched without regard to case or surrounding spaces and applied after discountIds in the order sent. A code claims its discount, which then applies as if named by id, including one that applies only through a code: a line-scope discount lands on every line whose product it applies to, a document-scope one on the document. The code's own limit is counted when the invoice is booked, refused there with DISCOUNT_CODE_REDEMPTION_LIMIT_REACHED. A code naming a discount already named is applied once. Refused with: DISCOUNT_CODE_INVALID (empty, spaces or too long) and DISCOUNT_NOT_APPLICABLE with details.reason codeUnknown, codeInactive, codeExpired or codeCustomerMismatch and details.code, beside every refusal discountIds lists.
Create a draft invoice › Responses
Invoice created successfully
idInvoice ID
statusInvoice status
dateInvoice date (ISO date)
isConsolidatedTrue when this invoice consolidates several subscriptions onto one document: a billing group’s shared invoice, or a parent customer’s invoice covering its child customers’ subscriptions. With both customerSubscriptionId and billingGroupId null it is the parent-paid kind.
currencyCurrency code (ISO 4217)
subtotalSubtotal before VAT (decimal string)
vatVAT amount (decimal string)
amountTotal amount including VAT (decimal string)
Invoice lines
The document-scope discount records the document referenced, in the order they applied, each applied once after every line discount. Empty when it referenced none.
totalDiscountedWhat the document's discounts took off in all, in the document's currency: each line's amount before discounts less its amount after them, plus the document discounts. A line discount typed by hand in LedgerBee counts too. Null when the document references no discount record.
createdAtCreation timestamp (ISO)
updatedAtLast update timestamp (ISO)
numberInvoice number. Null while the invoice is still a draft (allocated at booking).
dueDateDue date (ISO date)
customerIdCustomer ID
customerSubscriptionIdThe subscription this invoice bills, when it bills exactly one. Its lines may also include the subscriptions billed as part of that subscription’s section, which carry no section of their own. Null on a billing group’s shared invoice (see billingGroupId), on a parent-paid consolidated invoice (see isConsolidated) and on a manually created invoice.
billingGroupIdThe billing group this invoice is issued to, when several of one customer’s subscriptions bill onto it. Set instead of customerSubscriptionId, never alongside it. Filter the list by billingGroupId to find a group’s documents.
referenceReference / PO number
ourReferenceOur reference ("Vores ref.")
subjectHeading printed in bold on the PDF, directly above notes. The customer sees it on the document.
notesMessage printed on the PDF under subject. The customer sees it on the document.
Get an invoice
Credential: a company's API key or OAuth token.
Retrieves a single invoice by its unique identifier. Returns 404 when the
invoice does not exist in your company. For the rendered document, use the
PDF endpoint.
Required Scope
invoices-read
path Parameters
idInvoice ID
Get an invoice › Responses
The invoice
idInvoice ID
statusInvoice status
dateInvoice date (ISO date)
isConsolidatedTrue when this invoice consolidates several subscriptions onto one document: a billing group’s shared invoice, or a parent customer’s invoice covering its child customers’ subscriptions. With both customerSubscriptionId and billingGroupId null it is the parent-paid kind.
currencyCurrency code (ISO 4217)
subtotalSubtotal before VAT (decimal string)
vatVAT amount (decimal string)
amountTotal amount including VAT (decimal string)
Invoice lines
The document-scope discount records the document referenced, in the order they applied, each applied once after every line discount. Empty when it referenced none.
totalDiscountedWhat the document's discounts took off in all, in the document's currency: each line's amount before discounts less its amount after them, plus the document discounts. A line discount typed by hand in LedgerBee counts too. Null when the document references no discount record.
createdAtCreation timestamp (ISO)
updatedAtLast update timestamp (ISO)
numberInvoice number. Null while the invoice is still a draft (allocated at booking).
dueDateDue date (ISO date)
customerIdCustomer ID
customerSubscriptionIdThe subscription this invoice bills, when it bills exactly one. Its lines may also include the subscriptions billed as part of that subscription’s section, which carry no section of their own. Null on a billing group’s shared invoice (see billingGroupId), on a parent-paid consolidated invoice (see isConsolidated) and on a manually created invoice.
billingGroupIdThe billing group this invoice is issued to, when several of one customer’s subscriptions bill onto it. Set instead of customerSubscriptionId, never alongside it. Filter the list by billingGroupId to find a group’s documents.
referenceReference / PO number
ourReferenceOur reference ("Vores ref.")
subjectHeading printed in bold on the PDF, directly above notes. The customer sees it on the document.
notesMessage printed on the PDF under subject. The customer sees it on the document.
Delete a draft invoice
Credential: a company's API key or OAuth token.
Deletes a draft or scheduled invoice.
Only an invoice that has not been sent can be deleted: a draft, or a scheduled
one waiting for its send time. An invoice in any other status answers 400
with INVOICE_DELETION_FORBIDDEN; correct a sent invoice with a credit note
(POST /v1/credit-notes).
A draft is also kept when it is waiting for an approver
(INVOICE_APPROVAL_PENDING), when a shipment refers to its lines
(INVOICE_DELETION_BLOCKED_BY_SHIPMENT), when a card payment for it took
money, may still take it, or holds an amount on the buyer's card
(INVOICE_DELETION_BLOCKED_BY_CARD_CHARGE), or when revenue recognition has
already posted for it (INVOICE_DELETION_FORBIDDEN).
Deleting a draft that subscription billing created does not bill that period again.
Required Scope
invoices-write
path Parameters
idInvoice ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Delete a draft invoice › Responses
Invoice deleted
Update an unsent invoice
Credential: a company's API key or OAuth token.
Changes an invoice that has not been sent: a draft, or one scheduled to send.
Send null to clear a clearable field (customerDepartmentId,
customerContactId, reference, ourReference, description, notes,
tagIds). Returns the updated invoice.
A field you leave out keeps its stored value, with these exceptions:
- A request with
dateorpaymentTermsand nodueDatesets the due date from the payment terms, when the invoice has payment terms. - A new
customerIdremoves the department and contact unless the request states new ones, and removes any extra email recipients. - An approved invoice whose content changes loses its approval. If it was scheduled to send, it returns to draft.
Lines
lines replaces every stored line, so send the full intended set. Leave it out
to keep the lines as they are. Prices, totals and VAT are worked out
server-side: prices in the invoice's currency, VAT from the customer's VAT zone.
Changing customerId or currency requires lines in the same request
(INVOICE_CUSTOMER_OR_CURRENCY_CHANGE_REQUIRES_LINES), so the lines are
priced and taxed for the new values.
INVOICE_LINE_UPDATE_NOT_SUPPORTED refuses lines on these invoices, and
details.reason says which:
subscription: subscription billing created the invoice, or a line bills a subscription.self_billing: a self-billed invoice.shipment: a shipment refers to the invoice's lines.
The other fields of such an invoice can be changed, except customerId and
currency, which require lines.
A line that defers its revenue (recognitionPeriodDays) can be replaced like
any other: its revenue schedule is written again from the lines and the date
the invoice ends up with.
Sent invoices
An invoice that has been sent is booked and cannot be changed
(INVOICE_MODIFICATION_FORBIDDEN). Correct it with a credit note
(POST /v1/credit-notes).
Required Scope
invoices-write
path Parameters
idInvoice ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update an unsent invoice › Request Body
customerIdCustomer the invoice is for. Changing it requires lines in the same request, because each line's VAT is worked out from the customer's VAT zone. A change removes the department and contact unless the request states new ones, and removes any extra email recipients.
customerDepartmentIdCustomer department ID (for EAN-based e-invoicing and address override). Send null to remove the department.
customerContactIdCustomer contact ID (invoice recipient). Send null to remove the contact.
dateInvoice date (ISO date, YYYY-MM-DD). The due date follows it when the invoice has payment terms and the request states no dueDate.
dueDateDue date for payment (ISO date). Must not be before the invoice date.
currencyCurrency code (ISO 4217). Changing it requires lines in the same request, so the amounts are priced in the new currency.
paymentTermsPayment terms in days. The due date follows it when the request states no dueDate.
referenceReference / PO number ("PO-nr."). Send null to clear it.
ourReferenceOur reference ("Vores ref."). Send null to clear it.
descriptionInternal description for your own reference. Never printed on the PDF or shown to the customer: put text for the customer in subject and notes. Send null to clear it.
subjectHeading printed in bold on the PDF, directly above notes. The customer sees it on the document. Leave it out to keep the stored subject; send null to clear it.
notesMessage printed on the PDF under subject. The customer sees it on the document. Send null to clear them.
tagIdsTag/Dimension value IDs to attach to the journal entry when this invoice is booked. Replaces the stored set; send null or an empty array to remove every value. At most 100 ids.
Invoice lines, at most 1000. Replaces every stored line, so send the full intended set. Leave it out to keep the lines as they are. Refused on an invoice billed for a subscription, a self-billed invoice, an invoice a shipment refers to, and when a stored or sent line defers its revenue (recognitionPeriodDays).
discountIdsDocument-scope discount records to apply once to the whole document, after every line discount, reducing the lines whose product each applies to (every line when it names no product). Each id is a discount record (see GET /discounts). The order sent is the order they apply in. Each is checked for the line's product, the document's customer and the document date; a document converted from a quote is checked at the quote's date. A fixed or per-unit discount takes its amount in the document's currency: a discount with no amount in that currency is refused, never converted at an exchange rate. One applies when it applies to the customer and to at least one line's product. On an update, leaving it out keeps the discounts the document has; an empty array removes them. A change to them is sent with lines, which they are priced from: without the lines it is refused with DISCOUNT_REPRICE_NEEDS_LINES, and so is a change of the customer, the date or the currency of an invoice that carries discounts. Refused with: DISCOUNT_NOT_APPLICABLE (no such discount in your company, inactive, not assigned to this product and customer, or outside its dates on the document date; details.reason says which), DISCOUNT_WRONG_SCOPE, DISCOUNT_REFERENCED_TWICE, DISCOUNT_NOT_COMBINABLE, DISCOUNT_NO_AMOUNT_IN_CURRENCY, DISCOUNT_LINE_WITHOUT_PRODUCT, DISCOUNT_EXCEEDS_LINE and DISCOUNT_EXCEEDS_DOCUMENT.
discountCodesDiscount codes the customer gave, the same list sent to POST /discounts/check, matched without regard to case or surrounding spaces and applied after discountIds in the order sent. A code claims its discount, which then applies as if named by id, including one that applies only through a code: a line-scope discount lands on every line whose product it applies to, a document-scope one on the document. The code's own limit is counted when the invoice is booked, refused there with DISCOUNT_CODE_REDEMPTION_LIMIT_REACHED. A code naming a discount already named is applied once. On an update, a discount the document carries through a code keeps that code when the update names the discount again without it. Codes are sent with lines, which they are priced from; without the lines they are refused with DISCOUNT_REPRICE_NEEDS_LINES. Refused with: DISCOUNT_CODE_INVALID (empty, spaces or too long) and DISCOUNT_NOT_APPLICABLE with details.reason codeUnknown, codeInactive, codeExpired or codeCustomerMismatch and details.code, beside every refusal discountIds lists.
Update an unsent invoice › Responses
The updated invoice
idInvoice ID
statusInvoice status
dateInvoice date (ISO date)
isConsolidatedTrue when this invoice consolidates several subscriptions onto one document: a billing group’s shared invoice, or a parent customer’s invoice covering its child customers’ subscriptions. With both customerSubscriptionId and billingGroupId null it is the parent-paid kind.
currencyCurrency code (ISO 4217)
subtotalSubtotal before VAT (decimal string)
vatVAT amount (decimal string)
amountTotal amount including VAT (decimal string)
Invoice lines
The document-scope discount records the document referenced, in the order they applied, each applied once after every line discount. Empty when it referenced none.
totalDiscountedWhat the document's discounts took off in all, in the document's currency: each line's amount before discounts less its amount after them, plus the document discounts. A line discount typed by hand in LedgerBee counts too. Null when the document references no discount record.
createdAtCreation timestamp (ISO)
updatedAtLast update timestamp (ISO)
numberInvoice number. Null while the invoice is still a draft (allocated at booking).
dueDateDue date (ISO date)
customerIdCustomer ID
customerSubscriptionIdThe subscription this invoice bills, when it bills exactly one. Its lines may also include the subscriptions billed as part of that subscription’s section, which carry no section of their own. Null on a billing group’s shared invoice (see billingGroupId), on a parent-paid consolidated invoice (see isConsolidated) and on a manually created invoice.
billingGroupIdThe billing group this invoice is issued to, when several of one customer’s subscriptions bill onto it. Set instead of customerSubscriptionId, never alongside it. Filter the list by billingGroupId to find a group’s documents.
referenceReference / PO number
ourReferenceOur reference ("Vores ref.")
subjectHeading printed in bold on the PDF, directly above notes. The customer sees it on the document.
notesMessage printed on the PDF under subject. The customer sees it on the document.
Get the delivery status of an invoice
Credential: a company's API key or OAuth token.
Returns an aggregate send summary plus a per-attempt delivery log for the invoice.
Required Scope
invoices-read
path Parameters
idInvoice ID
Get the delivery status of an invoice › Responses
Delivery status
Aggregate send summary
Per-attempt delivery log entries
Download the invoice PDF
Credential: a company's API key or OAuth token.
Streams the rendered invoice PDF. Pass draft=true to render a draft watermark version (generated on the fly).
Required Scope
invoices-read
path Parameters
idInvoice ID
query Parameters
draftRender a draft watermark version
Download the invoice PDF › Responses
Bad Request
statusCodetimestamppathmessageSend an invoice to the customer
Credential: a company's API key or OAuth token.
Sends the invoice over the chosen delivery channel (Email, Sproom e-invoicing, or Manual). Sending books the invoice and allocates its number.
Required Scope
invoices-write
path Parameters
idInvoice ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Send an invoice to the customer › Request Body
deliveryTypeDelivery channel
overrideEmailOverride recipient email for this send only
overrideEanNumberOverride EAN number for this send only
updateCustomerRecordPersist the override email / EAN onto the customer record
documentTemplateIdOverride document template for PDF generation
Send an invoice to the customer › Responses
Invoice send accepted
successWhether the send was accepted
deliveryTypeThe delivery channel the document was sent through
sproomDocumentIdSproom document ID when sent via e-invoicing