Skip to content
Billing
/
/
Subscriptions & Billing I...
Last updated

Subscriptions & Billing Intent

Key idea:
A subscription expresses billing intent: who should be billed, what rates apply, how responsibility is allocated, and the billing cadence. A subscription does not execute billing by itself—it provides the blueprint used to generate charges.

Subscriptions answer: “What should happen every billing cycle?”

What a subscription defines

A subscription typically includes:

  • Target: either a billableEntityId (service recipient) or an accountId (direct billing)
  • Pricing: a debit rate and optional discount rates
  • Responsibility: an allocation configuration
  • Schedule: frequency, anchor, timezone, start/end dates
  • Lifecycle: status (ACTIVE / PAUSED / CANCELED)

Billable Entity vs Account

Billable Entity subscription (most common)

Use when billing is tied to services rendered to a specific recipient.

Example use cases:

  • Participant in a program
  • Dependent receiving services
  • Member-based services

Account subscription (direct billing)

Use when the charge should be billed directly to the responsible account.

Example use cases:

  • Registration fee
  • Administrative fee
  • Account-level balance billing

Schedule: frequency + anchor + timezone

Subscriptions standardize billing cadence.

Typical patterns:

  • Monthly on the 1st
  • Weekly on Monday
  • Quarterly on a specific month/day

Time zone matters because it determines:

  • when cycle boundaries start/end
  • how proration is calculated
  • how timestamps align in reporting

Proration (how mid-cycle changes work)

Proration happens when:

  • a subscription starts mid-cycle
  • a subscription ends mid-cycle
  • a subscription changes cadence

Example: mid-month start

  • Billing runs on the 1st of the month
  • A new participant starts on February 15
  • The billing system should produce a prorated charge for February

A common implementation:

  • the orchestrator creates a charge with an event date (Feb 15)
  • the billing system resolves proration based on the cycle boundary and the subscription schedule
Important:
Subscriptions capture intent. Charges are where “this period’s billing” becomes concrete.

API examples

Create a billable-entity subscription

curl -X POST "https://api.nelnetpay.com/subscriptions"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "billableEntityId": "be_emily",
    "rateId": "rate_monthly_service_fee",
    "discountRateIds": ["rate_loyalty_discount"],
    "allocationConfigurationId": "alloc_single_family_100",
    "frequency": "MONTHLY",
    "anchorDay": 1,
    "timeZone": "America/Chicago",
    "startDate": "2026-02-15",
    "status": "ACTIVE",
    "tags": {
      "billing": {
        "subscriptionSource": "admin-ui",
        "program": "STANDARD"
      }
    }
  }'

Create an account-level subscription

curl -X POST "https://api.nelnetpay.com/subscriptions"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "accountId": "acct_smith",
    "rateId": "rate_registration_fee",
    "allocationConfigurationId": "alloc_single_family_100",
    "frequency": "ONE_TIME",
    "timeZone": "America/Chicago",
    "startDate": "2026-02-01",
    "status": "ACTIVE"
  }'

Updating subscription lifecycle (no verb endpoints)

To pause/resume/cancel, update the subscription status via PATCH (or PUT depending on your API style).

Pause

curl -X PATCH "https://api.nelnetpay.com/subscriptions/sub_123"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{ "status": "PAUSED" }'

Resume

curl -X PATCH "https://api.nelnetpay.com/subscriptions/sub_123"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{ "status": "ACTIVE" }'

Cancel

curl -X PATCH "https://api.nelnetpay.com/subscriptions/sub_123"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{ "status": "CANCELED", "endDate": "2026-03-31" }'

How subscriptions interact with charges

A typical operational flow:

  1. Subscription exists (intent)
  2. A scheduler/orchestrator identifies subscriptions due for billing
  3. The orchestrator creates charges for the appropriate period
  4. Charges remain mutable until invoicing/settlement locks them

This separation makes it possible to:

  • preview/adjust charges before finalization
  • apply proration deterministically
  • preserve audit integrity

Tagging

Subscriptions can be tagged for:

  • reporting segmentation (program, cohort, channel)
  • auditing (source system, admin user)
  • downstream invoice grouping

Example:

{
  "tags": {
    "billing": {
      "program": "STANDARD",
      "createdBy": "admin-ui",
      "channel": "partner-x"
    }
  }
}

Versioning notes

Subscriptions are versioned:

  • updates create a new version
  • existing charges retain their snapshot
  • new charges use the latest subscription version by default

See Versioning & Change Management for change patterns and migration guidance.

Previous page
Next page