Request Body
Human-readable name for the credit grant (e.g., “Welcome Bonus”, “Q1 2024 Credits”)
Scope of the credit grantValues:
PLAN: Credits apply to all subscriptions of a specific planSUBSCRIPTION: Credits apply to a specific subscription
Required if scope is PLAN. The ID of the plan this grant applies to.
Required if scope is SUBSCRIPTION. The ID of the subscription this grant applies to.
Number of credits to grant (must be greater than zero)
How credits are appliedValues:
ONETIME: Credits are applied onceRECURRING: Credits are applied repeatedly based on period
Required if cadence is RECURRING. The recurring period.Values: DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY
Required if cadence is RECURRING. Number of periods for recurring grants (must be > 0)
How credits expireValues:
NEVER: Credits never expireDURATION: Credits expire after a specific durationBILLING_CYCLE: Credits expire at the end of the billing cycle
Required if expiration_type is DURATION. Duration before expiration (must be > 0)
Required if expiration_type is DURATION. Unit for expiration duration.Values: DAYS, WEEKS, MONTHS, YEARS
Required if scope is SUBSCRIPTION. Start date for the credit grant (ISO 8601 format)Not allowed for PLAN-scoped grants.
Optional for SUBSCRIPTION scope. End date for the credit grant (ISO 8601 format)Must be >= start_date if provided. Not allowed for PLAN-scoped grants.
Conversion rate from credits to currency during consumptionExample: If “2”, then 1 credit = 0.5 currency units
Conversion rate for top-ups (e.g., how many credits per currency unit when loading)
Priority for credit consumption (lower number = higher priority)Credits with lower priority numbers are consumed first.
Custom metadata as key-value pairs
Response
Unique identifier for the credit grant
Scope of the grant (PLAN or SUBSCRIPTION)
ID of the plan (if scope is PLAN)
ID of the subscription (if scope is SUBSCRIPTION)
Number of credits granted
Cadence of the grant (ONETIME or RECURRING)
Period for recurring grants
Number of periods for recurring grants
How credits expire (NEVER, DURATION, or BILLING_CYCLE)
Duration before expiration (if expiration_type is DURATION)
Unit for expiration duration
Start date for the grant (subscription-scoped only)
End date for the grant (subscription-scoped only)
Conversion rate from credits to currency
Conversion rate for top-ups
Priority for credit consumption
Timestamp when grant was created
Timestamp when grant was last updated
curl -X POST "https://api.flexprice.io/v1/credit-grants" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Welcome Bonus",
"scope": "SUBSCRIPTION",
"subscription_id": "sub_1234",
"credits": "100.00",
"cadence": "ONETIME",
"expiration_type": "DURATION",
"expiration_duration": 30,
"expiration_duration_unit": "DAYS",
"start_date": "2024-01-15T00:00:00Z",
"conversion_rate": "1",
"priority": 1
}'
{
"id": "cg_abc123xyz",
"name": "Welcome Bonus",
"scope": "SUBSCRIPTION",
"subscription_id": "sub_1234",
"credits": "100.00000000",
"cadence": "ONETIME",
"expiration_type": "DURATION",
"expiration_duration": 30,
"expiration_duration_unit": "DAYS",
"start_date": "2024-01-15T00:00:00Z",
"conversion_rate": "1.00000",
"priority": 1,
"metadata": {},
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z"
}
Credit Grant Scopes
Credits granted at the plan level apply to all subscriptions using that plan.Use cases:
- Included credits in a plan (e.g., “Enterprise plan includes 1000 API calls/month”)
- Plan-level promotions
- Standard credit allotments
Characteristics:
- Automatically applied to new subscriptions
- Cannot specify start/end dates (tied to subscription lifecycle)
- Ideal for recurring credits that are part of the plan definition
Subscription-Scoped Credits
Credits granted to a specific subscription.Use cases:
- One-time promotional credits for a customer
- Compensation credits
- Custom credit agreements
- Trial period bonuses
Characteristics:
- Requires start_date
- Optional end_date for time-limited grants
- Applied only to the specified subscription
- Flexible scheduling and expiration
Expiration Types
NEVER
Credits never expire. Suitable for purchased credits or permanent grants.
DURATION
Credits expire after a specific duration (e.g., 30 days, 6 months).
BILLING_CYCLE
Credits expire at the end of the current billing cycle. Common for monthly allowances.
Recurring Credit Grants
Recurring credit grants automatically apply credits at regular intervals:
For recurring grants, FlexPrice automatically schedules credit applications. You don’t need to manually create credits each period.