1

Getting started

Last Update 2 days ago

Setting Up the Template

Setting Up the Template

This guide covers the minimum required steps to get the template 100% functional after installation: admin access, default data, AI models (OpenRouter), and billing (Stripe).

Carlos Henrique

Last Update 2 days ago

💬 Want us to set this up for you, for free? If you'd rather not go through the setup yourself, you can open a support ticket or reach out to us directly through the chat in the bottom-right corner of the screen. We'll take care of the configuration for you at no cost.

1. Prerequisites

Before you start, have these ready:



    ⚠️ This template was built using Bubble.io’s new editor. Therefore, some features are only available in this version, such as Global Expressions. For more information, see the Property Editor Beta
    ⚠️ Go to App Editor > Settings > General and enable the "Expose the option to add an ID attribute to HTML elements" option.

    2. Turn Off Demo Mode

    This template ships with a Demo Mode setting, which disables all Create/Update/Delete actions across the app. It exists so the public marketplace demo doesn't get polluted with test data from visitors. You need to turn this off for your own app to be usable.
    1. In the Bubble editor, go to Data → Option Sets → AppEnvironment
    2. Open entry v1 and click Modify attributes
    3. Set Demo mode to no
    While you're in this screen, you can also configure other general settings available here: company name, company logo, contact email, and social media links.

    3. Create Your Admin Account

    If your database is empty (you did not copy the sample data when creating the app), there are no users yet — including no admin.

    1. Go to your app's Sign Up page and create a normal account
    2. In the Bubble editor, go to Data → App Data → User
    3. Find the user you just created
    4. Change its system_role field to Admin

      You can now log in and access the Admin panel.

      ⚠️ Admin:

      • pass: 12345678​

      4. Populate Default Data (Tools & Free Plan)

      1. Log in as your new admin user
      2. Go to Admin → System & API → API & Integrations
      3. Scroll to the "Default Data" section
      4. If you see "⚠️ No data found", click Populate Default Data

      This creates:

      • The 6 built-in AI tools (Web Search, Web Fetch, Datetime, Fusion, Advisor, Subagent)
      • The Free plan only
      ⚠️ This button does not create the paid plans (Plus, Pro). You'll create those manually in step 6, since they need to be linked to real Stripe Price IDs specific to your account.

      5. Connect OpenRouter

      5.1 Get your API key

      1. Go to openrouter.ai/workspaces/default/keys and create a new key
      2. Copy it — you'll paste it in the next step

      5.2 Add it to your app

      1. In your app, go to Admin → System & API → API & Integrations
      2. Under the OpenRouter tab, paste your key into "OpenRouter API Key"
      3. Click Rotate

        5.3 About the AI Chat streaming key

        Real-time streaming responses in Bubble only work when the API call is triggered from a client-side (page) workflow — this is a Bubble platform requirement, not a choice made by this template. Because of that, the Authorization key for the Chat Completion (Stream) call can't be resolved dynamically from the database the same way every other OpenRouter call in this template does (which all read the key from Admin → API & Integrations at request time, entirely server-side).
        In this template's marketplace demo, that key is set as a dynamic/public parameter (not hardcoded), pulling from the same key you enter in step 5.2. This is done on purpose and temporarily, so anyone testing the live demo can paste their own OpenRouter key in the admin panel and try the AI Chat — without needing access to the Bubble editor at all.
        This is not the recommended setup for a production app. Before launching your own app, lock this key down:
        1. In the Bubble editor, go to Plugins → API Connector → OpenRouter
        2. Open the Chat Completion (Stream) call
        3. In the Authorization header, replace the dynamic parameter with a fixed value: Bearer YOUR_API_KEY
        4. Check the Private checkbox next to it
        5. Save
        6. Go to App Editor > Data > Privacy > AppSetting > "Logged in" rule:
          1. Uncheck "Find this in searches".
          2. Uncheck "View" and "Find this in searches" for all fields (key, value, and slug).
          ⚠️ Once set as Private, rotating your key means updating it in two places: the admin panel (used by all other calls) and this Private field (used only by streaming).
          ⚠️ Before going live: the API Connector lets you set different values for the Test and Live versions of your app. Make sure you enter your OpenRouter key for the live version as well — not just the test/development one — or streaming will fail once your app is published.

          5.4 Import your AI models

          1. Go to Admin → Models → Import
          2. Click Import and confirm
          3. Models are pulled directly from OpenRouter and cached in your database
          4. Toggle Available on/off per model to control what your users can select
          ⚠️ Before enabling a model for your users: check its supported_parameters on openrouter.ai/models — if it doesn't support tools, your AI Chat will fail with a 404 error whenever any tool (Web Search, Advisor, etc.) is enabled alongside it. Also confirm input_modalities includes image/file if you plan to allow attachments, and check context_length against your Chat Memory setting to avoid context-overflow errors. 
          ⚠️ ZDR (Zero Data Retention) Support: if the user enables the ZDR toggle, make sure that the selected model/provider supports a ZDR-compatible endpoint. Otherwise, the request will fail. Not every model/provider supports ZDR.
          ⚠️ Re-run the import periodically to keep your model catalog up to date with new OpenRouter releases.

          6. Connect Stripe

          6.1 Add your Stripe keys to the plugin

          1. In the Bubble editor, go to Plugins → Stripe
          2. Enter your Publishable Key and Secret Key (start with test keys)
          3. You can find both keys in the Stripe Dashboard, under the API keys section: Stripe Dashboard → Developers → API keys
            1. Publishable key → starts with pk_test_ or pk_live_
            2. Secret key → starts with sk_test_ or sk_live_
          EnvironmentPublishableSecret
          Testpk_test_...sk_test_...
          Live
          		pk_live_...
          		sk_live_...

          6.2 Set Checkout Version to v3

          1. In the same Plugins → Stripe settings screen, find Checkout Version
          2. Set it to v3 (Recommended)

          6.3 Add your Stripe Secret Key to the API Connector

          The Customer Portal ("Manage billing") uses a direct API call configured separately from the Stripe plugin, since the native plugin doesn't support it.

          1. In the Bubble editor, go to Plugins → API Connector → Stripe
          2. Paste your Stripe Secret Key into the Authorization header (same key as step 6.1)
          3. Open the Stripe Billing Portal call
          ⚠️ In the Headers section of the Stripe Billing Portal and Update Subscription calls for Stripe in the API Connector plugin, if it doesn't already exist, add the following header:

          • Key: Content-Type
          • Value: application/x-www-form-urlencoded

          6.4 Create your Products & Prices in Stripe

          For each paid plan (Plus, Pro — monthly and yearly), create a matching Product + Price in Stripe.
          1. Go to Stripe Dashboard → Product catalog → Add product
          2. Set the name, price, and billing interval
          3. Copy the generated Price ID (starts with price_...)
          6.5 Create your paid Plans in the app

          1. Go to Admin → Management → Plans
          2. Click Create Plan for each paid plan (Plus Monthly, Plus Yearly, Pro Monthly, Pro Yearly)
          3. Fill in the name, price, interval, seat limit, token limit, features, and the matching Stripe Price ID

          6.6 Check your Stripe API version

          This template was built and tested against Stripe API version 2026-07-29.dahlia. If your Stripe account is running an older version, some fields (like billing period data) may not match what this template expects.
          1. Go to Stripe Dashboard → Developers → Overview → API Versions
          2. Compare your account's default version to 2026-07-29.dahlia
          3. If it's older, click Upgrade version and select the matching (or newer) version

          6.7 Set up Webhooks

          Webhooks keep your app in sync with Stripe (cancellations, renewals, failed payments).

          Finding your workflow URLs:

          1. In the Bubble editor, go to Settings → API
          2. Copy the Workflow API root URL shown there — it looks like:

                3. Append the backend workflow name to the end of that URL. For example:

            Set up these 5 endpoints in Stripe Dashboard → Developers → Webhooks → Add endpoint, using the URL pattern above with each workflow name, and selecting the matching event:
            Workflow nameStripe event
            stripe_webhook_subscription_createdcustomer.subscription.created
            stripe_webhook_subscription_updated
            		customer.subscription.updated
            stripe_webhook_subscription_deleted
            		customer.subscription.deleted
            stripe_webhook_invoice_paid
            		invoice.paid
            stripe_webhook_invoice_payment_failed
            		invoice.payment_failed
            ⚠️ Before going live, repeat this step using your version-live URL instead of version-test, and configure a second set of webhooks in Stripe pointing to your live app.

            7. Start the Recurring "Free Period Reset" Event

            The app resets the usage period for workspaces on the Free plan automatically, but this recurring event needs to be scheduled once to start running — it doesn't begin on its own.
            1. Log in as admin
            2. Go to Admin → System & API → API & Integrations
            3. Click Initialize Free Period (or the equivalent button in that section)
            This only needs to be done once, ever — after the first run, it reschedules itself automatically.

            8. Test the Full Flow

            1. Sign up as a new user, create a workspace
            2. Open AI Chat, send a message, confirm a streamed response appears
            3. Enable a tool (e.g. Web Search) and confirm it affects the response
            4. Go to Billing, subscribe to a paid plan using a Stripe test card (4242 4242 4242 4242)
            5. Confirm the plan updates in your app after checkout
            6. Cancel the subscription and confirm it reverts to Free
            7. Log in as admin, confirm the Dashboard shows MRR/Revenue data

            9. Going to Production — Checklist

            Before switching your app to the live version, make sure you've done all of the following:

            1. Added your OpenRouter key for the live version (step 5.3)
            2. Added your Stripe live keys to the Stripe plugin (step 6.1) and the Billing Portal API Connector call (step 6.3)
            3. Set up live-mode webhooks in Stripe, pointing to your version-live URLs (step 6.7)
            4. Copied your database from version-test to version-live — at minimum, the Tool and Plan tables, and any other data you want carried over (Bubble's Deploy to live screen lets you choose which tables to copy)
            5. Turned off Demo Mode on the live version too, if it was re-enabled during deployment

            Troubleshooting

            Error: billing_mode.type=flexible ... not supported: plan, quantity
            Some Stripe accounts default new subscriptions to "Flexible" billing mode, which can be incompatible with Bubble's native Stripe actions. If you run into this error, try setting Billing mode → Classic in Stripe Dashboard → Settings → Billing → Subscriptions and emails. This isn't required for every account — only apply this fix if you actually encounter the error.
            Chat doesn't stream / returns an error
            Confirm the key entered in Admin → API & Integrations (step 5.2) is valid. If you've already made the streaming key Private (step 5.3), check that field directly in the API Connector instead — and confirm it's set for the environment (test/live) you're currently using.
            Why is the streaming API key not Private by default, unlike every other key in this template?
            This is intentional for the marketplace demo only — see step 5.3 for the full explanation and the steps to lock it down for your own production app.
            "No models found" in the Model Selector
            Run the model import again (step 5.4). Confirm your OpenRouter API key is valid via Test Key (step 5.2).
            Webhooks not updating subscription status
            Double-check the event type selected in Stripe matches the workflow name, and that the webhook URL points to the correct environment (version-test vs. version-live).
            Create/Update/Delete buttons don't seem to do anything
            Demo Mode is probably still enabled — see step 3.

            Was this article helpful?

            0 out of 0 liked this article

            Still need help? Message Us