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.
Payment Sources
Payment sources define the methods and accounts through which payments are received from customers. Each payment source represents a specific payment channel (e.g., bank transfer, credit card, cash) and is linked to a financial account for proper accounting integration. Payment sources are essential for tracking where payments come from and ensuring they are posted to the correct accounts.
Payments and Payment Allocations
Payments represent money received from customers to settle their invoices. The payment system tracks incoming funds, allocates them to specific invoices, and integrates with the accounting system through journal entries. Payment allocations link payments to invoices, allowing partial payments, overpayments, and proper tracking of customer account balances.
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.
When payments are received from customers, they are recorded using a payment source (e.g., bank account, credit card processor). Payments are then allocated to specific invoices through payment allocations, which track how much of each payment applies to each invoice. This allows for partial payments, overpayments, and proper reconciliation of customer accounts.
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 |
| Payment Sources | GET /payment-sources/{id} | Payment channels and accounts |
| Payments | GET /payments/{id} | Customer payments and allocations |
| 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.
For payment processing, review Payment Sources to understand how payment channels are configured, then see Payments to learn how customer payments are recorded, allocated to invoices, and posted to the general ledger.