# Taggable Entities & Services

This document describes **where tags can be applied today**, how tags are **consolidated across services**, and how tagging support will expand over time.

## Current Tag Support

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


div
strong
Legend
ul
li
strong
✅
 — tags may be written directly on the entity
li
strong
Derived
 — tags are inherited and consolidated from upstream entities
li
strong
✅ 
&
 Derived
 — the entity supports its own tags and also receives consolidated tags
## Profile Service

In the Profile Service, tags capture **business context, identifiers, and operational metadata** on customer-facing entities.

### Example: Account with nested tags


```json
{
  "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"
    }
  }
}
```

div
strong
Key idea:
br

  Nested tags provide a natural namespace for audit, reporting, and system-generated metadata.

## Billing & Ledger — Tag Consumption

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)


### Consolidated charge tags

Tags are stored and emitted in a **nested structure** to preserve origin and meaning.

Example consolidated tag structure on a Charge:


```json
{
  "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"
      }
    }
  }
}
```

div
strong
Key idea:
br

  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.

## Downstream Consumption

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

## Forward Compatibility

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.

## Summary

- 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