Invoices

Invoices are the primary billing documents issued to customers in the system. Each invoice represents a finalized billing record that contains customer information, line items with detailed charges, tax calculations, and accounting references. Invoices are immutable once issued, ensuring data integrity and providing an accurate historical record of all billing transactions.

Invoice Properties

Property	Type	Description
id	GUID	Unique identifier
invoiceNumber	string	Human-readable number
invoiceDate	datetime	Creation date
dueDate	datetime	Payment due date
status	enum	Current status
customerId	GUID	Customer reference
customerName	string	Customer name (snapshot)
customerEmail	string	Email (snapshot)
billingAddress	string	Address (snapshot)
studyId	GUID	Study reference
contractId	GUID	Contract reference
netAmount	decimal	Total before tax
taxAmount	decimal	Total tax
discountAmount	decimal	Total discounts
grossAmount	decimal	Final amount
receivableAccountId	GUID	Receivable account
notes	string	Optional notes
externalReference	string	External system reference
createdAt	datetime	Creation timestamp
createdById	GUID	User who created (null if system)
updatedAt	datetime	Last update timestamp
updatedById	GUID	User who last updated

Invoice Status Values

The invoice status indicates the current state of the invoice in its lifecycle. Draft status means the invoice is being prepared and can still be modified. Issued status indicates the invoice has been finalized and sent to the customer. Canceled status is used when an invoice is voided and should not be paid. Credited status means a reversal invoice has been created to cancel out the original charges.

Status	Value	Description
Draft	1	Being prepared
Issued	2	Finalized and sent
Canceled	3	Voided
Credited	4	Reversed

Line Item Properties

Each invoice contains one or more line items representing individual charges. Line items include the article being charged, quantity, pricing, tax calculations, and accounting references for proper financial posting.

Property	Type	Description
id	GUID	Unique identifier
lineNumber	int	Display order
articleId	GUID	Article reference
articleCode	string	Article code (snapshot)
description	string	Item description
quantity	decimal	Quantity
unitPrice	decimal	Price per unit
netAmount	decimal	Quantity × Unit Price
taxAmount	decimal	Calculated tax
grossAmount	decimal	Net + Tax
taxCodeId	GUID	Tax code reference
taxRate	decimal	Tax rate applied
revenueAccountId	GUID	Revenue account
costCenterId	GUID	Cost center

API Endpoints

GET /invoices
GET /invoices/{id}

Response Example

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoiceNumber": "INV-2024-00123",
  "invoiceDate": "2024-09-01T00:00:00Z",
  "dueDate": "2024-09-30T00:00:00Z",
  "status": 2,
  "customerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "customerName": "John Doe",
  "customerEmail": "[email protected]",
  "billingAddress": "123 Main St, City, 12345",
  "studyId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "contractId": "d4e5f6a7-b8c9-0123-def1-234567890123",
  "netAmount": 5000.00,
  "taxAmount": 950.00,
  "discountAmount": 0.00,
  "grossAmount": 5950.00,
  "receivableAccountId": "e5f6a7b8-c9d0-1234-ef12-345678901234",
  "notes": null,
  "externalReference": null,
  "createdAt": "2024-09-01T10:30:00Z",
  "createdById": null,
  "updatedAt": null,
  "updatedById": null,
  "lineItems": [
    {
      "id": "f6a7b8c9-d0e1-2345-f123-456789012345",
      "lineNumber": 1,
      "articleId": "a7b8c9d0-e1f2-3456-1234-567890123456",
      "articleCode": "TUI-001",
      "description": "Tuition Fee - Winter Semester 2024",
      "quantity": 1,
      "unitPrice": 5000.00,
      "netAmount": 5000.00,
      "taxAmount": 950.00,
      "grossAmount": 5950.00,
      "taxCodeId": "b8c9d0e1-f2a3-4567-2345-678901234567",
      "taxRate": 19.00,
      "revenueAccountId": "c9d0e1f2-a3b4-5678-3456-789012345678",
      "costCenterId": "d0e1f2a3-b4c5-6789-4567-890123456789"
    }
  ]
}

Amount Calculations

The invoice system calculates amounts at both the line item and invoice levels using consistent formulas. For each line item, the net amount is calculated by multiplying quantity by unit price. Tax amount is then calculated by applying the tax rate to the net amount using the formula: netAmount × (taxRate / 100). The gross amount for the line item is the sum of net amount and tax amount. At the invoice level, the total net amount is the sum of all line item net amounts, total tax amount is the sum of all line item tax amounts, and the final gross amount is calculated as: netAmount + taxAmount - discountAmount.

Data Snapshots

Invoice data includes snapshots of customer information to ensure historical accuracy. When an invoice is created, the customer's name, email, and billing address are copied to the invoice record. This means that even if the customer's information changes later in the system, the invoice retains the information that was current at the time of billing. The same principle applies to article codes and tax rates, which are stored as snapshots on line items to maintain accurate historical records.