This document explains how the Profile Service models customers, responsibility, and relationships.
The goal is flexibility without ambiguity — allowing many real‑world payment scenarios while keeping rules explicit.
Important: Accounts and Billable Entities are only required when using Billing, Recurring Billing, or Invoicing.
If you are using the Profile Service by itself (or only with the Payment Widget), you may create People and attach payment methods without creating Accounts or Billable Entities.
A Billable Entity represents the person being billed. This who the billed services were rendered to.
Examples include:
- Student
- Staff member
- Child
- Person
Billable entities are intentionally lightweight and may reference external systems via an externalReferenceId. Billable Entities may have one or many Accounts associated with it.
An Account represents financial responsibility — the party that ultimately pays.
Examples:
- A family household
- A corporate department
- A sponsoring organization
An account may be responsible for one or many billable entities.
The Profile Service distinguishes between:
- Person — an individual human
- Organization — a legal or business entity
Both may:
- Associated with one or many accounts
- Act as payers
- Receive invoices and receipts (contacts)
Relationships are defined through explicit roles.
Roles define what an entity is allowed to do — not just who they are.
Examples:
- Person is a Payer on an Account to pay full or partial invoices.
- Organization is an Payer on an Account to pay subsidies.
- Person is a Contact on an Account to receive invoices.
Associations are always explicit and scoped to an account context.
- Parent pays for child enrollment
- Employer pays for employee benefits
- Agency pays on behalf of multiple customers
- Split responsibility across organizations
- Recurring or returning customer payments
- Creating customer records with stored payment methods
- Creating a email subscription for product updates
The model supports all of these without special cases.
| Component | Required When |
|---|---|
| Person / Organization | Always |
| Stored Payment Method | Optional |
| Account | Billing, Invoicing, Auto-Pay |
| Billable Entity | Billing & Subscriptions |
This allows lightweight integrations without forcing billing concepts.
The Profile Service supports custom tags on most entities.
Tags may be used for:
- Client-specific metadata
- Audit and traceability
- Reporting and downstream enrichment
- Cross-service context propagation
Tags are consolidated when referenced by downstream services (such as Billing and Invoicing).
For details on tag structure, consolidation, and propagation, see the Tagging section.
- Billable entities describe who services were rendered to
- Accounts describe who's financially responsible
- People and organizations participate through roles
- Associations make responsibility explicit