Skip to content
/
Tag Consolidation & Propa...
Last updated

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.

Key idea:
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

{
  "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"
      }
    }
  }
}
Key idea:
Each tag namespace reflects the entity that contributed it (for example, billing.rate or 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):

{
  "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
Previous page
Next page