Skip to content
API & References
/
Billing & Ledger
/
/
List Settled Charges

Billing & Ledger Service API (1.0.0)

The Billing & Ledger Service is the financial engine of the NPS Billing Platform. It manages pricing (Rates, Rate Cards), subscription configurations, allocation rules for split billing scenarios (divorced households, subsidies), charge lifecycle, and double-entry accounting ledger.

Key Concepts

Charge Lifecycle

Charges follow a strict lifecycle with immutability after invoicing:

  • PENDING → Created but not validated
  • BILLED → Validated and ready to invoice (still editable)
  • INVOICED → Invoiced (IMMUTABLE - moved to SettledCharge)
  • PAID → Paid directly without invoice
  • VOID → Cancelled

Allocation Configuration

Defines how charges are split between multiple accounts (e.g., divorced parents, subsidy agencies). Three rule types:

  • RESPONSIBLE_PARTY: Percentage-based split
  • COVERAGE_TRANSFER: Fixed amount covered (e.g., $25 subsidy per charge)
  • BILLING_CAP: Maximum amount per period

Double-Entry Ledger

All financial transactions follow the accounting equation (Debits = Credits). Journal entries are immutable once created - corrections use adjustment entries.

Monetary Values

All monetary amounts are stored as DECIMAL type in cents (e.g., 5000 = $50.00). Use DECIMAL or NUMERIC type (BigDecimal in Java) for precision and to avoid rounding errors. Never use integers or floating-point for money.

Download OpenAPI description
billing-ledger-service.json
billing-ledger-service.yaml
Languages
Servers
Mock server
https://docs.nelnetpay.com/_mock/apis/billing-ledger-service
UAT server
https://api.uat.nelnetpay.com/billing
Production server
https://api.nelnetpay.com/billing

Rates

Manage rate catalog (pricing for services)

Operations

RateCards

Manage rate card groupings for UI organization

Operations

Subscriptions

Manage billable entity subscriptions to rates

Operations

AllocationConfigurations

Manage charge allocation configurations for split billing

Operations

Charges

Manage billable charges (mutable pre-invoice state)

Operations

SettledCharges

Query settled charges (immutable post-invoice state)

Operations

List Settled Charges

Request

List settled charges (immutable post-invoice/payment state).

Settled charges are created when:

  • A charge is invoiced (settlementType: INVOICED)
  • A charge is paid directly without invoice (settlementType: DIRECT_PAYMENT)

Note: Settled charges are IMMUTABLE. Corrections must be made via ledger adjustments.

Security
OAuth2
Query
statusstring

Filter by settled charge status

Enum"INVOICED""PARTIALLY_PAID""PAID""REFUNDED""VOID"
settlement_typestring

Filter by settlement type

Enum"INVOICED""DIRECT_PAYMENT"
billable_entity_idstring(uuid)

Filter by billable entity ID

account_idstring(uuid)

Filter by account ID

invoice_idstring(uuid)

Filter by invoice ID

settled_at_fromstring(date-time)

Filter settled charges settled on or after this timestamp

settled_at_tostring(date-time)

Filter settled charges settled on or before this timestamp

pageinteger>= 1

Page number (1-indexed)

Default 1
Example: page=1
page_sizeinteger[ 1 .. 200 ]

Number of items per page

Default 50
Example: page_size=50
curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/settledCharges?status=INVOICED&settlement_type=INVOICED&billable_entity_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&account_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&invoice_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&settled_at_from=2019-08-24T14%3A15%3A22Z&settled_at_to=2019-08-24T14%3A15%3A22Z&page=1&page_size=50' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
resultsArray of objectsrequired
results[].​idstring(uuid)required
results[].​originalChargeIdstring(uuid)required
results[].​entityIdstring(uuid)required
results[].​billableEntityIdstring(uuid)required
results[].​accountIdstring(uuid)required
results[].​invoiceIdstring or null(uuid)
results[].​rateIdstring(uuid)

Rate used for this charge

results[].​quantitynumber(double)

Quantity billed

results[].​amountinteger

Full charge amount before proration (cents)

results[].​prorationFactornumber(double)

Proration factor (0.0-1.0)

results[].​proratedAmountinteger

Amount after proration (cents)

results[].​netAmountinteger

Final amount after discounts (cents)

results[].​discountRateIdsArray of strings(uuid)

Discount rates applied

results[].​discountAmountsArray of integers

Discount amounts in cents (parallel to discountRateIds)

results[].​allocationConfigIdstring or null(uuid)

Allocation configuration used

results[].​rateVersioninteger

Version of rate at settlement time

results[].​subscriptionVersioninteger or null

Version of subscription at settlement time

results[].​allocationVersioninteger or null

Version of allocation config at settlement time

results[].​discountRateVersionsArray of integers

Versions of discount rates at settlement time

results[].​settlementTypestringrequired

How the charge was settled

Enum"INVOICED""DIRECT_PAYMENT"
results[].​statusstringrequired

Status of settled (immutable) charge

Enum"INVOICED""PARTIALLY_PAID""PAID""REFUNDED""VOID"
results[].​originalAmountintegerrequired

Original charge amount in cents

results[].​resolvedAmountintegerrequired

Amount after allocation resolution in cents

results[].​amountPaidintegerrequired

Amount paid so far in cents

results[].​amountOutstandingintegerrequired

Remaining amount in cents

results[].​resolvedAllocationobject

Frozen snapshot of allocation at settlement time

results[].​resolvedRateobject

Frozen snapshot of rate at settlement time

results[].​consolidatedTagsobject

Tags consolidated from all sources with prefixes:

  • profile.billableEntity.*
  • profile.account.*
  • billing.rate.*
  • billing.subscription.*
  • billing.charge.*
results[].​settledAtstring(date-time)required
results[].​optimisticLockVersioninteger(int64)read-only

Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

results[].​createdAtstring(date-time)required
paginationobjectrequired
pagination.​totalRecordsintegerrequired

Total number of records across all pages

Example: 100
pagination.​currentPageintegerrequired

Current page number (1-indexed)

Example: 1
pagination.​totalPagesintegerrequired

Total number of pages

Example: 10
pagination.​nextPageinteger or null

Next page number, null if on last page

Example: 2
pagination.​prevPageinteger or null

Previous page number, null if on first page

Example: null
Response
application/json
{
  "results": [
    { … }
  ],
  "pagination": {
    "totalRecords": 100,
    "currentPage": 1,
    "totalPages": 10,
    "nextPage": 2,
    "prevPage": null
  }
}

Get Settled Charge Details

Request

Retrieve details of a specific settled charge.

Includes frozen snapshots of:

  • resolvedRate - Rate details at time of settlement
  • resolvedAllocation - Allocation details at time of settlement
  • consolidatedTags - Tags from all sources (profile, rate, subscription, charge)
Security
OAuth2
Path
settledChargeIdstring(uuid)required

Unique identifier for the settled charge

curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/settledCharges/{settledChargeId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
idstring(uuid)required
originalChargeIdstring(uuid)required
entityIdstring(uuid)required
billableEntityIdstring(uuid)required
accountIdstring(uuid)required
invoiceIdstring or null(uuid)
rateIdstring(uuid)

Rate used for this charge

quantitynumber(double)

Quantity billed

amountinteger

Full charge amount before proration (cents)

prorationFactornumber(double)

Proration factor (0.0-1.0)

proratedAmountinteger

Amount after proration (cents)

netAmountinteger

Final amount after discounts (cents)

discountRateIdsArray of strings(uuid)

Discount rates applied

discountAmountsArray of integers

Discount amounts in cents (parallel to discountRateIds)

allocationConfigIdstring or null(uuid)

Allocation configuration used

rateVersioninteger

Version of rate at settlement time

subscriptionVersioninteger or null

Version of subscription at settlement time

allocationVersioninteger or null

Version of allocation config at settlement time

discountRateVersionsArray of integers

Versions of discount rates at settlement time

settlementTypestringrequired

How the charge was settled

Enum"INVOICED""DIRECT_PAYMENT"
statusstringrequired

Status of settled (immutable) charge

Enum"INVOICED""PARTIALLY_PAID""PAID""REFUNDED""VOID"
originalAmountintegerrequired

Original charge amount in cents

resolvedAmountintegerrequired

Amount after allocation resolution in cents

amountPaidintegerrequired

Amount paid so far in cents

amountOutstandingintegerrequired

Remaining amount in cents

resolvedAllocationobject

Frozen snapshot of allocation at settlement time

resolvedRateobject

Frozen snapshot of rate at settlement time

consolidatedTagsobject

Tags consolidated from all sources with prefixes:

  • profile.billableEntity.*
  • profile.account.*
  • billing.rate.*
  • billing.subscription.*
  • billing.charge.*
settledAtstring(date-time)required
optimisticLockVersioninteger(int64)read-only

Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

createdAtstring(date-time)required
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "originalChargeId": "b6f1f7cb-49e8-4f30-ac44-8630c716f6ba",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "billableEntityId": "efd73805-0b19-4de3-9f1e-a64de8c44765",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
  "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
  "quantity": 0.1,
  "amount": 0,
  "prorationFactor": 0.1,
  "proratedAmount": 0,
  "netAmount": 0,
  "discountRateIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "discountAmounts": [
    0
  ],
  "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
  "rateVersion": 0,
  "subscriptionVersion": 0,
  "allocationVersion": 0,
  "discountRateVersions": [
    0
  ],
  "settlementType": "INVOICED",
  "status": "INVOICED",
  "originalAmount": 0,
  "resolvedAmount": 0,
  "amountPaid": 0,
  "amountOutstanding": 0,
  "resolvedAllocation": {},
  "resolvedRate": {},
  "consolidatedTags": {
    "property1": "string",
    "property2": "string"
  },
  "settledAt": "2019-08-24T14:15:22Z",
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z"
}

Refunds

Manage refunds for invoices, charges, or standalone refunds

Operations

Adjustments

Manage manual adjustments and corrections

Operations

Ledger

Manage double-entry accounting ledger

Operations
Webhooks

Exports

Export data in CSV format for GL integrations

Operations