Allocation Rules & Responsibility

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Allocation configurations answer: “How is a charge distributed across responsible parties?”

They are referenced by:

• Subscriptions (ongoing intent)
• Charges (direct billing)

Concepts: accounts vs billable entities

• Billable Entity: who services were rendered to (e.g., a participant / dependent / member)
• Account: who is financially responsible (e.g., household, sponsor, agency)

Allocations operate on accounts. The billable entity provides the context that ties services to responsibility, but the allocation rules distribute dollars to accounts.

Rule evaluation (order matters)

Rules are applied top-to-bottom. Small changes in order can change outcomes.

A common pattern:

1. Establish base responsibility (RESPONSIBLE_PARTY)
2. Transfer coverage (COVERAGE_TRANSFER)
3. Apply caps (BILLING_CAP)

Rule types used in this guide

Visual legend

API basics

• Base URL: https://api.nelnetpay.com
• Endpoint: POST /allocationConfigurations
• Auth: Bearer token

Minimal allocation configuration shape

{
  "name": "Allocation Name",
  "rules": [
    { "ruleType": "RESPONSIBLE_PARTY", "accountId": "acct_a", "percent": 100 }
  ],
  "tags": {
    "billing": { "allocationScenario": "EXAMPLE" }
  }
}

Example 1 — Single Family

Scenario

• Account: One entity (e.g., “Smith Family”)
• BillableEntity: One per child (services rendered to the child)
• Allocation: 100% responsible party

Visual

API example

curl -X POST "https://api.nelnetpay.com/allocationConfigurations"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Single Family - 100%",
    "rules": [
      { "ruleType": "RESPONSIBLE_PARTY", "accountId": "acct_smith", "percent": 100 }
    ],
    "tags": {
      "billing": { "allocationScenario": "SINGLE_FAMILY" }
    }
  }'

Example 2 — Family + Subsidy

Scenario

• Accounts: Family + Subsidy agency
• Allocation:
  1. Family responsible for base (100%)
  2. Subsidy covers a fixed dollar amount per charge (coverage transfer)
  3. Optional: cap subsidy coverage by period

Visual

API example

curl -X POST "https://api.nelnetpay.com/allocationConfigurations"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Family + Subsidy",
    "rules": [
      { "ruleType": "RESPONSIBLE_PARTY", "accountId": "acct_family", "percent": 100 },
      {
        "ruleType": "COVERAGE_TRANSFER",
        "fromAccountId": "acct_family",
        "toAccountId": "acct_subsidy",
        "amountPerCharge": 2500
      },
      {
        "ruleType": "BILLING_CAP",
        "accountId": "acct_subsidy",
        "capAmount": 50000,
        "capPeriod": "MONTHLY"
      }
    ],
    "tags": {
      "billing": { "allocationScenario": "FAMILY_SUBSIDY" }
    }
  }'

Example 3 — Split Family (one child)

Scenario

• Accounts: Jane + John
• BillableEntity: Alex
• Allocation: 50/50 split

Visual

API example

curl -X POST "https://api.nelnetpay.com/allocationConfigurations"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Split 50/50 - One Child",
    "rules": [
      { "ruleType": "RESPONSIBLE_PARTY", "accountId": "acct_jane", "percent": 50 },
      { "ruleType": "RESPONSIBLE_PARTY", "accountId": "acct_john", "percent": 50 }
    ],
    "tags": {
      "billing": { "allocationScenario": "SPLIT_ONE_CHILD" }
    }
  }'

Example 4 — Split Family (three children)

Scenario

• Alex – 50/50 Jane/John
• Emily – 100% Jane
• Jack – 100% John

Visual

How to implement this in Billing & Ledger

You typically create multiple allocation configurations:

• Allocation A: 50/50 split (for Alex)
• Allocation B: 100% Jane (for Emily)
• Allocation C: 100% John (for Jack)

Then reference the correct allocation configuration from each child’s subscription or charge.

Example 5 — Split Family + Subsidy (three children, subsidy on one share)

Scenario (Alex)

• RESPONSIBLE_PARTY: Jane 50%, John 50%
• COVERAGE_TRANSFER: subsidy covers fixed amount from Jane’s share (e.g., $25/day)
• Optional cap: subsidy coverage capped monthly

Visual

API example

curl -X POST "https://api.nelnetpay.com/allocationConfigurations"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Split 50/50 + Subsidy on Jane",
    "rules": [
      { "ruleType": "RESPONSIBLE_PARTY", "accountId": "acct_jane", "percent": 50 },
      { "ruleType": "RESPONSIBLE_PARTY", "accountId": "acct_john", "percent": 50 },
      {
        "ruleType": "COVERAGE_TRANSFER",
        "fromAccountId": "acct_jane",
        "toAccountId": "acct_subsidy",
        "amountPerCharge": 2500
      },
      {
        "ruleType": "BILLING_CAP",
        "accountId": "acct_subsidy",
        "capAmount": 50000,
        "capPeriod": "MONTHLY"
      }
    ],
    "tags": {
      "billing": { "allocationScenario": "SPLIT_SUBSIDY" }
    }
  }'

Residuals and contractual write-offs (the nuance)

You do not create a WRITE_OFF rule type.

Instead, write-offs are an outcome when caps constrain responsibility.

Why this matters:

• caps are applied across a billing period (cycle-aware)
• the “leftover” is deterministic and auditable
• reporting can treat the residual as contractual revenue reduction

Tagging

Allocation configurations should include tags so downstream records can explain why responsibility was routed:

{
  "tags": {
    "billing": {
      "allocationScenario": "FAMILY_SUBSIDY",
      "source": "admin-ui"
    }
  }
}

Versioning notes

Allocation configurations are versioned:

• updating creates a new version
• existing charges keep the snapshot they were created with
• applying new allocation behavior to existing charges requires an explicit charge update (and the charge must still be mutable)

See Versioning & Change Management for practical change patterns.