# Profiles, Accounts & Relationships

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.


## 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.

## Accounts

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.

## People and Organizations

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)


## Roles and Associations

Relationships are defined through explicit roles.

div
strong
Key idea:
br

  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.

## Common Real‑World Patterns

#### Profiles + Billing & Invoicing

- Parent pays for child enrollment
- Employer pays for employee benefits
- Agency pays on behalf of multiple customers
- Split responsibility across organizations


#### Profiles Standalone

- 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.

## Optional Components

| 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.

## Tags

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.

## Summary

- Billable entities describe who services were rendered to
- Accounts describe who's financially responsible
- People and organizations participate through roles
- Associations make responsibility explicit