# Integrate Freemius Billing and Monetization with AI Agent Skills

Freemius AI [Agent Skills](https://agentskills.io/home) are a set of instructions that can be used by AI agents to understand how to integrate Freemius into your SaaS product, use its various features, and leverage it to monetize your application.

If you are using any AI coding agents, assistants, or harnesses, such as [Claude Code](https://claude.com/product/claude-code), [ChatGPT Codex](https://chatgpt.com/codex/), [Cursor](https://cursor.com/), [OpenCode](https://opencode.ai/), [Command Code](https://commandcode.ai/), and [Antigravity CLI](https://antigravity.google/product/antigravity-cli), you can use these skills to integrate Freemius into your product and start monetizing your application in minutes.

## Included Features[​](#included-features "Direct link to Included Features")

The skills are designed to make it easy to integrate Freemius monetization, checkout, entitlement, and customer portal features into your product. Once integrated successfully, your product gets the following capabilities out of the box:

1. **Pricing Table**: Render rich pricing tables for processing subscriptions as well as one-time purchases.

   ![Freemius pricing table with subscription and one-time purchase options](/help/assets/ideal-img/freemius-pricing-table.6c69dbd.480.png)

2. **Checkout**: Integrate a secure [checkout](https://freemius.com/help/help/documentation/checkout/.md) for payment processing and upgrade flow.

   ![Freemius checkout flow for subscription purchase](/help/assets/ideal-img/freemius-checkout.3ede917.480.png)

3. **Entitlements**: Gate premium features behind a paywall and manage entitlements for your users from both the backend and frontend.

   ![Application paywall UI for controlling premium feature access](/help/assets/ideal-img/freemius-paywall-ui.4f8ba0f.480.png)

4. **Customer Portal**: Allow your users to manage their subscriptions and billing information, view their purchases and payments, and upgrade or cancel their subscriptions.

   ![Integrated customer portal for subscription and billing management](/help/assets/ideal-img/freemius-integrated-customer-portal.6e7c546.480.png)

The only requirement is that your backend is JavaScript-based, such as Node.js, Deno, or Bun.

## Installing the Skills[​](#installing-the-skills "Direct link to Installing the Skills")

We distribute and install Freemius AI skills through the standard, agent-agnostic [skills.sh](https://www.skills.sh/) platform.

### Installation for Claude Code[​](#installation-for-claude-code "Direct link to Installation for Claude Code")

Since Claude Code does not support the native `.agents` directory, run the following command to install specifically for Claude Code:

* npm
* Yarn
* pnpm
* Bun

```
npx skills add freemius/freemius-ai -a claude-code
```

```
yarn dlx skills add freemius/freemius-ai -a claude-code
```

```
pnpm dlx skills add freemius/freemius-ai -a claude-code
```

```
bun x skills add freemius/freemius-ai -a claude-code
```

### Installation for Codex, Cursor, and Other AI Agents[​](#installation-for-codex-cursor-and-other-ai-agents "Direct link to Installation for Codex, Cursor, and Other AI Agents")

For ChatGPT Codex, Cursor, OpenCode, Command Code, Antigravity CLI, and other supported AI coding agents, run:

* npm
* Yarn
* pnpm
* Bun

```
npx skills add freemius/freemius-ai
```

```
yarn dlx skills add freemius/freemius-ai
```

```
pnpm dlx skills add freemius/freemius-ai
```

```
bun x skills add freemius/freemius-ai
```

This works out of the box for most AI coding agents.

![skills.sh CLI prompt for selecting an AI coding agent during Freemius skills installation](/help/assets/ideal-img/freemius-ai-skills-installation.5c9eb1f.480.png)

Just be sure to pick your agent from the list when it asks.

Open Source

The skills are open source and can be found on our [GitHub repository](https://github.com/Freemius/freemius-ai).

Freemius AI includes four skills aimed at complete end-to-end SaaS integration, covering monetization, checkout, entitlements, and customer portal workflows. Install all of them to get the full integration experience.

## Setting Up Freemius Plans[​](#setting-up-freemius-plans "Direct link to Setting Up Freemius Plans")

The skills ask the agent to read your Freemius product configuration and integrate based on it. For example, you might be selling only subscriptions or a combination of subscriptions and top-up credits.

So before running the skills, make sure you have your plans and pricing set up following our [documentation](https://freemius.com/help/help/documentation/saas/saas-plans-pricing/.md). For the rest of the documentation, we will assume that:

1. You are selling subscriptions for continued access to your product through multiple plans, supporting only one subscription per user.

   ![Freemius subscription plans configured for a SaaS product](/help/assets/ideal-img/freemius-subscription-plans.0c07d75.480.png)

2. **All plans have a defined feature list that the AI can use for entitlements**.

   ![Freemius subscription plan features configured for a SaaS product](/help/assets/ideal-img/freemius-plan-features.df4eadf.480.png)

3. You have a top-up plan for one time purchases of credits which can be used as balance for metered features or actions in your product.

   ![Freemius top-up credit pricing for one-time purchases](/help/assets/ideal-img/freemius-topup-pricing.efbfea8.480.png)

More details about this setup can be found in our [documentation](https://freemius.com/help/help/documentation/saas/usage-based-billing-credits/.md).

Once you've set up your plans and pricing, go to the **Settings** → **API & Keys** and copy the `.env` file under the **Usage examples** and save it in your project root.

![Freemius API and keys page showing the generated environment file](/help/assets/ideal-img/freemius-env-file.aeb19fb.480.png)

## Integration Prompts[​](#integration-prompts "Direct link to Integration Prompts")

Now prompt your AI agent with a brief description of how you want to integrate Freemius into your product and gate premium features behind a paywall. For example, you can use the following prompt:

prompt

```
Integrate Freemius monetization in my software. I want to offer subscription with various plans for continued access and top up plans for purchasing additional credits. Use the relevant Freemius skils. The env file already has the secrets needed to connect with the Freemius platform. You can query the Freemius API directly with the Freemius JS SDK to figure out the pricing ID of relevant plans.
```

The agent will use the skills and fetch your Freemius plans to integrate checkout, entitlements, and customer portal features into your product. It will also add the relevant code to your backend to handle entitlements and top-up credits.

We recommend explaining the product setup to the agent upfront to avoid confusion. For example, if you are selling only subscriptions with multiple plans, you can use the following prompt:

prompt

```
Integrate Freemius monetization in my software. I want to offer subscriptions with multiple plans. Use the relevant Freemius skils. The env file already has the secrets needed to connect with the Freemius platform. You can query the Freemius API directly with the Freemius JS SDK to figure out the pricing ID of relevant plans.
```

Similarly if you are selling only top-up credits, you can use the following prompt:

prompt

```
Integrate Freemius monetization in my software. I want to offer top-up plans for purchasing additional credits. Use the relevant Freemius skils. The env file already has the secrets needed to connect with the Freemius platform. You can query the Freemius API directly with the Freemius JS SDK to figure out the pricing ID of relevant plans.
```

Once the integration is complete, you should see the [features](#included-features) implemented based on your product setup and plans. The agent will also add or update the top-level `AGENTS.md` file with relevant instructions for future reference and for maintaining premium entitlement and paywall logic.

## Setting Up the Checkout Redirection and Webhooks[​](#setting-up-the-checkout-redirection-and-webhooks "Direct link to Setting Up the Checkout Redirection and Webhooks")

Once the agent has integrated Freemius, it may ask you to set up checkout redirection and webhooks. You can do this by going to **Settings** → **Checkout & Redirection** and **Settings** → **Webhooks** in your Freemius product dashboard. The agent will show detailed instructions on how to do this.

## Test the Integration[​](#test-the-integration "Direct link to Test the Integration")

After the agent finishes, test the integration end-to-end and verify that it implemented all the [included features](#included-features) that apply to your product setup.

1. **Pricing Table**: The agent should have added or updated a pricing page that displays the plans, prices, billing cycles, and features configured for your Freemius product. If your product offers top-up credits, verify that the relevant one-time purchase options also appear.
2. **Checkout**: Starting a purchase from the pricing page should open Freemius Checkout with the correct plan and pricing selection. Complete a test purchase and confirm that the checkout redirection returns the user to your application.
3. **Entitlements and Paywalls**: The agent should have added the backend and frontend logic required to protect premium features. Verify that a user without the required entitlement sees the appropriate paywall and cannot bypass it by calling a protected backend route directly. After a successful purchase, confirm that the user receives access to the purchased features.
4. **Account Page and Customer Portal**: Based on your application's structure, the agent should have added or updated an account page to show relevant subscription, purchase, payment, or credit information. It should also provide access to the Freemius Customer Portal so users can manage their billing details and subscriptions.

Finally, verify that webhook events update entitlements and account information correctly when a subscription is created, renewed, changed, canceled, or expired. The exact pages, components, and routes may differ depending on your application's framework and architecture.

## Best Practices[​](#best-practices "Direct link to Best Practices")

When prompting your AI agent, we recommend the following best practices:

* **Mention Freemius Skills**: Ask the agent to "use the relevant Freemius skills" to ensure it uses the correct skills for the integration.
* **Specify the Monetization Model**: Clearly state the monetization model you want to implement (e.g., subscriptions, top-up credits, or both). This avoids confusion and helps the agent select the correct skills.
* **Use Plan Mode**: For complex product setups, ask the agent to "plan the integration" first. You can then review the plan and ask the agent to implement the integration based on it.
* **Mention the `.env` File**: Tell the agent that the `.env` file already contains the secrets required to connect to the Freemius platform. This helps the agent use the Freemius JS SDK to query the pricing IDs of the relevant plans.
* **Protect the `.env` File**: Never commit the `.env` file to your repository because it contains sensitive information that should not be shared publicly. Use environment variables or a secure secrets management system to store and access API keys and other sensitive information.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

If something is not working as expected, you can use the `freemius-troubleshooting` skill to help the agent identify and fix the issue. Explain the problem to the agent and ask it to use the troubleshooting skill. For example, you can use the following prompt:

prompt

```
Users are not getting access after a successful Checkout. Troubleshoot the Freemius integration in my software.
```

## Updating the Skills[​](#updating-the-skills "Direct link to Updating the Skills")

Before troubleshooting, we recommend updating the skills to the latest version by running the following command in your terminal.

* npm
* Yarn
* pnpm
* Bun

```
npx skills update -y
```

```
yarn dlx skills update -y
```

```
pnpm dlx skills update -y
```

```
bun x skills update -y
```