Skip to main content
Start selling

Integrate Freemius Billing and Monetization with OpenCode

In this guide, you will learn how to set up OpenCode to integrate Freemius monetization, checkout, entitlements, and customer portal features into your SaaS product.

Preparation​

  1. Register through the Freemius Developer Dashboard and create a product.
  2. Follow our plans and pricing documentation to configure your plans, prices, and plan features.
  3. Open a terminal in the project that you want OpenCode to update.

If you have not initialized OpenCode for the project, run OpenCode and enter /init. OpenCode will inspect the project and create a top-level AGENTS.md file with project instructions.

Install Freemius Skills​

From the project root, run the following command:

npx skills add freemius/freemius-ai

Select OpenCode and install all the Freemius skills when prompted to get the complete checkout, entitlement, and customer portal workflow.

Set Your Freemius API Key​

On the Settings → API & Keys page, copy the .env file under Usage examples and save it in your project root.

Protect Your API Keys

Never commit the .env file to your repository. Store production credentials in your deployment platform's secrets manager.

Prompt Your First Integration​

Prompt OpenCode with a brief description of how you want to integrate Freemius and gate premium features behind a paywall. For example:

prompt
Integrate Freemius monetization into my software. I want to offer subscriptions with multiple plans for continued access and top-up plans for purchasing additional credits. Use the relevant Freemius skills. The .env file already contains the secrets needed to connect to the Freemius platform. You can query the Freemius API directly with the Freemius JS SDK to find the pricing IDs of the relevant plans. First inspect the existing application and propose an integration plan. After I approve the plan, implement it and run the relevant tests.

OpenCode will use the installed skills and your Freemius product configuration to implement the relevant pricing table, checkout, entitlements, top-up credits, and customer portal features. It may also update the top-level AGENTS.md file with instructions for maintaining the integration.

Plan Before You Prompt

For a complex product setup, use the Tab key to switch OpenCode to the Plan agent. Ask it to inspect the codebase and propose an implementation without editing files. Review the proposed architecture, especially the authentication, entitlement storage, webhook handling, and checkout flow. Then switch to the Build agent and ask OpenCode to implement the approved plan.

Explain whether you sell subscriptions, top-up credits, or both. Also mention whether a user can hold more than one subscription and where premium access must be enforced.

Complete the Dashboard Setup​

After implementing the integration, OpenCode may ask you to configure URLs in the Freemius Developer Dashboard:

  • Go to Settings → Checkout & Redirection to configure the post-checkout redirection URL.
  • Go to Settings → Webhooks to add the webhook endpoint created for your application.

Use the exact URLs and events that OpenCode reports for your implementation.

Test the Integration​

OpenCode should adapt the Freemius integration to your application's existing structure. Verify that it created or updated the following features:

  1. Pricing Table: A pricing experience that displays the plans, prices, billing cycles, and features configured for your Freemius product.

  2. Checkout: A purchase flow that opens Freemius Checkout with the selected plan and returns the user to your application after a successful purchase.

  3. Entitlements and Paywalls: Backend and frontend checks that protect premium features, show a paywall to users without access, and grant access after the appropriate entitlement is received.

  4. Account Page and Customer Portal: An added or updated account area that displays relevant subscription or purchase information and gives users access to the Freemius Customer Portal.

Test these features with users who have and do not have active entitlements. Also verify that checkout redirection and webhook events update access and account information correctly.

Troubleshooting and Updates​

If the integration does not work as expected, describe the observed and expected behavior and ask OpenCode to use the freemius-troubleshooting skill. Before troubleshooting, update the installed skills:

npx skills update -y

For more information, examples, and best practices, see the Freemius Skills documentation.

On this page: