Customers

Customers represent students or entities that receive invoices in the system. Each customer record contains personal identification, contact information, and critical accounting identifiers used for financial system integration. Customers are linked to studies (academic programs) and have associated addresses for billing and correspondence purposes.

Customer Properties

Property	Type	Description
id	GUID	Unique identifier
firstName	string	First name
lastName	string	Last name
matriculationId	string	Matriculation number
cmsStudentId	string	External system ID
email	string	Email address
debtorNumber	string	Debtor number
creditorNumber	string	Creditor number
receivableAccountId	GUID	Receivable account
prepaymentAccountId	GUID	Prepayment account

Address Properties

Customers can have multiple addresses with different purposes. Each address has a type that indicates its use, such as billing, home, or correspondence. The system allows marking one address as the default for each customer.

Property	Type	Description
id	GUID	Unique identifier
customerId	GUID	Customer reference
addressType	string	Address type
street	string	Street address
city	string	City
postalCode	string	Postal code
country	string	Country
isDefault	boolean	Default address flag

API Endpoints

GET /customers
GET /customers/{id}

Response Example

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "firstName": "John",
  "lastName": "Doe",
  "matriculationId": "MAT-2024-001",
  "cmsStudentId": "CMS-123456",
  "email": "[email protected]",
  "debtorNumber": "DEB-12345",
  "creditorNumber": null,
  "receivableAccountId": "e5f6a7b8-c9d0-1234-ef12-345678901234",
  "prepaymentAccountId": "f6a7b8c9-d0e1-2345-f123-456789012345",
  "addresses": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "customerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "addressType": "Billing",
      "street": "123 Main Street",
      "city": "Springfield",
      "postalCode": "12345",
      "country": "USA",
      "isDefault": true
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
      "customerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "addressType": "Home",
      "street": "456 Oak Avenue",
      "city": "Springfield",
      "postalCode": "12346",
      "country": "USA",
      "isDefault": false
    }
  ]
}

Debtor Numbers

The debtor number is a critical field for accounting system integration and financial reconciliation. This identifier is used by external financial systems to track customer accounts receivable and match payments to outstanding invoices. Debtor numbers are typically synchronized from the campus management system and must be unique across all customers. When integrating with ERP systems or generating financial reports, the debtor number serves as the primary key for linking billing data to the broader financial system.

Address Types

The address type field categorizes addresses according to their intended use. Billing addresses are used for invoice delivery and payment correspondence. Home addresses represent the customer's primary residence. Correspondence addresses are used for general communications that are not specifically related to billing. The system allows customers to have multiple addresses of different types, providing flexibility for various communication and billing scenarios while maintaining organized contact information.

Customer Snapshots in Invoices

When an invoice is created, the system captures a snapshot of the customer's current information and stores it directly on the invoice record. This includes the customer's full name, email address, and billing address at the time of invoice creation. This snapshot approach ensures that invoices maintain accurate historical records even if the customer's information changes later. For example, if a customer moves to a new address after an invoice is issued, the invoice will still show the address that was current when the invoice was created, providing an accurate record for both the customer and the institution.