API Changelog

This page tracks additions and changes to the faktoora public API and its documentation. All changes are backwards-compatible unless noted otherwise.

June 2026

Invoice subject field

POST /invoices now accepts an optional subject field on each invoice. It sets the subject line shown on the rendered PDF document; it is not part of the structured e-invoice XML (ZUGFeRD / XRechnung / Peppol). When omitted, the subject continues to default to Rechnung vom <issueDate> (formatted DD.MM.YYYY), so existing integrations are unaffected.

April 2026

Recurring Invoices API

New public API endpoints for managing automated invoice schedules. Create recurring invoices on a weekly, monthly, quarterly, yearly, or custom schedule with optional auto-delivery by email.

Endpoint	Description
`POST /recurring-invoice`	Create a new recurring schedule (immediately active)
`GET /recurring-invoices`	List schedules with pagination, filtering, and sorting
`GET /recurring-invoice/{id}`	Get a single schedule
`PATCH /recurring-invoice/{id}`	Update schedule or template fields
`PATCH /recurring-invoice/{id}/{status}`	Change status (active, paused, cancelled)

Requires the RECURRING_INVOICE subscription feature. See Recurring Invoices for full documentation.

March 2026

Invoice Validation

Outgoing invoices can now be validated against XRechnung/ZUGFeRD standards via the API. Validation runs asynchronously after invoice file generation. Requires the invoiceValidation feature.

New/updated endpoints:

Endpoint	Description
`POST /invoices`	New optional `validate: true` parameter triggers validation after file generation
`GET /invoices/{faktooraId}/status`	Response now includes a `validation` object with `status`, `validity`, and `createdAt`
`GET /invoices/{faktooraId}/validation-report`	Download the PDF validation report for the most recent validation

See Outgoing Invoices — Invoice Validation for details.

Invoice Number API

New endpoints for generating, verifying, and configuring invoice numbers programmatically. Previously invoice number management was only available through the UI.

New endpoints:

Endpoint	Description
`GET /invoices/next-number`	Generate the next available invoice number using a configurable template
`GET /invoices/verify-number`	Check whether a specific invoice number is already in use
`GET /settings/invoice-number-template`	Get the current template, pad length, and counter
`PUT /settings/invoice-number-template`	Update the template pattern and/or pad length

Templates support date tokens (YYYY, MM, DD) with a separator and auto-incrementing counter — e.g., YYYY/MM/id produces 2026/03/0042. The number is verified for uniqueness on generation.

MCP tools: get_next_invoice_number, verify_invoice_number, get_invoice_number_template, update_invoice_number_template — same functionality available to MCP clients.

See Invoice Numbers for the full guide.

Skonto (Early Payment Discount) in Payment Terms

specifiedTradePaymentTerms in POST /invoices now accepts optional day and percentage fields as a structured alternative to manually encoding the #SKONTO#TAGE=X#PROZENT=Y# description string.

{
  "specifiedTradePaymentTerms": [{
    "dueDateTime": "20260430",
    "day": 14,
    "percentage": 2.25
  }]
}

If a description field is also provided with the encoded #SKONTO# format, the description takes precedence. The structured fields are only used when description is empty.

MCP Server

The faktoora API now exposes an MCP (Model Context Protocol) server, allowing AI agents and MCP-compatible clients to interact with the API using natural language tooling.

The MCP server is available at POST /api/v1/mcp and authenticates via your existing API key. It supports the full Streamable HTTP transport defined in the MCP specification.

Supported tools (60 total across six domains):

Domain	Example tools
Invoices	`create_invoice_xrechnung`, `create_invoice_zugferd2`, `get_invoice_status`, `delete_invoice`, `list_invoices`
Incoming invoices	`import_incoming_invoice`, `list_incoming_invoices`, `get_incoming_invoice_summary`
Outgoing import	`import_outgoing_invoice`, `list_outgoing_invoices`, `get_outgoing_invoice_content`
Customers	`create_customer`, `list_customers`, `get_customer`, `update_customer`, `delete_customer`
Products	`create_product`, `list_products`, `create_product_bundle`
Webhooks	`create_webhook`, `list_webhooks`, `delete_webhook`

See MCP Server for setup instructions and the full tool reference.

Products & Product Bundles API

The full Products API is now documented and available. You can manage your product and service catalog programmatically without going through the UI.

New endpoints:

Endpoint	Description
`GET /products`	List products with pagination, keyword search, and sort
`GET /product/:id`	Get a product by ID
`POST /product`	Create a product
`PATCH /product/:id`	Update a product
`DELETE /product/:id`	Delete a product
`GET /product/valid-code`	Check whether a product code is already in use

Product Bundles — groups of products that can be added to an invoice as a single unit — are also documented. This feature requires the PRODUCT_BUNDLE subscription add-on. See Products & Product Bundles for full details.

Customers API

The full Customers API is now documented, covering the complete lifecycle of buyer records.

New endpoints:

Endpoint	Description
`GET /customers`	List customers with filtering and sort
`GET /customer/:id`	Get a customer by ID
`POST /customer`	Create a customer
`PATCH /customer/:id`	Update a customer
`DELETE /customer/:id`	Delete a customer
`GET /customers/generate-number`	Auto-generate the next customer number in sequence
`GET /customer/verify-customer-number`	Check whether a customer number is unique
`POST /customers/import`	Bulk-import customers from a previously uploaded CSV file

See Customers for full details.

Webhook Subscription Management

Webhooks can now be registered, updated, and deleted via the API. Previously this required using the faktoora UI.

Endpoint	Description
`GET /webhooks`	List your registered webhook subscriptions
`POST /webhooks`	Register a new webhook
`PATCH /webhooks/{id}`	Update a webhook
`DELETE /webhooks/{id}`	Remove a webhook

Note: When registering a subscription, use "action": "invoiceCreated" (past tense). The event name delivered to your endpoint is invoiceCreate (present tense). See Webhooks for the full event reference.

Invoice API Additions

List endpoint: GET /invoices now supports paginated listing with filtering and sorting. Pass an Accept: application/pdf or Accept: application/xml header to continue using it as a single-invoice download by invoice number — both modes are supported on the same endpoint.

Delete endpoint: DELETE /invoices/{faktooraId} is now documented. Deletion requires the invoiceDeleteMode feature to be enabled on your account.

Status polling: GET /invoices/{faktooraId}/status is now documented. Poll this after POST /invoices to track authority registration and delivery state without relying solely on webhooks.

POST response: The POST /invoices response now includes a detailsPage URL alongside the faktooraId, linking directly to the invoice in the faktoora UI.

Outgoing Invoice Content Access

A full set of content-retrieval endpoints is now documented under /import/outgoing/{faktooraId}. These give structured, machine-readable access to invoices created via POST /invoices — useful for verification, reconciliation, and downstream processing.

New endpoints include:

Structured content by section: seller, buyer, lineitems, taxes, paymentterms, paymentmeans, delivery
Merged content in one call: GET /import/outgoing/{faktooraId}/content
Original source file download: GET /import/outgoing/{faktooraId}/source
Validation reports: JSON summary and PDF
Import processing status with three phases: validationStatus, visualizationStatus, overallStatus
Embedded attachment listing and download

See Outgoing Invoices for the full 18-endpoint table.

Incoming Invoice Content Access

The incoming invoice API reference has been significantly expanded. The canonical endpoint prefix is now /import/incoming/{importId} — the legacy /import/{importId} prefix remains fully supported.

Added 13 content-retrieval endpoints:

Structured content by section: seller, buyer, lineitems, taxes, paymentterms, paymentmeans, delivery
Merged content in one call: GET /import/incoming/{importId}/content
Original source file download: GET /import/incoming/{importId}/source
Embedded attachment listing and download
Paginated invoice list: GET /import/incoming

See Incoming Invoices for the full 19-endpoint table.

December 2025

Webhook Payload Schemas

Full field-level schemas are now published for all 15 webhook event types. Previously only a subset of fields were listed.

invoiceCreate payload — expanded to include 20+ fields: amount, outstandingBalance, currency, invoiceNumber, invoiceTypeCode, status, format, issueDate, dueDate, deliveryDate, orderNumber, shippingOrderNumber, contractNumber, assignmentNumber, orderReferenceId, buyerReferenceId, mandateReference, projectName, totalCosts, createdAt

invoiceIncomingCreate payload — expanded to include: importId, taxAmount, sellerName, type, inputType, isValid, buyerReference, invoiceCurrencyCode

detailsPage field — added to all event payloads that reference a document. This is a fully-qualified URL linking directly to the relevant entity in the faktoora UI. Useful for linking webhook notifications to specific records without constructing URLs manually.

New Webhook Events

Two additional webhook events are now active and documented:

Event	Trigger
`orderConfirmationCreate`	Order confirmation document created
`orderConfirmationSent`	Order confirmation sent via email

July 2025

Additional Webhook Events

The following events were added and are now documented:

Event	Trigger
`invoiceSent`	Outgoing invoice successfully delivered via email
`invoiceIncomingSent`	Incoming invoice forwarded to a recipient via email

June 2025 — Developer Documentation Launch

docs.faktoora.com launched as the dedicated developer portal for the faktoora API.

Initial coverage:

Getting Started — authentication (X-API-KEY header), environment setup, and first-request walkthrough
Outgoing Invoices — invoice creation via POST /invoices with draft, review, and direct modes; ZUGFeRD, XRechnung format selection; download by faktooraId or invoice number
Incoming Invoices — API upload via POST /import, EN 16931 validation, status polling, PDF preview
Webhooks — initial event reference covering invoiceCreate, invoiceOverdue, invoiceIncomingCreate, offers, letters, reminders, customerCreate, productCreate
Glossary — canonical definitions for faktooraId, XRechnung, ZUGFeRD, PEPPOL, EN 16931, invoice status lifecycle
Process diagrams — sequence and flowchart diagrams for outgoing and incoming invoice flows
Interactive API docs — full OpenAPI spec at /api-docs via the Scalar UI

June 2026​

Invoice subject field​

April 2026​

Recurring Invoices API​

March 2026​

Invoice Validation​

Invoice Number API​

Skonto (Early Payment Discount) in Payment Terms​

MCP Server​

Products & Product Bundles API​

Customers API​

Webhook Subscription Management​

Invoice API Additions​

Outgoing Invoice Content Access​

Incoming Invoice Content Access​

December 2025​

Webhook Payload Schemas​

New Webhook Events​

July 2025​

Additional Webhook Events​

June 2025 — Developer Documentation Launch​

June 2026

Invoice subject field

April 2026

Recurring Invoices API

March 2026

Invoice Validation

Invoice Number API

Skonto (Early Payment Discount) in Payment Terms

MCP Server

Products & Product Bundles API

Customers API

Webhook Subscription Management

Invoice API Additions

Outgoing Invoice Content Access

Incoming Invoice Content Access

December 2025

Webhook Payload Schemas

New Webhook Events

July 2025

Additional Webhook Events

June 2025 — Developer Documentation Launch