Credits
Create Credit Definition
Create a new credit definition that configures how credits are granted and applied. Usage credits require feature or price linkage. Monetary credits require currency and must be billing visible. Plan-scoped credits require planId.
Authorization
bearerAuth AuthorizationBearer <token>
Use your secret API key as the bearer token
In: header
Request Body
application/json
name*string
Human-readable name
Length
1 <= lengthdescription?string
scope*string
Value in
"component" | "price" | "plan" | "merchant"applicationType*string
Value in
"usage" | "monetary"planId?string|null
Required for plan-scoped credits
featureId?string|null
featureSlug?string|null
priceId?string|null
priceComponentId?string|null
defaultAmount*integer
Default credit amount
Range
1 <= valuerefillAmount?integer
Range
1 <= valueexpiryDays?integer
Range
1 <= valuerefillRrule?string
renewOnBilling?boolean
billingVisible?boolean
billingDescription?string
currency?string
Required for monetary credits
priority?integer
Response Body
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/credits/definitions" \ -H "Content-Type: application/json" \ -d '{ "name": "API Call Credits", "description": "Monthly API call allowance", "scope": "plan", "applicationType": "usage", "planId": "plan_xyz789abc123def456", "featureSlug": "max-api-calls", "defaultAmount": 10000, "refillAmount": 10000, "expiryDays": 30, "renewOnBilling": true }'{
"definition": {
"id": "string",
"merchantId": "string",
"name": "string",
"description": "string",
"scope": "component",
"applicationType": "usage",
"planId": "string",
"featureId": "string",
"featureSlug": "string",
"priceId": "string",
"priceComponentId": "string",
"defaultAmount": 0,
"refillAmount": 0,
"expiryDays": 0,
"refillRrule": "string",
"renewOnBilling": false,
"billingVisible": false,
"billingDescription": "string",
"currency": "string",
"priority": 0,
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": "2019-08-24T14:15:22Z"
}
}{
"error": "Plan-scoped credits require planId"
}{
"error": "Failed to create credit definition"
}