Skip to main content

​
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 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 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: 
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.

​
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:

Adding entitlements to plans

Credit entitlements in add-ons

Monetize my product using credits