# Rates & Rate Cards

div
strong
Key idea:
br
strong
Rates
 define 
em
pricing instructions
 (debits and discounts). 
strong
Rate Cards
 organize rates for discovery in UIs and admin tools.
  Charges and subscriptions always reference explicit 
code
rateId
 values (and specific versions) so historical billing behavior is stable and auditable.

Rates answer: “How do I represent what should be billed?”
Rate Cards answer: “How do I present rates consistently to humans and UIs?”

## Overview

You will typically do three things:

1) Create debit rates (things you charge) and discount rates (things that reduce what’s owed).
2) Optionally group rates into one or more rate cards (catalogs).
3) Reference rates from **subscriptions** (billing intent) or **charges** (invoice-ready instructions).


## Core concepts

| Concept | What it means in Billing & Ledger |
|  --- | --- |
| **Debit rate** | Increases what is owed (e.g., $100 fee) |
| **Discount rate** | Reduces what is owed (e.g., 10% off or $25 off) |
| **Stacking** | Applying multiple discounts in a defined order |
| **Standalone discount** | A discount applied without a paired debit (credit/goodwill) |
| **Rate Card** | A discoverable catalog of rates; not charged directly |
| **Versioning** | Updates create new versions; existing charges don’t silently change |


## Debit rates

Debit rates represent billable amounts such as:

- Monthly service fee
- Daily usage fee
- One-time registration fee
- Per-unit pricing (quantity-driven)


### Common debit patterns

**Fixed amount**

- Always the same amount per charge


**Unit price**

- Amount * quantity (e.g., $50 × 3 units)


## Discount rates

Discounts are modeled as rates so they behave predictably in versioning and tagging.

### Discount models

**Percent discount**

- Example: 10% off a debit


**Fixed discount**

- Example: $25 off a debit


### Discount stacking (important)

When multiple discounts are applied, the system applies them in order. A typical approach is:

1) Percent discounts first (reduce base)
2) Fixed discounts next (subtract fixed credits)


If your implementation uses a different order, document that order consistently across billing services.

## How rates appear in charges

A charge can represent:

- **Single debit** (one debit rate)
- **Debit + discount(s)** (one debit + one or more discount rates)
- **Standalone discount** (discount rate only)


div
strong
Important:
br

  Charges store 
em
instructions
 (rate references + context), not just a final number. The final resolved totals occur during billing/settlement.

## API examples

All examples use production:

- Base URL: https://api.nelnetpay.com
- Auth: Authorization: Bearer <accessToken>


### Create a fixed debit rate


```bash
curl -X POST "https://api.nelnetpay.com/rates"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Monthly Service Fee",
    "description": "Standard monthly fee",
    "rateType": "DEBIT",
    "pricingModel": "FIXED",
    "amount": 15000,
    "currency": "USD",
    "tags": {
      "billing": {
        "category": "SERVICE_FEE",
        "plan": "STANDARD"
      }
    }
  }'
```

### Create a unit-price debit rate


```bash
curl -X POST "https://api.nelnetpay.com/rates"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Usage Fee",
    "description": "Per-unit usage charge",
    "rateType": "DEBIT",
    "pricingModel": "UNIT",
    "amountPerUnit": 5000,
    "currency": "USD",
    "tags": {
      "billing": {
        "category": "USAGE"
      }
    }
  }'
```

### Create a percent discount rate


```bash
curl -X POST "https://api.nelnetpay.com/rates"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Loyalty Discount",
    "description": "10% discount",
    "rateType": "DISCOUNT",
    "discountModel": "PERCENT",
    "percent": 10,
    "tags": {
      "billing": {
        "discountType": "LOYALTY"
      }
    }
  }'
```

### Create a fixed discount rate


```bash
curl -X POST "https://api.nelnetpay.com/rates"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Promotional Credit",
    "description": "$25 off",
    "rateType": "DISCOUNT",
    "discountModel": "FIXED",
    "amount": 2500,
    "currency": "USD",
    "tags": {
      "billing": {
        "discountType": "PROMO"
      }
    }
  }'
```

## Rate Cards

Rate Cards are catalogs—use them when you want a curated list of rates.

Typical uses:

- Admin portals
- Partner configuration UIs
- Payment Widget configuration (“show these options”)


### Create a rate card


```bash
curl -X POST "https://api.nelnetpay.com/rateCards"   -H "Authorization: Bearer $ACCESS_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "Standard Catalog",
    "description": "Rates available for standard customers",
    "items": [
      { "rateId": "rate_monthly_service_fee" },
      { "rateId": "rate_usage_fee" },
      { "rateId": "rate_loyalty_discount" }
    ],
    "tags": {
      "billing": {
        "catalog": "STANDARD"
      }
    }
  }'
```

### Retrieve a rate card (example)


```bash
curl -X GET "https://api.nelnetpay.com/rateCards/rateCard_standard"   -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Tagging guidance

Rates and rate cards can be tagged to help downstream services:

- Reporting segmentation
- Auditing (“who created this rate?”)
- UI behavior and grouping


Recommended tag patterns:

- Use a nested namespace: billing → category, plan, discountType
- Keep values stable and human-readable


Example:


```json
{
  "tags": {
    "billing": {
      "category": "SERVICE_FEE",
      "plan": "STANDARD",
      "createdBy": "admin-ui"
    }
  }
}
```

## What’s next

- **Allocation Rules & Responsibility**: who pays and how caps/coverage work
- **Subscriptions & Billing Intent**: cadence, proration, and lifecycle
- **Versioning & Change Management**: safe updates without rewriting history