This document describes where tags can be applied today, how tags are consolidated across services, and how tagging support will expand over time.
| Service | Entity | Tag Support |
|---|---|---|
| Profile Service | Billable Entity | ✅ |
| Profile Service | Account | ✅ |
| Profile Service | Person | ✅ |
| Profile Service | Organization | ✅ |
| Profile Service | Payment Method | ❌ |
| Billing & Ledger | Rate Configuration | ✅ |
| Billing & Ledger | Allocation Configuration | ✅ |
| Billing & Ledger | Subscription Configuration | ✅ |
| Billing & Ledger | Charge | ✅ & Derived |
| Billing & Ledger | Journal Entries & Lines | Derived |
| Invoices | Invoice | Derived |
| Settlement & Reconciliation | Settlement & Remittance Record | Derived |
- ✅ — tags may be written directly on the entity
- Derived — tags are inherited and consolidated from upstream entities
- ✅ & Derived — the entity supports its own tags and also receives consolidated tags
In the Profile Service, tags capture business context, identifiers, and operational metadata on customer-facing entities.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Doe Household",
"externalReferenceId": "acct_household_123",
"tags": {
"sourceSystem": "partner-crm",
"customerTier": "gold",
"audit": {
"createdBy": "onboarding-job",
"correlationId": "3e3f7e52-7f1c-4b52-8b0d-6f3fd7dcb42b"
},
"reporting": {
"region": "midwest",
"division": "k12"
}
}
}Nested tags provide a natural namespace for audit, reporting, and system-generated metadata.
Billing & Ledger is where multiple tag sources are intentionally combined.
When a charge is created, Billing consumes tags from all entities involved in producing that charge, including:
- Billable Entity
- Account
- Rate configuration
- Allocation configuration
- Subscription configuration (if applicable)
Tags are stored and emitted in a nested structure to preserve origin and meaning.
Example consolidated tag structure on a Charge:
{
"profile": {
"billableEntity": {
"source": "sis",
"term": "spring-2026"
}
},
"billing":{
"rate": {
"ratePlan": "standard",
"pricingModel": "flat"
},
"allocation": {
"fund": "general",
"percentage": "100"
},
"subscription": {
"cycle": "monthly"
},
"charge": {
"requestId": "abc-123"
}
}
}
}Consolidated tags are always nested by source. Tags are never flattened in a way that loses context.
This nesting model applies consistently to all derived tags produced by Billing & Ledger.
Nested consolidated tags are:
- Persisted on the Charge
- Propagated to Journal Entries
- Emitted on Invoices and Receipts
- Included in Settlement & Remittance records
- Delivered in webhook payloads
- Exposed in reporting
Downstream systems can rely on tag structure to understand both the value and its origin.
Tagging support will expand to additional services, including:
- Payments (first-class payment tags)
- Configuration & Rules (non-billing configuration)
- Reporting APIs (filtering, grouping, segmentation)
The nested consolidation model will remain consistent as tagging expands.
- Multiple entities contribute tags to a charge
- Tags are consolidated automatically by Billing
- Consolidated tags are nested by source
- Nested structure is preserved across all downstream services