Skip to main content
Start selling

Integrate Freemius Billing and Monetization with AI Agent Skills

Freemius AI Agent Skills 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, ChatGPT Codex, Cursor, OpenCode, Command Code, and Antigravity CLI, you can use these skills to integrate Freemius into your product and start monetizing your application in minutes.

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.

  2. Checkout: Integrate a secure checkout for payment processing and upgrade flow.

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

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

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

Installing the Skills​

We distribute and install Freemius AI skills through the standard, agent-agnostic skills.sh platform.

Installation for Claude Code​

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

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

Installation for Codex, Cursor, and Other AI Agents​

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

npx skills add freemius/freemius-ai

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

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.

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​

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

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

  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.

More details about this setup can be found in our documentation.

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.

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

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​

After the agent finishes, test the integration end-to-end and verify that it implemented all the 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​

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​

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​

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

npx skills update -y
On this page: