Skip to content
Billing
/
/
Rates & Rate Cards
Last updated

Rates & Rate Cards

Key idea:
Rates define pricing instructions (debits and discounts). Rate Cards organize rates for discovery in UIs and admin tools. Charges and subscriptions always reference explicit 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

ConceptWhat it means in Billing & Ledger
Debit rateIncreases what is owed (e.g., $100 fee)
Discount rateReduces what is owed (e.g., 10% off or $25 off)
StackingApplying multiple discounts in a defined order
Standalone discountA discount applied without a paired debit (credit/goodwill)
Rate CardA discoverable catalog of rates; not charged directly
VersioningUpdates 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)
Important:
Charges store 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

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

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

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

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

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)

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:

{
  "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
Previous page
Next page