Billing Service API
Welcome to the Billing Service API documentation. This API provides read-only access to billing data for integration with external systems such as campus management systems, enterprise resource planning (ERP) software, and accounting systems. The API enables you to retrieve comprehensive billing information including invoices, customer data, articles with pricing, and supporting reference data needed for financial integration and reporting purposes.
API Overview
The Billing Service API is organized around REST principles and returns JSON-encoded responses. All endpoints support standard HTTP methods for retrieving data, and the API uses conventional HTTP response codes to indicate success or errors. The base URL for all API requests follows the pattern https://api.yourdomain.com/billing and requires authentication via API keys or OAuth tokens depending on your integration setup.
Core Entities
The billing system is built around several core entities that work together to manage the complete billing lifecycle. Understanding these entities and their relationships is essential for effective API integration.
Customers
Customers represent students or entities that receive invoices. Each customer record contains personal information, contact details, and critical accounting identifiers such as debtor numbers that are used for financial system integration. Customers are linked to studies (academic programs) and have associated addresses for billing and correspondence purposes.
Invoices
Invoices are the primary billing documents issued to customers. Each invoice contains a header with customer information, dates, amounts, and a collection of line items representing individual charges. Invoices progress through various statuses from draft to issued, and each invoice is immutably linked to a customer and optionally to a contract and study program.
Articles
Articles represent the products or services that can be billed to customers. Examples include tuition fees, registration fees, exam fees, and other chargeable services. Articles have time-based pricing that allows prices to change over time while maintaining historical accuracy. Each article is configured with default tax codes, cost centers, and revenue accounts for proper financial posting.
Studies and Academic Terms
Studies represent academic programs that customers are enrolled in. Each study is linked to an exam regulation and contains semester status information. Academic terms define the semester periods and are used to organize billing activities according to the academic calendar. The system uses these entities to determine when semester-based fees should be charged and to link invoices to specific academic periods.
Data Flow
The billing workflow begins when a customer enrolls in a study program. A contract is created that defines the billing rules and fee structure for that customer's program. Based on the contract configuration, the system generates planned invoices according to the billing schedule. When a planned invoice becomes due, it is converted into an actual invoice with line items. Each line item references an article, applies the appropriate tax code, and assigns cost centers for financial tracking.
Quick Reference
| Entity | Endpoint | Description |
|---|---|---|
| Invoices | GET /invoices/{id} | Retrieve invoice with line items |
| Customers | GET /customers/{id} | Get customer with debtor number |
| Articles | GET /articles/{id} | View article details and pricing |
| Tax Codes | GET /tax-codes/{id} | Tax rates and accounts |
| Cost Centers | GET /cost-centers/{id} | Cost allocation units |
| Accounts | GET /accounts/{id} | Financial accounts |
| Academic Terms | GET /academic-terms/{id} | Semester periods |
Next Steps
Begin with the Invoices page to understand the structure of billing documents and how to retrieve invoice data. Then explore Customers to learn about customer information and debtor numbers. The Articles page explains how pricing works and how articles are configured with tax and cost center defaults.