Skip to content
API & References
/
Billing & Ledger
/
/
Get Rate Details

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

List Rates

Request

List all rates (pricing catalog) for the authenticated merchant with pagination and filtering. Rates define how much each type of service costs.

Security
OAuth2
Query
typestring

Filter by rate type

Enum"service fee""LATE_FEE""REGISTRATION""DISCOUNT""OTHER"
tagsstring

Filter by tags using dot.notation (key:value pairs, comma-separated)

Example: tags=billing.program:PRE_K,billing.taxable:false
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/rates?type=service+fee&tags=billing.program%3APRE_K%2Cbilling.taxable%3Afalse&page=1&page_size=50' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
resultsArray of objectsrequired
results[].​idstring(uuid)required

Unique identifier

results[].​entityIdstring(uuid)required

Merchant identifier (from auth context)

results[].​descriptionstringrequired

Human-readable description of the rate

results[].​typestringrequired

Type of rate

Enum"service fee""LATE_FEE""REGISTRATION""DISCOUNT""OTHER"
results[].​pricePerUnitinteger

Price per unit in cents (e.g., 5000 = $50.00). Required unless type is DISCOUNT.

results[].​discountPercentagenumber(double)[ 0 .. 100 ]

Discount percentage (only for type DISCOUNT)

results[].​tagsobject

Tags for categorization and reporting

results[].​versionintegerread-only

Business version number for audit history and deterministic billing (auto-incremented on updates)

results[].​optimisticLockVersioninteger(int64)read-only

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

results[].​createdAtstring(date-time)required
results[].​updatedAtstring(date-time)
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": 1,
    "currentPage": 1,
    "totalPages": 1,
    "nextPage": null,
    "prevPage": null
  }
}

Create Rate

Request

Create a new rate in the pricing catalog.

Rate Types:

  • service fee - Regular service fee/service fees
  • LATE_FEE - Late payment penalties
  • REGISTRATION - One-time registration fees
  • DISCOUNT - Discount rates (use discountPercentage instead of pricePerUnit)
  • OTHER - Miscellaneous charges
Security
OAuth2
Bodyapplication/jsonrequired
descriptionstring<= 255 charactersrequired
typestringrequired

Type of rate

Enum"service fee""LATE_FEE""REGISTRATION""DISCOUNT""OTHER"
pricePerUnitinteger>= 0

Required unless type is DISCOUNT

discountPercentagenumber(double)[ 0 .. 100 ]

Required if type is DISCOUNT

tagsobject
curl -i -X POST \
  https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/rates \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Pre-K Daily Rate",
    "type": "service fee",
    "pricePerUnit": 5000,
    "tags": {
      "billing.category": "service fee",
      "billing.program": "PRE_K",
      "billing.taxable": "false",
      "billing.glCode": "4000"
    }
  }'

Responses

Rate created successfully

Bodyapplication/json
idstring(uuid)required

Unique identifier

entityIdstring(uuid)required

Merchant identifier (from auth context)

descriptionstringrequired

Human-readable description of the rate

typestringrequired

Type of rate

Enum"service fee""LATE_FEE""REGISTRATION""DISCOUNT""OTHER"
pricePerUnitinteger

Price per unit in cents (e.g., 5000 = $50.00). Required unless type is DISCOUNT.

discountPercentagenumber(double)[ 0 .. 100 ]

Discount percentage (only for type DISCOUNT)

tagsobject

Tags for categorization and reporting

versionintegerread-only

Business version number for audit history and deterministic billing (auto-incremented on updates)

optimisticLockVersioninteger(int64)read-only

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

createdAtstring(date-time)required
updatedAtstring(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "description": "string",
  "type": "service fee",
  "pricePerUnit": 0,
  "discountPercentage": 100,
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get Rate Details

Request

Retrieve details of a specific rate

Security
OAuth2
Path
rateIdstring(uuid)required

Unique identifier for the rate

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

Responses

Successful response

Bodyapplication/json
idstring(uuid)required

Unique identifier

entityIdstring(uuid)required

Merchant identifier (from auth context)

descriptionstringrequired

Human-readable description of the rate

typestringrequired

Type of rate

Enum"service fee""LATE_FEE""REGISTRATION""DISCOUNT""OTHER"
pricePerUnitinteger

Price per unit in cents (e.g., 5000 = $50.00). Required unless type is DISCOUNT.

discountPercentagenumber(double)[ 0 .. 100 ]

Discount percentage (only for type DISCOUNT)

tagsobject

Tags for categorization and reporting

versionintegerread-only

Business version number for audit history and deterministic billing (auto-incremented on updates)

optimisticLockVersioninteger(int64)read-only

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

createdAtstring(date-time)required
updatedAtstring(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "description": "string",
  "type": "service fee",
  "pricePerUnit": 0,
  "discountPercentage": 100,
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update Rate

Request

Update a rate's information (partial update).

Note: Updating a rate does NOT affect existing charges or subscriptions. They retain the rate version from when they were created.

Security
OAuth2
Path
rateIdstring(uuid)required

Unique identifier for the rate

Bodyapplication/jsonrequired
descriptionstring<= 255 characters
pricePerUnitinteger>= 0
discountPercentagenumber(double)[ 0 .. 100 ]
tagsobject
curl -i -X PATCH \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/rates/{rateId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Pre-K Daily Rate (2026)",
    "pricePerUnit": 5500
  }'

Responses

Rate updated successfully

Bodyapplication/json
idstring(uuid)required

Unique identifier

entityIdstring(uuid)required

Merchant identifier (from auth context)

descriptionstringrequired

Human-readable description of the rate

typestringrequired

Type of rate

Enum"service fee""LATE_FEE""REGISTRATION""DISCOUNT""OTHER"
pricePerUnitinteger

Price per unit in cents (e.g., 5000 = $50.00). Required unless type is DISCOUNT.

discountPercentagenumber(double)[ 0 .. 100 ]

Discount percentage (only for type DISCOUNT)

tagsobject

Tags for categorization and reporting

versionintegerread-only

Business version number for audit history and deterministic billing (auto-incremented on updates)

optimisticLockVersioninteger(int64)read-only

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

createdAtstring(date-time)required
updatedAtstring(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "description": "string",
  "type": "service fee",
  "pricePerUnit": 0,
  "discountPercentage": 100,
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Delete Rate

Request

Soft delete a rate (marked as deleted but retained for audit purposes).

Restrictions: Cannot delete a rate that is referenced by active subscriptions or unbilled charges.

Security
OAuth2
Path
rateIdstring(uuid)required

Unique identifier for the rate

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

Responses

Rate deleted successfully

Response
No content

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

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