# Subscriptions & Billing Intent

div
strong
Key idea:
br

  A subscription expresses 
em
billing intent
: who should be billed, what rates apply, how responsibility is allocated, and the billing cadence.
  A subscription does 
strong
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


div
strong
Important:
br

  Subscriptions capture intent. Charges are where “this period’s billing” becomes concrete.

## API examples

### Create a billable-entity subscription


```bash
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


```bash
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


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

### Resume


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

### Cancel


```bash
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:


```json
{
  "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.