Lumen Documentation

Credits provide allowances for features or discounts on invoices. They are the primary way Lumen handles "what's included" in a plan and are the highest-priority input into any entitlement check. They are composed of two parts:

Credit Definitions: Reusable templates that define the rules for a credit — its amount, renewal frequency, and expiry.
Credit Grants: An instance of a definition applied to a specific customer, giving them an allowance.

When to Use Credits

To include a free allowance for a usage-based feature (e.g., 10,000 API calls per month).
To offer trials or promotional access that automatically expires.
To provide invoice discounts or service credits for support cases.
To model refills that align with billing cycles or renew on a custom schedule.

How Credits Work: The Full Loop

1. Define the Credit

You first create a reusable Credit Definition. For a usage credit, this is where you link the credit to a specific featureSlug.

# POST /v1/credit-definitions
# Creates a reusable template for 10,000 monthly API credits.
curl -X POST "https://api.getlumen.dev/v1/credit-definitions" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly API Credits",
    "applicationType": "usage",
    "featureSlug": "api-calls",
    "defaultAmount": 10000,
    "refillAmount": 10000,
    "renewOnBilling": true
  }'

2. Grant the Credit

Next, you give the credit to a customer via a Credit Grant. This is often done automatically when a customer subscribes to a plan.

# POST /v1/credit-grants
# Grants the monthly API credits to a specific customer.
curl -X POST "https://api.getlumen.dev/v1/credit-grants" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_123",
    "creditDefinitionId": "cd_monthly_api",
    "initialAmount": 10000
  }'

3. Check Entitlement & Report Usage

As described in the Entitlements guide, your application performs the check -> act -> report loop. The report step, sending a usage event, is what consumes the credit.

# POST /v1/events
# This event decrements the customer's credit balance for "api-calls".
curl -X POST "https://api.getlumen.dev/v1/events" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "api-calls",
    "customerId": "cust_123",
    "eventValue": 1,
    "idempotencyKey": "txn_12345"
  }'

4. See Credits on the Invoice

At the end of the billing cycle, any applied monetary credits or consumed usage credits (if they offset a priced feature) will appear as line items on the customer's invoice, clearly showing their value.

How Credits Affect Entitlements

When you check an entitlement for a feature that has an active credit grant, the credit's allowance takes precedence over any limit defined on the plan. For numeric features, the feature.value reflects the credit allowance and the API response will indicate credits as the source.

# GET /v1/entitlements/cust_123/feature/api-calls
# This customer is on a plan with 1,000 calls, but has a credit grant for 10,000.

The response shows the credit allowance is being used, and the customer is entitled.

{
  "entitled": true,
  "feature": {
    "slug": "api-calls",
    "value": 10000
  },
  "source": "credits",
  "creditInfo": {
    "creditAllowance": 10000,
    "creditsRemaining": 8500,
    "nextExpiryDate": "2025-10-01T00:00:00Z"
  }
}

Credit Types & Common Patterns

Usage Credits

Usage credits provide an allowance for a specific feature.

Hard Limit: If a feature has credits but no overage pricing on the plan, entitlement checks will fail once the credits are used up.
Overage: If you also configure overage pricing, usage beyond the credit allowance will be billed automatically.
Trials: A trial is just a one-time credit grant that expires. Create a grant with a specific expiryDate.

Monetary Credits

Monetary credits apply a discount directly to a customer's next invoice. They are useful for one-off adjustments, support cases, or promotions.

# POST /v1/credit-grants
# Grants a $50.00 credit to the customer's next invoice.
curl -X POST "https://api.getlumen.dev/v1/credit-grants" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_123",
    "creditType": "monetary",
    "amount": 5000,
    "currency": "USD",
    "reason": "support-credit"
  }'

UI vs API

UI (recommended)
- Add usage-based features to plans; the UI wires metrics and credit definitions for you.
- Choose renewal rules and default amounts.
- Grant/adjust credits from the dashboard for support and promotions.
API (advanced)
- Custom renewal rules (RRULE), cross-plan scopes, and bulk operations.
- Monetary credits applied directly to invoices.
- Migration tooling and idempotent provisioning.

Common pitfalls

Forgetting to link a usage credit definition to the feature, which means usage has no allowance.
Forgetting to send usage events, which means credits are never consumed.
Expecting unused credits to roll over when expiryDays is set, as it causes a reset at renewal.
Using timezones (TZID) in RRULEs, which is not supported. Keep RRULEs in UTC.

Credits