Lumen
API Reference

Credits API

Complete guide to managing credits, grants, and usage tracking via the API

Credits API

The Credits API allows you to create flexible credit systems for your customers, including usage-based credits, monetary credits, and automated renewal mechanisms. Credits can be scoped to merchants, plans, or specific features, providing granular control over customer entitlements.

Overview

The credits system consists of three main components:

  • Credit Definitions: Templates that define how credits work (usage/monetary, amounts, renewal rules)
  • Credit Grants: Individual credit allocations given to specific customers
  • Credit Transactions: Historical record of credit usage and events

Credit Types

Usage Credits

  • Applied against feature usage (API calls, storage, etc.)
  • Can be linked to specific features or pricing components
  • Automatically deducted when features are used

Monetary Credits

  • Applied as discounts against invoice amounts
  • Always billing-visible and require currency specification
  • Can be merchant-wide or plan-specific

Credit Scopes

  • Merchant: Credits applicable across all customer subscriptions
  • Plan: Credits that only apply to specific subscription plans

Authentication

All API requests require authentication via merchant credentials.

Credit Definitions

Get All Credit Definitions

Get all credit definitions for the authenticated merchant.

GET /api/credits/definitions?scope={scope}&applicationType={applicationType}

Query Parameters

ParameterTypeDescription
scopestringFilter by scope: merchant or plan
applicationTypestringFilter by type: usage or monetary

Response

{
  "definitions": [
    {
      "id": "cd_123",
      "merchantId": "merchant_123",
      "name": "API Call Credits",
      "description": "Credits for API usage",
      "scope": "plan",
      "applicationType": "usage",
      "planId": "plan_123",
      "featureId": "feature_api_calls",
      "featureSlug": "api-calls",
      "defaultAmount": 1000,
      "refillAmount": 1000,
      "expiryDays": 30,
      "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
      "renewOnBilling": true,
      "priority": 1,
      "billingVisible": false,
      "billingDescription": null,
      "currency": null,
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "deletedAt": null
    }
  ]
}

Get Credit Definition by ID

Get a specific credit definition by its ID.

GET /api/credits/definitions/{id}

Parameters

ParameterTypeDescription
idstringCredit Definition ID

Response

{
  "definition": {
    "id": "cd_123",
    "merchantId": "merchant_123",
    "name": "API Call Credits",
    "description": "Credits for API usage",
    "scope": "plan",
    "applicationType": "usage",
    "planId": "plan_123",
    "featureId": "feature_api_calls",
    "featureSlug": "api-calls",
    "defaultAmount": 1000,
    "refillAmount": 1000,
    "expiryDays": 30,
    "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
    "renewOnBilling": true,
    "priority": 1,
    "billingVisible": false,
    "billingDescription": null,
    "currency": null,
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "deletedAt": null
  }
}

Create Credit Definition

Create a new credit definition.

POST /api/credits/definitions

Request Body

{
  "name": "Storage Credits",
  "description": "Credits for file storage",
  "scope": "plan",
  "applicationType": "usage",
  "planId": "plan_123",
  "featureId": "feature_storage",
  "featureSlug": "storage",
  "defaultAmount": 5000,
  "refillAmount": 5000,
  "expiryDays": 30,
  "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
  "renewOnBilling": true,
  "priority": 2,
  "billingVisible": false
}

Request Fields

FieldTypeRequiredDescription
namestring✓Display name for the credit definition
scopestring✓Credit scope: merchant or plan
applicationTypestring✓Credit type: usage or monetary
defaultAmountnumber✓Default credit amount when granted
descriptionstringOptional description
planIdstring*Required when scope is plan
featureIdstring*Feature ID for usage credits
featureSlugstring*Feature slug for usage credits
priceIdstring*Price ID for usage credits (paid plans)
priceComponentIdstring*Price component ID for usage credits
refillAmountnumberAmount to refill during renewals
expiryDaysnumberDays until credits expire
refillRrulestringRRULE for automatic renewals
renewOnBillingbooleanWhether to renew on billing cycle
prioritynumberPriority for credit application (higher first)
billingVisiblebooleanWhether credits appear on invoices
billingDescriptionstringDescription for billing/invoices
currencystring*Required for monetary credits

* Conditional requirements based on scope and applicationType

Response

{
  "definition": {
    "id": "cd_456",
    "merchantId": "merchant_123",
    "name": "Storage Credits",
    "description": "Credits for file storage",
    "scope": "plan",
    "applicationType": "usage",
    "planId": "plan_123",
    "featureId": "feature_storage",
    "featureSlug": "storage",
    "defaultAmount": 5000,
    "refillAmount": 5000,
    "expiryDays": 30,
    "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
    "renewOnBilling": true,
    "priority": 2,
    "billingVisible": false,
    "billingDescription": null,
    "currency": null,
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "deletedAt": null
  }
}

Update Credit Definition

Update an existing credit definition.

POST /api/credits/definitions/{id}/update

Parameters

ParameterTypeDescription
idstringCredit Definition ID

Request Body

{
  "name": "Updated Storage Credits",
  "description": "Updated description",
  "defaultAmount": 10000,
  "refillAmount": 10000,
  "expiryDays": 60,
  "isActive": false
}

Request Fields

All fields are optional and only provided fields will be updated:

FieldTypeDescription
namestringDisplay name for the credit definition
descriptionstringOptional description
billingDescriptionstringDescription for billing/invoices
applicationTypestringCredit type: usage or monetary
scopestringCredit scope: merchant or plan
planIdstringPlan ID for plan-scoped credits
featureIdstringFeature ID for usage credits
featureSlugstringFeature slug for usage credits
priceIdstringPrice ID for usage credits
priceComponentIdstringPrice component ID for usage credits
defaultAmountnumberDefault credit amount when granted
refillAmountnumberAmount to refill during renewals
expiryDaysnumberDays until credits expire
refillRrulestringRRULE for automatic renewals
renewOnBillingbooleanWhether to renew on billing cycle
prioritynumberPriority for credit application (higher first)
isActivebooleanWhether the definition is active

Response

{
  "definition": {
    "id": "cd_456",
    "merchantId": "merchant_123",
    "name": "Updated Storage Credits",
    "description": "Updated description",
    "scope": "plan",
    "applicationType": "usage",
    "planId": "plan_123",
    "featureId": "feature_storage",
    "featureSlug": "storage",
    "defaultAmount": 10000,
    "refillAmount": 10000,
    "expiryDays": 60,
    "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
    "renewOnBilling": true,
    "priority": 2,
    "billingVisible": false,
    "billingDescription": null,
    "currency": null,
    "isActive": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "deletedAt": null
  }
}

Delete Credit Definition

Soft delete a credit definition (preserves historical data).

POST /api/credits/definitions/{id}/delete

Parameters

ParameterTypeDescription
idstringCredit Definition ID

Response

{
  "definition": {
    "id": "cd_456",
    "merchantId": "merchant_123",
    "name": "Updated Storage Credits",
    "description": "Updated description",
    "scope": "plan",
    "applicationType": "usage",
    "planId": "plan_123",
    "featureId": "feature_storage",
    "featureSlug": "storage",
    "defaultAmount": 10000,
    "refillAmount": 10000,
    "expiryDays": 60,
    "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
    "renewOnBilling": true,
    "priority": 2,
    "billingVisible": false,
    "billingDescription": null,
    "currency": null,
    "isActive": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "deletedAt": "2024-01-15T11:00:00Z"
  }
}

Get Plan Credit Definitions

Get all credit definitions for a specific plan.

GET /api/credits/plans/{planId}/definitions?applicationType={applicationType}

Parameters

ParameterTypeDescription
planIdstringPlan ID

Query Parameters

ParameterTypeDescription
applicationTypestringFilter by type: usage or monetary

Response

{
  "definitions": [
    {
      "id": "cd_123",
      "merchantId": "merchant_123",
      "name": "Plan API Credits",
      "description": "API credits for this plan",
      "scope": "plan",
      "applicationType": "usage",
      "planId": "plan_123",
      "featureId": "feature_api_calls",
      "featureSlug": "api-calls",
      "defaultAmount": 1000,
      "refillAmount": 1000,
      "expiryDays": 30,
      "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
      "renewOnBilling": true,
      "priority": 1,
      "billingVisible": false,
      "billingDescription": null,
      "currency": null,
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "deletedAt": null
    }
  ]
}

Credit Grants

Get Customer Credit Grants

Get all credit grants for a specific customer.

GET /api/credits/customers/{customerId}/grants?status={status}&applicationType={applicationType}

Parameters

ParameterTypeDescription
customerIdstringCustomer ID

Query Parameters

ParameterTypeDescription
statusstringFilter by status: ACTIVE, EXPIRED, REVOKED
applicationTypestringFilter by type: usage or monetary

Response

{
  "grants": [
    {
      "id": "cg_123",
      "merchantId": "merchant_123",
      "customerId": "cust_456",
      "creditDefinitionId": "cd_123",
      "initialAmount": 1000,
      "remainingAmount": 750,
      "status": "ACTIVE",
      "applicationType": "usage",
      "scope": "plan",
      "planId": "plan_123",
      "featureId": "feature_api_calls",
      "featureSlug": "api-calls",
      "priceId": null,
      "priceComponentId": null,
      "currency": null,
      "priority": 1,
      "startDate": "2024-01-01T00:00:00Z",
      "expiryDate": "2024-01-31T23:59:59Z",
      "source": "ADMIN_GRANTED",
      "referenceCode": "WELCOME_BONUS",
      "notes": "Welcome bonus for new customer",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "deletedAt": null,
      "creditDefinition": {
        "id": "cd_123",
        "name": "API Call Credits",
        "description": "Credits for API usage"
      }
    }
  ]
}

Get Customer Credit Transactions

Get credit usage history for a specific customer.

GET /api/credits/customers/{customerId}/transactions?limit={limit}&fromDate={fromDate}&toDate={toDate}

Parameters

ParameterTypeDescription
customerIdstringCustomer ID

Query Parameters

ParameterTypeDescription
limitnumberMaximum number of transactions (max 1000)
fromDatestringStart date (ISO 8601 format)
toDatestringEnd date (ISO 8601 format)

Response

{
  "transactions": [
    {
      "id": "ct_123",
      "merchantId": "merchant_123",
      "customerId": "cust_456",
      "creditGrantId": "cg_123",
      "amount": 10,
      "applicationType": "usage",
      "eventName": "api_call",
      "eventTimestamp": "2024-01-15T10:30:00Z",
      "featureId": "feature_api_calls",
      "featureSlug": "api-calls",
      "priceId": null,
      "priceComponentId": null,
      "currency": null,
      "metadata": {
        "endpoint": "/api/users",
        "method": "GET"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Credit Grant

Create a new credit grant for a customer.

POST /api/credits/grants

Request Body

{
  "customerId": "cust_456",
  "creditDefinitionId": "cd_123",
  "initialAmount": 2000,
  "startDate": "2024-01-01T00:00:00Z",
  "expiryDate": "2024-12-31T23:59:59Z",
  "priority": 5,
  "source": "ADMIN_GRANTED",
  "referenceCode": "PROMO_2024",
  "notes": "Promotional credits for Q1 2024"
}

Request Fields

FieldTypeRequiredDescription
customerIdstring✓Customer ID to grant credits to
creditDefinitionIdstring✓Credit definition ID to base grant on
initialAmountnumberOverride default amount from definition
startDatestringWhen credits become available (ISO 8601)
expiryDatestringWhen credits expire (ISO 8601)
prioritynumberOverride priority from definition
sourcestring✓Grant source: ADMIN_GRANTED, PLAN_BENEFIT, RENEWAL, PROMO
referenceCodestringReference code for tracking
notesstringOptional notes about the grant

Response

{
  "grant": {
    "id": "cg_789",
    "merchantId": "merchant_123",
    "customerId": "cust_456",
    "creditDefinitionId": "cd_123",
    "initialAmount": 2000,
    "remainingAmount": 2000,
    "status": "ACTIVE",
    "applicationType": "usage",
    "scope": "plan",
    "planId": "plan_123",
    "featureId": "feature_api_calls",
    "featureSlug": "api-calls",
    "priceId": null,
    "priceComponentId": null,
    "currency": null,
    "priority": 5,
    "startDate": "2024-01-01T00:00:00Z",
    "expiryDate": "2024-12-31T23:59:59Z",
    "source": "ADMIN_GRANTED",
    "referenceCode": "PROMO_2024",
    "notes": "Promotional credits for Q1 2024",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "deletedAt": null
  }
}

Revoke Credit Grant

Revoke an active credit grant.

POST /api/credits/grants/{id}/revoke

Parameters

ParameterTypeDescription
idstringCredit Grant ID

Request Body

{
  "notes": "Revoked due to policy violation"
}

Request Fields

FieldTypeDescription
notesstringOptional reason for revocation

Response

{
  "grant": {
    "id": "cg_789",
    "merchantId": "merchant_123",
    "customerId": "cust_456",
    "creditDefinitionId": "cd_123",
    "initialAmount": 2000,
    "remainingAmount": 0,
    "status": "REVOKED",
    "applicationType": "usage",
    "scope": "plan",
    "planId": "plan_123",
    "featureId": "feature_api_calls",
    "featureSlug": "api-calls",
    "priceId": null,
    "priceComponentId": null,
    "currency": null,
    "priority": 5,
    "startDate": "2024-01-01T00:00:00Z",
    "expiryDate": "2024-12-31T23:59:59Z",
    "source": "ADMIN_GRANTED",
    "referenceCode": "PROMO_2024",
    "notes": "Promotional credits for Q1 2024 | Revoked: Revoked due to policy violation",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z",
    "deletedAt": null
  }
}

Get Grants for Definition

Get all grants for a specific credit definition.

GET /api/credits/definitions/{definitionId}/grants

Parameters

ParameterTypeDescription
definitionIdstringCredit Definition ID

Response

{
  "grants": [
    {
      "id": "cg_123",
      "merchantId": "merchant_123",
      "customerId": "cust_456",
      "creditDefinitionId": "cd_123",
      "initialAmount": 1000,
      "remainingAmount": 750,
      "status": "ACTIVE",
      "applicationType": "usage",
      "scope": "plan",
      "planId": "plan_123",
      "featureId": "feature_api_calls",
      "featureSlug": "api-calls",
      "priceId": null,
      "priceComponentId": null,
      "currency": null,
      "priority": 1,
      "startDate": "2024-01-01T00:00:00Z",
      "expiryDate": "2024-01-31T23:59:59Z",
      "source": "ADMIN_GRANTED",
      "referenceCode": "WELCOME_BONUS",
      "notes": "Welcome bonus for new customer",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "deletedAt": null
    }
  ]
}

Background Processing (Trigger Endpoints)

These endpoints are used for automated background processing and are typically called by scheduled jobs.

Process Grant Renewals

Process automatic renewals for credit grants based on RRULE configurations.

POST /trigger/credits/process-grant-renewals

Request Body

{
  "timestamp": "2024-01-01T00:00:00Z"
}

Request Fields

FieldTypeRequiredDescription
timestampstring✓Timestamp to process renewals for (ISO 8601)

Response

{
  "success": true,
  "renewalCount": 25,
  "errorCount": 2,
  "timestamp": "2024-01-01T00:00:00Z"
}

Process Credit Expirations

Process credit expirations and mark expired grants as expired.

POST /trigger/credits/process-expirations

Request Body

{
  "timestamp": "2024-01-01T00:00:00Z"
}

Request Fields

FieldTypeRequiredDescription
timestampstring✓Timestamp to process expirations for (ISO 8601)

Response

{
  "success": true,
  "expiredCount": 15,
  "timestamp": "2024-01-01T00:00:00Z"
}

Process Renewal After Invoice

Process credit renewals that are triggered after invoice generation.

POST /trigger/credits/renewal-after-invoice

Request Body

{
  "merchantId": "merchant_123",
  "customerId": "cust_456"
}

Request Fields

FieldTypeRequiredDescription
merchantIdstring✓Merchant ID
customerIdstring✓Customer ID

Response

{
  "success": true,
  "renewalCount": 3,
  "merchantId": "merchant_123",
  "customerId": "cust_456",
  "timestamp": "2024-01-01T00:00:00Z"
}

Examples

Creating Usage Credits for a Feature

curl -X POST /api/credits/definitions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Call Credits",
    "description": "Credits for API usage",
    "scope": "plan",
    "applicationType": "usage",
    "planId": "plan_basic",
    "featureId": "feature_api_calls",
    "featureSlug": "api-calls",
    "defaultAmount": 1000,
    "refillAmount": 1000,
    "expiryDays": 30,
    "refillRrule": "FREQ=MONTHLY;INTERVAL=1",
    "renewOnBilling": true,
    "priority": 1
  }'

Creating Monetary Credits

curl -X POST /api/credits/definitions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Account Credit",
    "description": "Monetary credit for customer account",
    "scope": "merchant",
    "applicationType": "monetary",
    "defaultAmount": 5000,
    "currency": "USD",
    "billingVisible": true,
    "billingDescription": "Account Credit",
    "priority": 10
  }'

Granting Credits to a Customer

curl -X POST /api/credits/grants \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_customer123",
    "creditDefinitionId": "cd_api_credits",
    "initialAmount": 2000,
    "source": "ADMIN_GRANTED",
    "referenceCode": "WELCOME_BONUS",
    "notes": "Welcome bonus for new customer"
  }'

Getting Customer Credit Usage

curl -X GET "/api/credits/customers/cust_customer123/transactions?limit=50&fromDate=2024-01-01T00:00:00Z&toDate=2024-01-31T23:59:59Z" \
  -H "Content-Type: application/json"

Revoking a Credit Grant

curl -X POST /api/credits/grants/cg_grant123/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Credits revoked due to account suspension"
  }'

Data Models

Credit Definition

FieldTypeDescription
idstringUnique credit definition identifier
merchantIdstringMerchant that owns this definition
namestringDisplay name
descriptionstringOptional description
scopestringmerchant or plan
applicationTypestringusage or monetary
planIdstringPlan ID (required for plan-scoped credits)
featureIdstringFeature ID for usage credits
featureSlugstringFeature slug for usage credits
priceIdstringPrice ID for usage credits
priceComponentIdstringPrice component ID for usage credits
defaultAmountnumberDefault amount when granting
refillAmountnumberAmount to refill during renewals
expiryDaysnumberDays until credits expire
refillRrulestringRRULE string for automatic renewals
renewOnBillingbooleanWhether to renew on billing cycle
prioritynumberPriority for credit application
billingVisiblebooleanWhether to show on invoices
billingDescriptionstringDescription for billing
currencystringCurrency code (required for monetary credits)
isActivebooleanWhether definition is active
createdAtstringCreation timestamp
updatedAtstringLast update timestamp
deletedAtstringSoft deletion timestamp

Credit Grant

FieldTypeDescription
idstringUnique credit grant identifier
merchantIdstringMerchant ID
customerIdstringCustomer ID
creditDefinitionIdstringCredit definition ID
initialAmountnumberInitial credit amount
remainingAmountnumberRemaining credit amount
statusstringACTIVE, EXPIRED, REVOKED
applicationTypestringusage or monetary
scopestringmerchant or plan
planIdstringPlan ID (for plan-scoped credits)
featureIdstringFeature ID
featureSlugstringFeature slug
priceIdstringPrice ID
priceComponentIdstringPrice component ID
currencystringCurrency code
prioritynumberPriority for application
startDatestringWhen credits become available
expiryDatestringWhen credits expire
sourcestringGrant source
referenceCodestringReference code
notesstringNotes about the grant
createdAtstringCreation timestamp
updatedAtstringLast update timestamp
deletedAtstringSoft deletion timestamp

Credit Transaction

FieldTypeDescription
idstringUnique transaction identifier
merchantIdstringMerchant ID
customerIdstringCustomer ID
creditGrantIdstringCredit grant ID
amountnumberCredit amount used
applicationTypestringusage or monetary
eventNamestringEvent that triggered usage
eventTimestampstringWhen event occurred
featureIdstringFeature ID
featureSlugstringFeature slug
priceIdstringPrice ID
priceComponentIdstringPrice component ID
currencystringCurrency code
metadataobjectAdditional event metadata
createdAtstringTransaction creation timestamp

Error Responses

400 Bad Request

{
  "error": "Name is required"
}
{
  "error": "Plan-scoped credits require planId"
}
{
  "error": "Usage credits require either price linkage (priceId/priceComponentId) or feature linkage (featureId/featureSlug)"
}
{
  "error": "Monetary credits require currency"
}
{
  "error": "Limit must be less than 1000"
}
{
  "error": "From date must be before to date"
}

404 Not Found

{
  "error": "Credit definition not found"
}
{
  "error": "Credit grant not found"
}

500 Internal Server Error

{
  "error": "Failed to create credit definition"
}
{
  "error": "Failed to create credit grant"
}
{
  "error": "Failed to process grant renewals"
}

Important Notes

Credit Application Priority

Credits are applied in priority order (higher priority first). This allows you to control which credits are used first:

  • Promotional credits (high priority) used before regular credits
  • Expiring credits used before non-expiring credits
  • Feature-specific credits used before general credits

Renewal Mechanisms

Credits support multiple renewal mechanisms:

  1. RRULE-based: Automatic renewals based on recurrence rules
  2. Billing-triggered: Renewals triggered by billing cycle events
  3. Manual: Admin-initiated renewals through API

Monetary vs Usage Credits

Monetary Credits:

  • Applied as discounts on invoices
  • Must be billing-visible
  • Require currency specification
  • Cannot be linked to features

Usage Credits:

  • Applied against feature usage
  • Can be linked to specific features or prices
  • Not necessarily billing-visible
  • Tracked through credit transactions

Soft Deletion

All credit entities use soft deletion to preserve historical data:

  • Credit definitions can be deactivated instead of deleted
  • Credit grants maintain transaction history even when revoked
  • Deleted entities are excluded from active queries

Merchant Isolation

All credit operations are automatically scoped to the authenticated merchant:

  • Credit definitions are merchant-specific
  • Credit grants only apply to customers within the merchant
  • Complete data isolation between merchants

Date Handling

All dates are in ISO 8601 format with UTC timezone:

  • startDate: When credits become available for use
  • expiryDate: When credits expire and become unusable
  • eventTimestamp: When credit usage events occurred

Validation Rules

Credit definitions have complex validation rules based on scope and type:

  • Plan-scoped credits require planId
  • Usage credits require feature or price linkage
  • Monetary credits require currency and must be billing-visible
  • All amounts must be positive integers

UI Components

Lumen provides UI components so you can speed up your SaaS app development.

Customers API

Complete guide to managing customers via the API