> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaloops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up token billing for AI and app usage

> Sell token packages, define usage triggers for AI features, and manage SDK API keys for metered billing in your Instaloops community.

<Note>
  Only community owners and admins with **Manage settings** permission can access this tab.
</Note>

Token Billing lets you sell token packages to members and charge tokens when they use AI-powered or integrated app features. You define how many tokens each action costs, set package prices, and manage API keys for SDK integrations.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/supacoder/images/community-settings/token-billing.png" alt="Token Billing tab showing packages, triggers, and API keys sections" />
</Frame>

## View usage at a glance

The dashboard shows four stats for the last 30 days:

* **Consumed**: total tokens used by members
* **Granted**: tokens added through purchases or subscriptions
* **Overage**: extra tokens used beyond included balances
* **Active Balances**: members with a current token balance

## Create a token package

<Steps>
  <Step>
    Open **Settings** and select **Token Billing**.
  </Step>

  <Step>
    In the **Token Packages** section, click **New Package**.
  </Step>

  <Step>
    Fill in the form:
  </Step>
</Steps>

* **Product**: select an existing product from the Products tab (required)
* **Package Name**: for example, Starter Pack
* **Billing Model**: Prepaid (one-time) or Subscription (recurring)
* **Tokens Included**: number of tokens the buyer receives
* **Price**: cost in dollars
* **Renewal**: for subscriptions, choose Monthly or Yearly

For subscription packages, you can also enable **metered overage** and set a per-token overage price.

<Note>
  You must create at least one product in the Products tab before you can create a token package.
</Note>

## Define usage triggers

Triggers decide how many tokens an app feature costs each time it runs.

<Steps>
  <Step>
    In the **Usage Triggers** section, click **New Trigger**.
  </Step>

  <Step>
    Select the **App** this trigger applies to.
  </Step>

  <Step>
    Enter a **Display Name** (for example, AI Generation).
  </Step>

  <Step>
    Set a **Slug** (for example, `ai_generation`).
  </Step>

  <Step>
    Enter the **Token Cost** per call.
  </Step>

  <Step>
    Click **Create Trigger**.
  </Step>
</Steps>

<Note>
  You must register apps in the Apps tab before you can create triggers.
</Note>

## Manage SDK API keys

API keys let external apps authenticate and consume tokens on behalf of your community.

<Steps>
  <Step>
    In the **SDK API Keys** section, click **New API Key**.
  </Step>

  <Step>
    Enter a **Key Name** (for example, Production Key).
  </Step>

  <Step>
    Optionally restrict the key to a single **App** scope.
  </Step>

  <Step>
    Click **Create Key**.
  </Step>

  <Step>
    Copy the key immediately. It is shown only once.
  </Step>
</Steps>

Click the trash icon next to a key to revoke it. Revoked keys lose access immediately.

## SDK integration quick reference

* **Install**: `npm install @instapay/sdk`
* **Server-side**: use an API key (`il_live_...`) for backend apps
* **Client-side**: request a session token via `POST /api/v1/auth/session`
* **Consume tokens**: call `POST /api/v1/consume` with the trigger slug and app ID

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What happens when a member runs out of tokens?">
    If the member has no remaining balance, the app action is blocked. You can set a purchase or upgrade link on the product so members are redirected to buy more tokens.
  </Accordion>

  <Accordion title="Can I change the token cost of a trigger later?">
    Yes. Edit the trigger and update the Token Cost. The new cost applies to future calls immediately. Past consumption is not retroactively adjusted.
  </Accordion>

  <Accordion title="What is the difference between prepaid and subscription token packages?">
    Prepaid packages grant tokens once at purchase. Subscription packages grant a fresh batch of tokens on each renewal and can optionally charge overage fees for extra usage beyond the included amount.
  </Accordion>

  <Accordion title="Can I scope an API key to multiple apps?">
    No. Each key can either be community-wide or restricted to a single app. If you need access for multiple apps, create one key per app.
  </Accordion>

  <Accordion title="Do archived packages stop existing balances from working?">
    No. Archiving a package only prevents new purchases. Members who already bought the package keep their remaining tokens and can continue using them.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="New Package button is disabled">
    You need at least one product in the Products tab. Create a product first, then return to Token Billing. The button will become active.
  </Accordion>

  <Accordion title="API key is rejected by the SDK">
    Make sure you copied the full key including the `il_live_` prefix. If you lost it, revoke the old key and create a new one. Keys are only displayed once at creation.
  </Accordion>

  <Accordion title="Trigger is not deducting tokens">
    Verify the trigger slug matches exactly what your app sends in the consume call. Check that the app is registered and the trigger is tied to the correct app ID. Review the 30-day analytics to see if consumption is being recorded.
  </Accordion>

  <Accordion title="Overage charges are not appearing in Stripe">
    Metered overage only works for subscription packages. Make sure overage is enabled on the package and a per-token overage price is set. It may take a billing cycle for Stripe to invoice the overage.
  </Accordion>
</AccordionGroup>

## Related

* [Products](/monetization/products)
* [Pricing](/monetization/pricing)