Skip to content
API & References
/
Billing & Ledger
/
/
Update Subscription

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

List Subscriptions

Request

List all subscriptions for the authenticated merchant. Subscriptions link billable entities to rates with allocation configurations.

Security
OAuth2
Query
billable_entity_idstring(uuid)

Filter by billable entity ID

statusstring

Filter by subscription status

Enum"ACTIVE""PAUSED""CANCELLED"
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/subscriptions?billable_entity_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&status=ACTIVE&page=1&page_size=50' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

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

Reference to BillableEntity in Profile Service

results[].​rateIdstring(uuid)required
results[].​allocationConfigIdstring(uuid)required
results[].​discountRateIdsArray of strings(uuid)

Discount rates to apply

results[].​billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
results[].​billingAnchorDayinteger[ 1 .. 31 ]required

Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

results[].​billingTimezonestringrequired

IANA timezone for billing calculations

Example: "America/New_York"
results[].​startDatestring(date)required
results[].​endDatestring or null(date)
results[].​statusstringrequired

Status of subscription

Enum"ACTIVE""PAUSED""CANCELLED"
results[].​versionintegerrequired

Business version number for change tracking (subscription configuration history)

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": 100,
    "currentPage": 1,
    "totalPages": 10,
    "nextPage": 2,
    "prevPage": null
  }
}

Create Subscription

Request

Create a new subscription linking a billable entity to a rate.

Validation: The billable entity must be associated with ALL accounts referenced in the allocation configuration. This is validated via Profile Service.

Billing Frequency:

  • DAILY - Charges generated daily
  • WEEKLY - Charges generated weekly (anchorDay = day of week 1-7)
  • BIWEEKLY - Charges generated every two weeks
  • MONTHLY - Charges generated monthly (anchorDay = day of month 1-31)
Security
OAuth2
Bodyapplication/jsonrequired
billableEntityIdstring(uuid)required
rateIdstring(uuid)required
allocationConfigIdstring(uuid)required
discountRateIdsArray of strings(uuid)
billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]required
billingTimezonestringrequired
startDatestring(date)required
endDatestring(date)
curl -i -X POST \
  https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/subscriptions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "billableEntityId": "550e8400-e29b-41d4-a716-446655440010",
    "rateId": "550e8400-e29b-41d4-a716-446655440001",
    "allocationConfigId": "550e8400-e29b-41d4-a716-446655440020",
    "discountRateIds": [
      "550e8400-e29b-41d4-a716-446655440002"
    ],
    "billingFrequency": "WEEKLY",
    "billingAnchorDay": 1,
    "billingTimezone": "America/New_York",
    "startDate": "2026-01-20"
  }'

Responses

Subscription created successfully

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
billableEntityIdstring(uuid)required

Reference to BillableEntity in Profile Service

rateIdstring(uuid)required
allocationConfigIdstring(uuid)required
discountRateIdsArray of strings(uuid)

Discount rates to apply

billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]required

Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

billingTimezonestringrequired

IANA timezone for billing calculations

Example: "America/New_York"
startDatestring(date)required
endDatestring or null(date)
statusstringrequired

Status of subscription

Enum"ACTIVE""PAUSED""CANCELLED"
versionintegerrequired

Business version number for change tracking (subscription configuration history)

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",
  "billableEntityId": "efd73805-0b19-4de3-9f1e-a64de8c44765",
  "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
  "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
  "discountRateIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "billingFrequency": "DAILY",
  "billingAnchorDay": 1,
  "billingTimezone": "America/New_York",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "status": "ACTIVE",
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get Subscription Details

Request

Retrieve details of a specific subscription

Security
OAuth2
Path
subscriptionIdstring(uuid)required

Unique identifier for the subscription

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

Responses

Successful response

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
billableEntityIdstring(uuid)required

Reference to BillableEntity in Profile Service

rateIdstring(uuid)required
allocationConfigIdstring(uuid)required
discountRateIdsArray of strings(uuid)

Discount rates to apply

billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]required

Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

billingTimezonestringrequired

IANA timezone for billing calculations

Example: "America/New_York"
startDatestring(date)required
endDatestring or null(date)
statusstringrequired

Status of subscription

Enum"ACTIVE""PAUSED""CANCELLED"
versionintegerrequired

Business version number for change tracking (subscription configuration history)

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",
  "billableEntityId": "efd73805-0b19-4de3-9f1e-a64de8c44765",
  "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
  "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
  "discountRateIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "billingFrequency": "DAILY",
  "billingAnchorDay": 1,
  "billingTimezone": "America/New_York",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "status": "ACTIVE",
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update Subscription

Request

Update a subscription's information (partial update).

Version Tracking: Each update increments the subscription version. Existing charges retain the version from when they were created.

Security
OAuth2
Path
subscriptionIdstring(uuid)required

Unique identifier for the subscription

Bodyapplication/jsonrequired
rateIdstring(uuid)
allocationConfigIdstring(uuid)
discountRateIdsArray of strings(uuid)
billingFrequencystring

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]
billingTimezonestring
endDatestring(date)
curl -i -X PATCH \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/subscriptions/{subscriptionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
    "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
    "discountRateIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "billingFrequency": "DAILY",
    "billingAnchorDay": 1,
    "billingTimezone": "string",
    "endDate": "2019-08-24"
  }'

Responses

Subscription updated successfully

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
billableEntityIdstring(uuid)required

Reference to BillableEntity in Profile Service

rateIdstring(uuid)required
allocationConfigIdstring(uuid)required
discountRateIdsArray of strings(uuid)

Discount rates to apply

billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]required

Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

billingTimezonestringrequired

IANA timezone for billing calculations

Example: "America/New_York"
startDatestring(date)required
endDatestring or null(date)
statusstringrequired

Status of subscription

Enum"ACTIVE""PAUSED""CANCELLED"
versionintegerrequired

Business version number for change tracking (subscription configuration history)

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",
  "billableEntityId": "efd73805-0b19-4de3-9f1e-a64de8c44765",
  "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
  "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
  "discountRateIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "billingFrequency": "DAILY",
  "billingAnchorDay": 1,
  "billingTimezone": "America/New_York",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "status": "ACTIVE",
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Pause Subscription

Request

Pause a subscription to temporarily stop charge generation

Security
OAuth2
Path
subscriptionIdstring(uuid)required

Unique identifier for the subscription

curl -i -X POST \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/subscriptions/{subscriptionId}/pause' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Subscription paused successfully

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
billableEntityIdstring(uuid)required

Reference to BillableEntity in Profile Service

rateIdstring(uuid)required
allocationConfigIdstring(uuid)required
discountRateIdsArray of strings(uuid)

Discount rates to apply

billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]required

Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

billingTimezonestringrequired

IANA timezone for billing calculations

Example: "America/New_York"
startDatestring(date)required
endDatestring or null(date)
statusstringrequired

Status of subscription

Enum"ACTIVE""PAUSED""CANCELLED"
versionintegerrequired

Business version number for change tracking (subscription configuration history)

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",
  "billableEntityId": "efd73805-0b19-4de3-9f1e-a64de8c44765",
  "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
  "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
  "discountRateIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "billingFrequency": "DAILY",
  "billingAnchorDay": 1,
  "billingTimezone": "America/New_York",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "status": "ACTIVE",
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Resume Subscription

Request

Resume a paused subscription

Security
OAuth2
Path
subscriptionIdstring(uuid)required

Unique identifier for the subscription

curl -i -X POST \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/subscriptions/{subscriptionId}/resume' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Subscription resumed successfully

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
billableEntityIdstring(uuid)required

Reference to BillableEntity in Profile Service

rateIdstring(uuid)required
allocationConfigIdstring(uuid)required
discountRateIdsArray of strings(uuid)

Discount rates to apply

billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]required

Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

billingTimezonestringrequired

IANA timezone for billing calculations

Example: "America/New_York"
startDatestring(date)required
endDatestring or null(date)
statusstringrequired

Status of subscription

Enum"ACTIVE""PAUSED""CANCELLED"
versionintegerrequired

Business version number for change tracking (subscription configuration history)

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",
  "billableEntityId": "efd73805-0b19-4de3-9f1e-a64de8c44765",
  "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
  "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
  "discountRateIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "billingFrequency": "DAILY",
  "billingAnchorDay": 1,
  "billingTimezone": "America/New_York",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "status": "ACTIVE",
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Cancel Subscription

Request

Cancel a subscription permanently.

Note: This does not void existing charges. Use charge void endpoints for that.

Security
OAuth2
Path
subscriptionIdstring(uuid)required

Unique identifier for the subscription

Bodyapplication/json
effectiveDatestring(date)

Date when cancellation takes effect (defaults to today)

reasonstring

Reason for cancellation

curl -i -X POST \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/subscriptions/{subscriptionId}/cancel' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "effectiveDate": "2019-08-24",
    "reason": "string"
  }'

Responses

Subscription cancelled successfully

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
billableEntityIdstring(uuid)required

Reference to BillableEntity in Profile Service

rateIdstring(uuid)required
allocationConfigIdstring(uuid)required
discountRateIdsArray of strings(uuid)

Discount rates to apply

billingFrequencystringrequired

Billing frequency for subscriptions

Enum"DAILY""WEEKLY""BIWEEKLY""MONTHLY"
billingAnchorDayinteger[ 1 .. 31 ]required

Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

billingTimezonestringrequired

IANA timezone for billing calculations

Example: "America/New_York"
startDatestring(date)required
endDatestring or null(date)
statusstringrequired

Status of subscription

Enum"ACTIVE""PAUSED""CANCELLED"
versionintegerrequired

Business version number for change tracking (subscription configuration history)

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",
  "billableEntityId": "efd73805-0b19-4de3-9f1e-a64de8c44765",
  "rateId": "dc6263b0-e8fb-4144-a111-53fde6c86836",
  "allocationConfigId": "dacda6b8-3e25-4031-b6a4-1ec5aa108ab2",
  "discountRateIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "billingFrequency": "DAILY",
  "billingAnchorDay": 1,
  "billingTimezone": "America/New_York",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "status": "ACTIVE",
  "version": 0,
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

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