# Allocation Rules & Responsibility div strong Key idea: br Allocation configurations define em who pays . They can split responsibility, transfer coverage to a sponsor/subsidy, and cap responsibility across a billing period. When caps are reached, the leftover becomes a strong contractual write-off (recorded as a discount outcome). 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 | Rule | What it does | | --- | --- | | **RESPONSIBLE_PARTY** | Establishes base responsibility (percent splits) | | **COVERAGE_TRANSFER** | Moves a fixed amount of responsibility from one account to another | | **BILLING_CAP** | Limits responsibility across a period. Residual becomes contractual write-off | ## Visual legend div div strong Billable Entity br span Service recipient div strong Account br span Responsible party div strong Rule br span Computation step ## API basics - Base URL: https://api.nelnetpay.com - Endpoint: POST /allocationConfigurations - Auth: Bearer token ### Minimal allocation configuration shape ```json { "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 div div strong Billable Entity br Emily (be_emily) div → div strong Account br Smith Family (acct_smith) br (100%) ### API example ```bash 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 div div strong Billable Entity br Child (be_child) div strong Rules (in order) ol li strong RESPONSIBLE_PARTY : Family 100% li strong COVERAGE_TRANSFER : $25 per charge → Subsidy li em Optional strong BILLING_CAP : cap subsidy coverage per period div strong Accounts br Family (acct_family) br Subsidy (acct_subsidy) ### API example ```bash 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 div div strong Billable Entity br Alex (be_alex) div → div div strong Account br Jane (acct_jane) br (50%) div strong Account br John (acct_john) br (50%) ### API example ```bash 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 div div strong Alex (be_alex) br span Jane 50% (acct_jane) • John 50% (acct_john) div strong Emily (be_emily) br span Jane 100% (acct_jane) div strong Jack (be_jack) br span John 100% (acct_john) ### 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 div div strong Billable Entity br Alex (be_alex) div strong Rules (in order) ol li strong RESPONSIBLE_PARTY : Jane 50%, John 50% li strong COVERAGE_TRANSFER : from Jane → Subsidy ($25 per charge) li em Optional strong BILLING_CAP : cap subsidy coverage per period div div strong Jane br acct_jane div strong John br acct_john div strong Subsidy br acct_subsidy ### API example ```bash 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. div strong Example: br If you cap an account at code $350 for the billing cycle and there are four code $100 charges, the cap is reached at code $350 and the remaining code $50 is treated as a contractual write-off (recorded as a discount outcome). 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: ```json { "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.