---
updatedAt: 2026-01-26T14:38:29.000Z
agentTools:
  projectIndex: https://developer.candis.io/llms.txt
---

# Candis Invoice Data API

Read-only access to invoice metadata for archival and reporting purposes.

The Candis Invoice Data API provides a structured view of invoices stored in Candis.
It is designed for retrieving and maintaining invoice metadata for reference, monitoring, and high-level analysis — not for accounting or bookkeeping exports.

While the API is primarily read-only, it includes a limited update capability for maintaining payment status metadata.

## Retrieve invoices

Provides access to invoice metadata for an organization.

### Purpose

This endpoint offers an archival view of invoices in Candis. It is intended for retrieving structured, read-only invoice information for reference, monitoring, and reporting use cases.

## What to expect from this endpoint

The endpoint returns a paginated list of invoices for an organization.

For each invoice, the response may include:

**Invoice lifecycle and status information**
Creation, update, request, and approval timestamps, as well as the current invoice status.

**Monetary and payment-related data**
Invoice amounts, currency, discounts, payment terms, payment method, payment status, and relevant payment dates.

**Invoice metadata and references**
Invoice number, document type, purchase order number, delivery date, invoice date, and contact information.

**Basic bank and payment metadata**
Bank account information and automatic payment flags, if available.

Note: Some fields depend on the organization’s configuration or enabled add-ons and may not be present in all responses.

## What this endpoint is not designed for

**No invoice documents or images**
This endpoint does not return PDF files or scanned invoice documents. Only structured metadata is provided, together with a reference (archiveUrl) to the archived document.

**Not an accounting export**
The Invoice Data API is not intended for accounting or bookkeeping use cases.
While invoices may contain limited booking-related information, the data is neither complete nor guaranteed to be suitable for accounting exports.

For reliable and complete accounting data — including ledger accounts, tax logic, and export-specific structures — use the Export API.

### Typical use cases

This endpoint is suitable for:

* building invoice archives or overview lists,
* monitoring invoice and payment status,
* generating high-level reports and KPIs based on invoice metadata,
* synchronizing invoice lists with external systems for reference purposes.

For accounting, posting, or tax-relevant data processing, use the Export API.

## Update an invoice

Updates selected invoice metadata.
Currently, this endpoint is intended exclusively for maintaining payment status information (for example, marking an invoice as paid).

### Endpoint

PUT
<https://api.candis.io/v1/organizations/{organizationId}/invoices/{id}>

Path parameters

* organizationId (string, required)
  The organization ID.
* id (string, required)
  Unique identifier of the invoice.

### Request body

Invoice update payload

payment (object)

Payment information.

* isPaid (boolean, required)
  Indicates whether the invoice is paid.
* paidAt (date-time)
  Date when the invoice was paid.
  Required when isPaid is true.

### Validation rules

* If payment.isPaid is true, payment.paidAt must be provided.
* If payment.isPaid is false, payment.paidAt should be omitted (or will be ignored, depending on implementation).

### Notes and limitations

* This endpoint does not modify invoice documents or files.
* Only explicitly supported metadata fields can be updated.
* This endpoint is not an accounting interface.

For accounting exports, ledger postings, tax logic, or booking-relevant structures, use the Export API.