Skip to content
Billing
/
/
Versioning & Change Manag...
Last updated

Versioning & Change Management

Key idea:
Versioning protects audit integrity. Configuration changes should affect future behavior by default and never silently rewrite history. Charges snapshot configuration versions so you can always explain “why this happened.”

Versioning applies to all major Billing & Ledger configuration entities:

  • Rates
  • Allocation configurations
  • Subscriptions
  • Rate cards (where applicable)

What versioning means (in practice)

When you update a configuration entity, the system creates a new version.

  • The old version remains available for historical reference.
  • Existing charges and settled financial records keep referencing the version they were created with.
  • New charges can use the latest version going forward.

This allows you to change pricing/responsibility without retroactively changing historical outcomes.

Charge snapshots (why changes don’t “rewrite” old charges)

When a charge is created, it records the configuration versions it depends on, such as:

  • debit rate version
  • discount rate versions
  • allocation configuration version
  • subscription version (if charge was created from a subscription)

That’s why this statement is true:

Updating rates/allocations/subscriptions changes future charges, not charges that already exist—unless you explicitly update those charges while they are still mutable.

Mutability boundary (when changes are allowed)

Charges are mutable until they are finalized by billing output generation (for example, invoice generation and/or settlement). After that point:

  • charges are immutable
  • updates are rejected
  • deletes are rejected
  • “voiding” is treated as an update and is also rejected

This is the heart of why billing cycles matter: they define when financial truth becomes locked.

Pattern A — Change future behavior only (most common)

Use this when you want the new pricing/allocation to apply starting next cycle.

  1. Update the configuration (creates a new version)
  2. Leave existing charges untouched
  3. Ensure new charges reference the latest versions going forward

Best for:

  • new pricing plans
  • new discount programs
  • updated subsidy rules
  • updated splits

Pattern B — Migrate existing charges (explicit, pre-finalization)

Use this when charges were created early (or incorrectly) and you need to update them before invoicing/settlement.

Constraints:

  • charges must still be in a mutable status
  • your API call must explicitly request an update to that charge

Example: update a charge to use a different discount rate (illustrative)

curl -X PATCH "https://api.nelnetpay.com/charges/chg_123"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "discountRateIds": ["rate_new_discount"]
  }'

Pattern C — Correct after finalization (no rewrites)

If an error is found after charges are finalized:

  • do not rewrite history
  • instead create corrective activity (for example, a discount/credit charge or downstream correction flow)

This preserves audit integrity and makes reporting consistent.

Versioning and reporting

Versioning enables answers to questions like:

  • “Which pricing plan version produced this charge?”
  • “What allocation rules were in effect?”
  • “When did we change responsibility routing?”

When combined with tags (and nested tag provenance), reporting becomes significantly more powerful.

Tagging interaction (high-level)

Because tags can exist at multiple layers:

  • rate tags
  • allocation tags
  • subscription tags
  • profile entity tags

…and because charges snapshot configuration versions, the system can reliably explain:

  • which tags were applied
  • at what time
  • from which configuration objects
Previous page
Next page