List Credit Grants

Retrieve a list of credit grants with optional filtering by scope, plan, or subscription.

GET /v1/credit-grants

cURL - List all credit grants

curl -X GET "https://api.flexprice.io/v1/credit-grants?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "data": [
    {
      "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": {
        "campaign": "new_user_2024"
      },
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "cg_def456uvw",
      "name": "Monthly Plan Credits",
      "scope": "PLAN",
      "plan_id": "plan_enterprise",
      "credits": "500.00000000",
      "cadence": "RECURRING",
      "period": "MONTHLY",
      "period_count": 12,
      "expiration_type": "BILLING_CYCLE",
      "conversion_rate": "1.00000",
      "metadata": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Query Parameters

scope · string

Filter by scope

Values: PLAN, SUBSCRIPTION

plan_id · string

Filter by plan ID (only returns PLAN-scoped grants)

subscription_id · string

Filter by subscription ID (only returns SUBSCRIPTION-scoped grants)

cadence · string

Filter by cadence

Values: ONETIME, RECURRING

expiration_type · string

Filter by expiration type

Values: NEVER, DURATION, BILLING_CYCLE

limit · integer · default: "10"

Number of credit grants to return per page (max 100)

offset · integer · default: "0"

Number of credit grants to skip for pagination

sort_by · string · default: "created_at"

Field to sort by

Values: created_at, updated_at, name, credits

sort_order · string · default: "desc"

Sort order

Values: asc, desc

Response

data · array

Array of credit grant objects

Show Credit grant object

id · string

Unique identifier for the credit grant

name · string

Name of the credit grant

scope · string

Scope of the grant (PLAN or SUBSCRIPTION)

plan_id · string

ID of the plan (if scope is PLAN)

subscription_id · string

ID of the subscription (if scope is SUBSCRIPTION)

credits · string

Number of credits granted

cadence · string

Cadence of the grant (ONETIME or RECURRING)

period · string

Period for recurring grants (DAILY, WEEKLY, MONTHLY, etc.)

period_count · integer

Number of periods for recurring grants

expiration_type · string

How credits expire (NEVER, DURATION, or BILLING_CYCLE)

expiration_duration · integer

Duration before expiration (if expiration_type is DURATION)

expiration_duration_unit · string

Unit for expiration duration (DAYS, WEEKS, MONTHS, YEARS)

start_date · string

Start date for the grant (subscription-scoped only)

end_date · string

End date for the grant (subscription-scoped only)

conversion_rate · string

Conversion rate from credits to currency

topup_conversion_rate · string

Conversion rate for top-ups

priority · integer

Priority for credit consumption

metadata · object

Custom metadata

created_at · string

Timestamp when grant was created

updated_at · string

Timestamp when grant was last updated

total · integer

Total number of credit grants matching the filter criteria

limit · integer

Number of credit grants returned per page

offset · integer

Number of credit grants skipped

cURL - List all credit grants

curl -X GET "https://api.flexprice.io/v1/credit-grants?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "data": [
    {
      "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": {
        "campaign": "new_user_2024"
      },
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "cg_def456uvw",
      "name": "Monthly Plan Credits",
      "scope": "PLAN",
      "plan_id": "plan_enterprise",
      "credits": "500.00000000",
      "cadence": "RECURRING",
      "period": "MONTHLY",
      "period_count": 12,
      "expiration_type": "BILLING_CYCLE",
      "conversion_rate": "1.00000",
      "metadata": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Common Filtering Patterns

View All Credits for a Customer

To see all credits available to a customer, you need to query both:

1. Plan-scoped grants for any active subscriptions
2. Subscription-scoped grants for their specific subscriptions

# Get customer's subscriptions
subscriptions = client.subscriptions.list(customer_id="cust_123")

# Get subscription-scoped grants
for sub in subscriptions.data:
    grants = client.credit_grants.list(subscription_id=sub.id)
    
# Get plan-scoped grants
for sub in subscriptions.data:
    grants = client.credit_grants.list(
        scope="PLAN",
        plan_id=sub.plan_id
    )

Audit Recurring Credits

List all recurring credit grants to understand ongoing commitments:

curl -X GET "https://api.flexprice.io/v1/credit-grants?cadence=RECURRING" \
  -H "Authorization: Bearer YOUR_API_KEY"

Find Expiring Credits

While the list endpoint doesn’t directly filter by expiration date, you can:

1. List all grants with expiration_type=DURATION
2. Filter by application date ranges in your application logic
3. Use the credit grant applications endpoint for scheduled credits