# Tag Consolidation & Propagation

Tag consolidation is a core platform behavior in Nelnet Payment Services (NPS).
It describes **how tags from multiple entities are combined, structured, and propagated** as data flows across services.

## What Is Tag Consolidation?

Tag consolidation is the process of **collecting tags from all related upstream entities** and emitting them downstream as a **single, structured representation**.

div
strong
Key idea:
br

  Consolidation preserves context by nesting tags by their source — never flattening them.

Downstream systems should not need to re-fetch upstream entities to understand why something occurred.

## Where Consolidation Occurs

The primary consolidation point today is **Billing & Ledger**, specifically during **charge creation**.

When Billing creates a charge, it consumes tags from **all entities involved in producing that charge**, including:

- Billable Entity (service recipient)
- Account (financial responsibility)
- Rate configuration
- Allocation configuration
- Subscription configuration (if applicable)
- System-generated billing context


## Consolidated Tag Structure

Consolidated tags are stored and emitted using a **nested namespace model**.

### Example: Consolidated tags 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

  Each tag namespace reflects the entity that contributed it (for example, 
code
billing.rate
 or 
code
billing.billableEntity
).

This nesting model applies consistently to **all derived or consolidated tags** produced by the platform.

## Propagation to Downstream Services

Once consolidated, tags are automatically propagated to downstream artifacts, including:

- Charges
- Journal entries and journal lines
- Invoices
- Receipts
- Settlement and remittance records
- Webhook event payloads
- Reporting datasets


The structure and namespaces are preserved throughout propagation.

## Emission in Webhooks

When an event is emitted via the Push Notification Service, consolidated tags are included in the payload.

Example (simplified):


```json
{
  "eventType": "ChargeCreated",
  "payload": {
    "chargeId": "chg_123",
    "amount": "250.00",
    "currency": "USD",
    "tags": {
      "billing": {
        "rate": {
          "ratePlan": "standard"
        },
      },
      "profile": {
        "billableEntity": {
          "program": "biology"
        }
      }
    }
  }
}
```

This allows webhook consumers to react using **business context**, without additional API calls.

## Reporting & Analytics

Reporting services consume the same consolidated tag structures.

Tags may be used for:

- Filtering
- Grouping
- Segmentation
- Audit analysis


Because tags remain nested, reports can distinguish **where context originated**, not just its value.

## Conflict Handling (High-Level)

When multiple sources provide the same logical tag key:

- Tags are kept in separate namespaces
- No silent overwrites occur
- Deterministic precedence rules are applied within a namespace where applicable


Exact precedence rules are service-specific and documented where relevant.

## Forward Compatibility

As tagging expands into additional services (Payments, Configuration, Reporting APIs):

- The consolidation model remains consistent
- New namespaces may be introduced
- Existing tag structures remain backward compatible


## Summary

- Tag consolidation occurs automatically
- Charges consume tags from all related entities
- Consolidated tags are nested by source
- Structure is preserved through propagation
- Downstream systems can rely on tags for context without re-fetching data