# Bolt Integration Guide with Freemius Follow this guide to integrate Freemius Checkout and monetization into your apps and SaaS built on [Bolt.new](https://bolt.new/) with a single prompt to your AI agent. The end result is: * **Integrated Pricing Page and Checkout**: Your users will see the pricing you've configured at Freemius and be able to purchase your product through the Freemius checkout. ![Pricing page](/help/assets/ideal-img/pricing-page-example.854a9a8.480.png) * **Gated Premium Features**: You can easily gate your premium features behind a paywall and allow access only to users who have purchased the product. ![Paywall UI](/help/assets/ideal-img/paywall-ui.eaa5085.480.png) * **Integrated Accounts Page**: Show active subscriptions and payments directly within your app, and link to the Freemius Customer Portal for more advanced account management features. ![Accounts page](/help/assets/ideal-img/accounts-page.5b38634.480.png) Continue reading to learn how to achieve this with a single prompt to Bolt.new's AI agent. ## Set Up Your Product at Freemius[​](#set-up-your-product-at-freemius "Direct link to Set Up Your Product at Freemius") If you haven't already, register and [create your product and plans](https://freemius.com/help/help/documentation/saas/saas-plans-pricing/.md) at Freemius. For this guide, create a few subscription-based plans, as shown below: ![Setup plans in the Freemius Developer Dashboard](/help/assets/ideal-img/freemius-plans-example.149ddda.480.png) All plans have monthly and annual billing cycles with different pricing and features, as shown below: ![Setup pricing and features](/help/assets/ideal-img/freemius-pricing-example.694acee.480.png) ## Save Your Project Secrets[​](#save-your-project-secrets "Direct link to Save Your Project Secrets") First, get your API keys from the Freemius Developer Dashboard. Go to **Product** → **Settings** and, under the **API & Keys** tab, copy your API keys as shown below: ![API Keys](/help/assets/ideal-img/freemius-api-key.cd464f6.480.png) 1. **Product ID**: This will be referenced as `FREEMIUS_PRODUCT_ID`. 2. **Product Public Key**: This will be referenced as `FREEMIUS_PUBLIC_KEY`. 3. **Product Secret Key**: This will be referenced as `FREEMIUS_SECRET_KEY`. 4. **API Bearer Authorization Token**: This will be referenced as `FREEMIUS_API_KEY`. Next, get your Bolt.new app URL. This will be referenced as `LIVE_FRONTEND_URL` as a secret. To get this link, publish your app by clicking the **Publish** button in the top-right corner to get the production URL, then copy it as shown below: ![Publish Bolt.new app to get production URL](/help/assets/ideal-img/bolt-production-url.2f171fa.480.png) While editing your Bolt.new project, add the keys to the **Secrets** manager under the Settings. 1. Click the **Settings** button from the center view. ![Bolt.new project secret keys settings](/help/assets/ideal-img/bolt-ai-save-secret-keys.ceffd52.480.png) 2. Manually add each key and its value, then click the **Create secret** button. ![Bolt.new project secret keys settings saved](/help/assets/ideal-img/bolt-secrets.d54eeb3.480.png) ## Update Bolt.new Knowledge[​](#update-boltnew-knowledge "Direct link to Update Bolt.new Knowledge") Add custom instructions to Bolt.new's Knowledge Base so the AI agent knows how to integrate Freemius into your application. 1. Click **Knowledge** under the Settings button. 2. Copy and paste the following instructions into the textarea. ``` ## Freemius Monetization Integrate Freemius end-to-end in this Bolt app using Supabase functions, shared backend utilities, and frontend paywall/account UX. ### Integration Guidelines When asked to integrate Freemius, follow the instructions from this URL: https://raw.githubusercontent.com/Freemius/freemius-ai/refs/heads/main/bolt-integration/subscription/prompt.md ### Protect Premium Features with Paywall - To restrict any premium operations in the API routes that require an active subscription, use the shared `supabase/functions/_shared/freemius.ts` module's `getUserEntitlement` (for any plan) or `hasPlan` (specific plan) functions. Return a 403 response with `code: "subscription_required"` if the user doesn't have the required subscription. - On the frontend, handle the `subscription_required` error by reading the response body from `error.context.body` as a stream (since Supabase `functions.invoke` puts non-2xx response bodies there as a ReadableStream, not plain JSON). Show a lock-style paywall UI with a link to `/pricing`. You can disable relevant UI after the first failed attempt. - The front-end may also call the `functions/v1/get-entitlements` API route to check for active entitlements and show a paywall UI with a link to `/pricing` through a `Subscribe` button if there is no active subscription. - The front-end may also call the `functions/v1/get-entitlements` API route to check for active entitlements and show a paywall UI with a link to `/pricing` through a `Subscribe` button if there is no active subscription. - Correctly find the matching user and write the entitlement record. The getUserByEmail should read the correct field, `purchase.email`, to skip the silently returned null for every purchase. - The SDK's `freemius.entitlement.getActive()` throws a hard error if more than one active entitlement is found. With a real account that has been through multiple subscription cycles, switch to `freemius.entitlement.getActives()` (which returns an array) and then pick the most recently created one. --- ``` 3. Click the **Save prompt** button. ![Updating Bolt.new knowledgebase with Freemius instructions](/help/assets/ideal-img/bolt-knowledge.fc62815.480.png) ## Do the Integration[​](#do-the-integration "Direct link to Do the Integration") Return to the Bolt.new editor and enter the following prompt: prompt ``` Implement the Freemius integration based on the project's Knowledge saved. ``` The AI agent will start working on the integration. Here's what will happen: 1. The agent might ask you to enable the Bolt.new Database or to connect your Supabase project. 2. The agent will ask you to create a new database table named `user_fs_entitlement`—accept this. 3. Because the integration instructions are comprehensive, the agent will work through several steps. Once complete, it will output two URLs: one for checkout redirection and one for webhooks. ![Webhook and Checkout URLs](/help/assets/ideal-img/bolt-webhook-checkout-redirection-url.07694e2.480.png) ### Set Up Checkout Redirection[​](#set-up-checkout-redirection "Direct link to Set Up Checkout Redirection") Go to **Plans** → **Customize** and set the **Checkout Success Redirection** that the AI agent gave you. ![Checkout Redirection](/help/assets/ideal-img/freemius-checkout-redirection-url.7a7904f.480.png) This ensures the purchase is processed immediately by your app and users get instant access to benefits. Learn more in our [documentation](https://freemius.com/help/help/documentation/checkout/integration/hosted-checkout/.md#redirection-after-a-successful-purchase). ### Set Up Webhooks[​](#set-up-webhooks "Direct link to Set Up Webhooks") Go to **Products** → **Webhooks** → **Listeners** and add the webhook URL that the AI agent gave you. ![Add new webhook](/help/assets/ideal-img/freemius-new-webhook.854409d.480.png) Make sure to send the following event types: * license.cancelled * license.created * license.deleted * license.expired * license.extended * license.plan.changed * license.quota.changed * license.shortened * license.updated This ensures your application knows the status of a license. For example, when a subscription is renewed, your application will also update the expiry date. For more information about webhooks, see our [documentation](https://freemius.com/help/help/documentation/saas/events-webhooks/.md). For now, creating the webhook listener with the URL and event types is sufficient for the integration to work. ## Test the Integration[​](#test-the-integration "Direct link to Test the Integration") Test the integration end-to-end to ensure everything works as expected. 1. You should now see a new **Subscribe** button in the app's navbar. ![Subscribe Button](/help/assets/ideal-img/navbar-subscribe-button.5c79e98.480.png) 2. Clicking the action button in the paywall will take you to the pricing page, which can look like this: ![Pricing Page](/help/assets/ideal-img/pricing-page-example.854a9a8.480.png) **It will fetch all the plans, pricing, and features you have configured in Freemius in real time.** 3. Click the **Subscribe** button on any plan to test it further. This takes you to the Freemius Checkout page. ![Freemius Checkout](/help/assets/ideal-img/checkout.8c2ab6c.480.png) For this step, use a [100% discount coupon](https://freemius.com/help/help/documentation/selling-with-freemius/coupon-discount/.md) to test the checkout without making a production payment. 4. After checkout completes, you'll see a confirmation that the payment was successful and be redirected back to the app. ![Payment Successful UI](/help/assets/ideal-img/payment-successful.be674f1.480.png) The app should now show that you're subscribed and have access to premium features. 5. The AI should have added or enhanced the `/accounts` page, similar to this: ![Accounts page](/help/assets/ideal-img/accounts-page.5b38634.480.png) 6. Click the **Update Subscription** button to go to the pricing page. This time, your current plan is highlighted, and the other plans are shown as upgrade or downgrade options. ![Pricing Table](/help/assets/ideal-img/pricing-table.2cb5e0e.480.png) 7. To further test, click the **Cancel Subscription** button on the accounts page. You'll see the app cancel the subscription with Freemius, and the UI will update accordingly. ![Accounts page with no subscription](/help/assets/ideal-img/accounts-page-no-subscription.e63a88d.480.png) 8. Click **Manage Billing** to access the Freemius Customer Portal, where you can test other features such as changing plans or updating payment methods. ![Freemius Customer Portal](/help/assets/ideal-img/freemius-customer-portal.b9a1f22.480.png) If all steps work as expected, you have successfully integrated Freemius monetization with your Bolt.new app. You can also customize the UI further to match your app's design and branding. ## Protect Features with Paywall[​](#protect-features-with-paywall "Direct link to Protect Features with Paywall") In your **Knowledge** settings, Bolt.new is already configured with instructions for maintaining the Freemius integration and paywall. You only need to tell the AI which UI elements and API routes to protect. For example, to protect the meme generator feature on both the backend and frontend, use this prompt: prompt ``` Add a paywall to the meme generation feature. Use guide from knowledgebase to protect the API route with `getUserEntitlement` and show a lock-style paywall UI with a link to `/pricing` on the frontend if the user doesn't have any active subscription. Disable the generate button after the first failed attempt. ``` The end result will look like this: ![Paywall UI](/help/assets/ideal-img/paywall-ui.eaa5085.480.png) To restrict a feature to a specific plan only—for example, Pro plan users for the meme generator—use `hasPlan` instead of `getUserEntitlement` like this: prompt ``` Add a paywall to the meme generation feature. Use guide from knowledgebase to protect the API route with `hasPlan` for the `` and show a lock-style paywall UI with a link to `/pricing` on the frontend if the user doesn't have an active Pro subscription. Disable the generate button after the first failed attempt. ``` ### Customize for Your Feature[​](#customize-for-your-feature "Direct link to Customize for Your Feature") Customize the prompt for your use case by specifying which UI elements and API routes to protect. The **meme generator** is just an example. Additionally, if you're using the `hasPlan` function, you can find the `` from the Freemius Developer Dashboard under your product's plans, as shown below: ![Find plan ID from Freemius Developer Dashboard](/help/assets/ideal-img/finding-plan-id.fd81e0e.480.png) ## Update the Published App[​](#update-the-published-app "Direct link to Update the Published App") After publishing, if the integration stops working, it is usually because the URLs have changed. Copy the new URL from the App Publish button, update the `LIVE_FRONTEND_URL` secret, and ask the AI agent to verify the checkout redirection and webhook URLs and update them if necessary. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") Thorough testing ensures everything works as expected. However, issues can still occur. Here are our recommendations and tips. ### Getting Help from the AI Agent[​](#getting-help-from-the-ai-agent "Direct link to Getting Help from the AI Agent") If something breaks or does not work as expected, first ask the AI agent to fix it. For example, if checkout redirection is not working, ask the agent: prompt ``` The checkout redirection is not working, check the redirection flow and make sure it works as expected. ``` ### Make Sure the Webhooks and Checkout Redirections are Working[​](#make-sure-the-webhooks-and-checkout-redirections-are-working "Direct link to Make Sure the Webhooks and Checkout Redirections are Working") Webhooks and Checkout Redirection are the two most critical parts of the integration. If they do not work properly, the integration will fail. Test these parts thoroughly. You can ask the AI agent to verify them end-to-end. Freemius also sends email notifications if webhook processing fails. ![Webhook failure notice](/help/assets/ideal-img/freemius-webhook-failure.b657177.480.png) If this happens, copy the email content and ask the AI agent to fix the issue. For example: prompt ``` I received the following email from Freemius about webhook processing failure: {paste the email content here} Please fix the issue and make sure the webhooks are working as expected. ``` ### Using One-off Purchases[​](#using-one-off-purchases "Direct link to Using One-off Purchases") Our integration guide is based on subscription plans and will not work for one-off purchases or lifetime access. While it is fully possible to integrate such purchase models with Freemius, it requires a different implementation approach. We recommend contacting our [support team](mailto:support@freemius.com?subject=One-off%20Purchase%20Integration%20with%20Bolt) with your use case and requirements, and we can guide you through the best approach for your specific needs. ### Contact Freemius Support[​](#contact-freemius-support "Direct link to Contact Freemius Support") Our support team is here to help. Contact us at , and we will be happy to assist with integration and troubleshooting.