Module

Invoicing

B2B invoice creation, lifecycle management, PDF generation, and dispute handling between accommodation providers and tour operators.

Stable

Overview

Ananas GDS includes a built-in B2B invoicing system for accommodation providers to bill tour operators and other partners. Invoices track line items, tax, due dates, and go through a structured lifecycle from draft to payment. PDF generation and email delivery are supported.

Invoice Model

The Invoice model represents a single billing document issued by an accommodation provider to a partner.

Field	Type	Description
`id`	UUID	Unique identifier. Read-only.
`invoice_number`	string	Auto-generated invoice number. Format: `INV-YYYY-NNNN`.
`owner`	User FK	The user who issued the invoice (accommodation provider).
`partner`	User FK, nullable	The recipient of the invoice — a connected tour operator.
`issue_date`	date	The date the invoice was issued.
`due_date`	date	The payment due date.
`currency`	string	3-character ISO currency code. e.g. `EUR`.
`status`	string	Current lifecycle state. See Status Lifecycle.
`subtotal`	decimal	Sum of all line item totals before tax.
`tax_rate`	decimal	Tax rate as a percentage, e.g. `19.00` for 19%.
`tax_amount`	decimal	Computed tax amount (`subtotal × tax_rate / 100`). Read-only.
`total_amount`	decimal	Computed total (`subtotal + tax_amount`). Read-only.
`notes`	text	Optional free-text notes printed on the invoice.
`template`	FK InvoiceTemplate, nullable	Visual template applied when generating the PDF.
`created_at`	datetime	Record creation timestamp. Read-only.
`updated_at`	datetime	Last modification timestamp. Read-only.

Invoice Line Items

Each invoice has one or more line items describing the services or goods being billed.

Field	Type	Description
`invoice`	FK Invoice	Parent invoice this line item belongs to.
`description`	string	Description of the service or item.
`quantity`	decimal	Number of units.
`unit_price`	decimal	Price per unit.
`line_total`	decimal	Computed total for this line (`quantity × unit_price`). Read-only.

Line items are sent as a nested array in invoice create and update requests. Example request body:

json

{
  "partner": 42,
  "issue_date": "2026-05-01",
  "due_date": "2026-05-31",
  "currency": "EUR",
  "tax_rate": "19.00",
  "notes": "Season 2026 distribution fee",
  "line_items": [
    {
      "description": "Fact sheet distribution — Q2 2026",
      "quantity": "1.00",
      "unit_price": "450.00"
    },
    {
      "description": "Photo library sync",
      "quantity": "3.00",
      "unit_price": "50.00"
    }
  ]
}

Status Lifecycle

Invoices follow a strict state machine. The table below lists each status, its meaning, and the allowed transitions.

Status	Description	Allowed Transitions
`DRAFT`	Invoice created but not yet sent. Fully editable.	SENT, CANCELLED
`SENT`	Sent to the recipient. No further edits permitted.	VIEWED, CANCELLED
`VIEWED`	Recipient has opened the invoice.	DISPUTED, CLEARED, CANCELLED
`DISPUTED`	Recipient has raised a dispute on the invoice.	CLEARED, CANCELLED
`CLEARED`	Dispute resolved. Awaiting payment.	PAID, CANCELLED
`PAID`	Invoice marked as paid. Terminal state.	—
`CANCELLED`	Invoice cancelled. Terminal state.	—
`OVERDUE`	System-set automatically when `due_date` passes and status is SENT, VIEWED, or DISPUTED.	PAID, CANCELLED

⚠

Sent invoices are locked

Once an invoice is SENT, its line items and financial data cannot be edited. Create a new invoice or cancel and reissue.

API Endpoints

Invoice CRUD

GET /api/invoicing/invoices/ 🔐 Auth required

List all invoices for the authenticated user. Supports ?status= filter.

POST /api/invoicing/invoices/ 🔐 Auth required

Create a new invoice. The invoice is created with status DRAFT. Include line items as a nested array in the request body.

GET /api/invoicing/invoices/{id}/ 🔐 Auth required

Retrieve invoice details including line items and the full activity log.

PUT /api/invoicing/invoices/{id}/ 🔐 Auth required

Update an invoice. Only permitted when status is DRAFT.

DELETE /api/invoicing/invoices/{id}/ 🔐 Auth required

Delete an invoice. Only permitted when status is DRAFT.

Invoice Actions

POST /api/invoicing/invoices/{id}/send/ 🔐 Auth required

Transition the invoice from DRAFT to SENT. Sends a notification email to the partner.

POST /api/invoicing/invoices/{id}/dispute/ 🔐 Auth required

Recipient marks the invoice as DISPUTED. Allowed from VIEWED or SENT.

POST /api/invoicing/invoices/{id}/mark-paid/ 🔐 Auth required

Owner marks the invoice as PAID.

POST /api/invoicing/invoices/{id}/cancel/ 🔐 Auth required

Cancel the invoice. Allowed from any non-terminal state.

PDF & Delivery

GET /api/invoicing/invoices/{id}/pdf/ 🔐 Auth required

Download the invoice as a PDF. The PDF is rendered using the invoice's assigned template, or the default template if none is set.

POST /api/invoicing/invoices/{id}/send-reminder/ 🔐 Auth required

Send a payment reminder email to the partner. See Reminders for details.

Templates

GET /api/invoicing/templates/ 🔐 Auth required

List all invoice templates for the authenticated user.

POST /api/invoicing/templates/ 🔐 Auth required

Create a new invoice template.

GET /api/invoicing/templates/{id}/ 🔐 Auth required

Retrieve a specific template.

PUT /api/invoicing/templates/{id}/ 🔐 Auth required

Update a template.

DELETE /api/invoicing/templates/{id}/ 🔐 Auth required

Delete a template.

Invoice Templates

Templates customise the visual appearance and default content of generated PDFs. A template can be assigned to any invoice; if none is assigned, the platform default is used.

Field	Description
`name`	Human-readable template name.
`header_text`	Text printed at the top of the invoice, above line items.
`footer_text`	Text printed at the bottom of the invoice — payment terms, bank details, legal notices.
`payment_terms`	Short payment terms statement, e.g. Payment due within 30 days.
`bank_details`	Bank account information for wire transfer payments.
`primary_color`	Hex color code used for PDF accents and headings, e.g. `#c9a84c`.

Activity Log

Every state change and action on an invoice is recorded in the InvoiceActivity log. The log is immutable — entries cannot be edited or deleted.

Field	Description
`user`	The user who performed the action.
`action`	Action code: `created`, `sent`, `viewed`, `disputed`, `cleared`, `paid`, `cancelled`, `reminder_sent`.
`detail`	Optional text note attached to the action.
`timestamp`	When the action occurred.

The full activity log is returned as a nested array in the invoice detail response (GET /api/invoicing/invoices/{id}/), ordered oldest to newest.

Reminders

Payment reminders can be sent for invoices with status SENT, VIEWED, or OVERDUE. Each reminder dispatched is recorded in an InvoiceReminder record.

Field	Description
`sent_at`	Timestamp when the reminder was dispatched.
`reminder_type`	Reminder sequence: `first`, `second`, or `final`.
`recipient_email`	Email address the reminder was sent to.

✓

Suggested reminder cadence

Set up a regular cadence: first reminder 3 days after due date, second at 7 days, final at 14 days.

← Tour Operators Payments & Subscriptions →