> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Grant credits as entitlements in plans and add-ons
## Overview
This guide explains how to include recurring credit grants directly in your plans and add-ons as entitlements. This lets you offer "included credits" as part of a base subscription (e.g., "5,000 AI credits per month on the Pro Plan") or sell additional credit capacity via add-ons (e.g., "Extra 10,000 API credits per month").
Credits granted through plan or add-on entitlements are automatically issued and reset each billing period, without manual intervention or separate billing charges.
## Use cases
* **Base plan with included credits**: A Pro plan that includes 5,000 AI credits per month, alongside a recurring base charge.
* **Free plan with credits**: A free-tier plan that grants 500 AI credits per month at no charge.
* **Add-on credit booster**: An "Extra Credits" add-on that grants an additional 10,000 credits per month on top of the base plan.
* **Annual plan with yearly credit grant**: An annual plan that grants 60,000 credits per year (equivalent to 5,000/month), granted upfront.
## Step 1: Create a credit type
A credit type is the custom currency used to track credit grants and consumption. Skip this step if a credit type already exists.
1. Go to **Product Catalog → Credits**.
2. Click **Create credit type**.
3. Enter a **Name** (e.g., *AI Credits*) and set unit labels (e.g., *credit* / *credits*).
4. Save.
## Step 2: Map credit consumption (optional)
Define which metered features consume credits and at what rate. This is required for tracking usage against the credit grant.
1. In your plan's pricing section, go to **Credit consumption**.
2. Click **+ Add**.
3. Select the metered feature (e.g., *AI Image Generation*).
4. Define the conversion rate (e.g., `1 image = 10 AI Credits`).
5. Click **Add** for each feature mapping.
Only **event-based meters** are currently supported for credit consumption mapping. Credit consumption configuration is shared across the plan's entitlements and billing charges.
## Step 3: Add a credit entitlement to a plan
1. Open the plan in **Product Catalog → Plans**.
2. In the **Entitlements** section, click **+ Add**.
3. Select the credit type from the list (e.g., *AI Credits*).
4. Enter the **grant amount** (e.g., `5000`).
5. Select the **cadence**: **Monthly** or **Yearly**.
6. Click **Add** to confirm.
The credit entitlement now appears in the plan's entitlement list alongside feature entitlements.
## Step 4: Add a credit entitlement to an add-on (optional)
Use this step if you want to sell additional credit capacity as an add-on.
1. Open the add-on in **Product Catalog → Add-ons**.
2. In the **Entitlements** section, click **+ Add**.
3. Select the credit type from the list.
4. Enter the **grant amount** and **cadence**.
5. (Optional) Set the **Entitlement behavior**:
* **Increment plan limit** *(default)*: The add-on credits are added to the base plan's credit grant.
* **Override plan limit**: The add-on replaces the base plan's credit grant.
6. Click **Add** to confirm.
See [Credit entitlements in add-ons](../../documentation/modeling-your-pricing-in-stigg/add-ons/assigning-features-to-add-ons/credits) for full details.
## Step 5: Publish the plan or add-on
Click **Publish** to make the changes available for new and migrated subscriptions.
Publishing a plan creates a new version. Existing subscriptions are not automatically updated. Use [plan migration](../../documentation/modeling-your-pricing-in-stigg/plans/migrating-plans) to roll out changes to existing subscribers.
## Step 6: Subscribe a customer
Once the plan is published, subscribe a customer to it:
1. Go to **Customers → \[Customer] → Create subscription**.
2. Select the product and the plan.
3. Click **Create Subscription**.
Credits are automatically granted to the customer based on the configured cadence.
## Checking credit entitlements via the SDK
After a customer subscribes, use `getCreditEntitlement()` to check their current credit balance in real time:
```typescript theme={null}
const creditEntitlement = await stiggClient.getCreditEntitlement({
customerId: 'customer-123',
currencyId: 'currency-ai-credits',
});
if (creditEntitlement.remaining > 0) {
// Customer has credits — proceed with the action
console.log('Remaining credits:', creditEntitlement.remaining);
} else {
// No credits remaining — deny or prompt for top-up
}
```
The balance reflects all active grants from plan entitlements, add-on entitlements, manual top-ups, and promotional credits, minus total consumption.
## Example: "Extra API Credits" add-on
**Scenario**: Your Pro plan includes 50,000 API credits per month. You want to let customers purchase additional credit capacity without upgrading their plan.
**Setup**:
1. Create an add-on named *Extra API Credits* with **Multiple instance** type.
2. Add a credit entitlement:
* **Credit type**: API Credits
* **Amount**: 10,000
* **Cadence**: Monthly
3. Set the add-on price (e.g., \$49/month per unit) and publish.
**Result**: A customer on the Pro plan who purchases 3 units of the *Extra API Credits* add-on receives:
* 50,000 credits/month from the plan entitlement
* 30,000 credits/month from the add-on (10,000 × 3)
* **80,000 API credits per month in total**
Credits from the plan and add-on are pooled together and consumed in the order defined by your [credit consumption logic](../../documentation/modeling-your-pricing-in-stigg/credits/credit-consumption-logic).
## Visibility in the Stigg app
Once a customer is subscribed to a plan with credit entitlements:
* **Entitlement Summary**: The credit grant appears alongside other entitlements, showing the amount and cadence.
* **Entitlement Usage**: Shows current credit utilization with a link to the Credits tab for a detailed breakdown.
* **Credits tab**: Displays a breakdown of all active grants, differentiating between plan grants, add-on grants, and manual top-ups.
Also see: