Subscription Foundation

Subscription Foundation delivers an open source framework (opens in a new tab) for building BigCommerce apps that empower shoppers to subscribe to products and services. It provides a template for custom subscription billing and invoicing solutions for your business or client. Subscription Foundation includes a default integration with Stripe Billing, which can significantly accelerate your development time.

Subscription Foundation uses the Channels toolkit to display the custom subscription channel in the Channel Manager of a store's control panel alongside other sales channels.

Software requirements

• Node.js (opens in a new tab) 18.15.0
• The npm (opens in a new tab) package manager
• A supported SQL database engine (opens in a new tab), either Postgres or another database server of your choice

Configure accounts

To configure your accounts, complete the following steps:

1. To develop and test apps, you need a BigCommerce sandbox store. If you don't have one, Create a Sandbox Store.
2. To register apps and create app API accounts, you need a BigCommerce Dev Portal account. If you don't have one, create a Dev Portal account (opens in a new tab).

Fork and install the source repository

To fork the repository, complete the following steps:

1. Fork the subscription-foundation repository (GitHub) (opens in a new tab) to your GitHub account.
2. Clone your fork to your local development environment.
3. Navigate to the root directory of your cloned repository and install the default packages for your app by running the following command:

npm install

Create an HTTPS tunnel

After you successfully install the packages, prepare to expose the app to the internet so you can install it on your sandbox store.

Because you must serve apps over fully-qualified publicly accessible URLs, this guide uses a tool called ngrok (opens in a new tab) to open HTTP tunnels that securely expose localhost ports to the internet.

To get started with ngrok, follow the Create an HTTPS Tunnel section of the sample app tutorial. If your app does not run on port 3000, replace 3000 with the port of your app server.

Create an app profile

As a next step, you need to create a draft app profile to generate app API account credentials. To develop and test the app, you need to install it on your sandbox store.

To install your app on your sandbox store, complete the following steps:

1. Sign in to the Dev Portal (opens in a new tab). Then follow our directions to create an app. Enter the following values on the Technical tab.

2. In the Callback URLs section, supply the following URLs. Replace {ngrok_url} with the ngrok ID you noted in Create an HTTPS tunnel. Edit the app profile with new callback URLs each time the ngrok id changes. To learn more about developing with ngrok, see How to Test App Authentication Locally with ngrok (opens in a new tab).

3. In the OAuth scopes section, add the following scopes:

4. On the App Supported Features tab, select MULTI STOREFRONT to specify this is a multi-storefront enabled app.

5. Click Update & Close, then click Confirm Update to acknowledge the OAuth scopes you configured.

Make sure to remain signed in to the Dev Portal.

Configure Stripe

Subscription Foundation uses Stripe Connect so that your app can use one single connection to submit payments to the previously configured Stripe accounts of multiple BigCommerce merchants. See Stripe Billing (opens in a new tab) for merchant configuration instructions.

When the app initiates subscription charges, it will use the merchant's dedicated public key with the app's dedicated secret key. This ensures that a subscriber's entire purchase history is available in the merchant's Stripe Dashboard and store control panel.

During development, you'll work with two Stripe accounts. You'll create them both in the next section. The following table lists them in the order of creation:

Create Stripe accounts

To create a Stripe account, complete the following steps:

1. To create the Stripe account that simulates your merchant's pre-existing Stripe account, sign up with Stripe (opens in a new tab). Your app uses this account's client ID to process subscriber payments and manage subscriptions. Make sure to give it a merchant-specific name.

2. Sign in to the Stripe Dashboard (opens in a new tab).

3. On the Stripe Dashboard (opens in a new tab), create and configure a second app-specific Stripe account. The app uses this account's client secret to process subscription payments.

   a. In the top left corner of your Stripe Dashboard, click the name of your merchant-specific account. Select + New Account from the drop-down list.

   b. Give the new account a name that clearly identifies it as app-specific to differentiate it from the merchant-specific payment and subscription management account. This guide uses BigCommerce App as an example.

   

   c. Under Get started with Stripe, copy the Secret key.

Enable Stripe Connect for Platforms

As you complete the following steps, make sure that you are making changes to the app-specific account. To verify, check the top left corner of your Stripe Dashboard for the app account name you chose in step 3b of the preceding section.

To configure test mode, complete the following steps:

1. On your Stripe Dashboard (opens in a new tab), click Connect to enable Stripe Connect for Platforms (opens in a new tab).

2. Click Get started.

3. Select Platform or Marketplace, then click Continue.

4. To configure the app-specific account's Stripe Connect settings, go to Settings > Connect settings (opens in a new tab) on your Stripe Dashboard.

5. Under Integration do the following:

   a. Copy the Test mode client ID.

   Make note of the client ID

   Make note of the test mode client ID and keep it in a safe location. In a later step, you will use the client ID to update the NEXT_PUBLIC_STRIPE_CLIENT_ID environment variable in the .env file.

   b. Set OAuth settings to OAuth for Standard accounts.

   c. Click Redirects, then click + Add URI. Add the following callback URI for your app:

   Your app's Stripe callback URI

   https://{ngrok_url}/stripe/callback

Configure the BigCommerce store

After you successfully configure test mode, configure your BigCommerce sandbox store in the store control panel.

To configure the store to make subscription charges, complete the following steps:

1. In the control panel of your BigCommerce store, navigate to Store Setup > Payments > Stripe settings (opens in a new tab) and make sure that Test Mode is set to Yes.

2. To start a subscription, shoppers must check out using a stored payment instrument. To enable this functionality, go to Stripe settings (opens in a new tab), locate the Stored Credit Cards section, and toggle on Enable stored credit cards with Stripe.

3. If you don't have a stored card to charge, go to your BigCommerce storefront and add some products to your cart. Begin the checkout sequence and either sign in as a shopper or create a new account. During the payments step, select Save this card for later.

Declare environment variables

After you configure the store, you have all the information you need to add environment variables to your project.

To declare environment variables, complete the following steps:

1. Create a .env file in the root directory of your project.

2. Copy the contents of .env.sample to .env with the following command:

cp .env.sample .env

Open the .env file you just created and update the following environment variables:

Run migration and start the server

To run the migration and start the server, complete the following steps:

1. If you're using Postgres, which is the default data store for Subscription Foundation, skip to the next step. Otherwise, follow the instructions in Replacing Postgres.

2. Obtain the database URL in Supabase (opens in a new tab) by doing the following:

   a. In the Supabase dashboard, click New project and select the appropriate organization. Enter a name and database password in the Create a new project dialog, and click Create new project.

   b. In the Supabase dashboard, click the Settings (gear) icon, and in the left navigation menu, click Database. Scroll down the page to the Connection string section, click URI, and copy the connection string. Use this string to update the DATABASE_URL environment variable in the .env file. The string resembles the following example:

postgresql://postgres:[YOUR-PASSWORD]@db.uqchmyniufaqkijttavq.supabase.co:5432/postgres

3. Run the pre-configured Prisma migration script to create the database tables and initial client as defined in /prisma/migrations/* by issuing the following command:

npx prisma migrate dev

3. Start the app server with the following npm script:

npm run dev

After the app server and ngrok are running, you can install the draft app on your sandbox store. For more information about installing and troubleshooting apps in development, read our App Tutorial section on Installing and launching an app.

Replacing Postgres

To use an alternate SQL database (e.g., SQLite), complete the following steps:

1. Update the /prisma/schema.prisma file with a provider other than Postgresql. For a list of options, read Prisma's reference docs (opens in a new tab).

databse db {
   provider = "sqlite"
   url      = env("DATABASE_URL")

2. In /prisma/.env, update the value of the DATABASE_URL variable to match the connection string of your new database. Use the same string to update the DATABASE_URL environment variable in the .env file.

3. Run the prisma migration script with the following command:

npx prisma migrate dev

4. To generate a fresh app client that uses the new database provider, run the following script:

npx prisma generate 

5. To access this database locally, run the following command, then use a visual editor to verify that the database tables have been created.

npx prisma studio

6. Start the app server by running the following command:

npm run dev

Managing subscription products

To add new subscription rules and edit existing ones, complete the following steps:

1. In the store control panel, navigate to the Channel Manager menu and click Stripe Subscriptions.
2. Click the product you want to modify. For more information, see Foundations for Stripe Billing (opens in a new tab).

If you plan to use the API to add products to the subscription sales channel, see product channel assignments for more information.

Deploying your app with Vercel

The BigCommerce Subscription Foundation framework enables you to deploy your application with Vercel directly from the GitHub repo.

To deploy your app with Vercel:

1. Login to GitHub, and then navigate to the BigCommerce Subscription Foundation README.md (opens in a new tab) file.
2. Scroll down the page to the Deploy with Vercel section and click Deploy.

3. In the Get started section, select a Git provider, and then authorize Vercel to connect to your provider.
4. In the Create Git Repository, select a Git scope, enter a name for the repository, and then click Create. Do not enable Create private Git Repository because a different OAuth is needed and will cause an error.

5. (Optional) If you are deploying to Vercel from a GitHub organization, you need to create a team by following the steps in the Create a team section.

6. In the Configure Project section, in the DATABASE_URL field enter the connection string for the Supabase database you created in the previous step. See Run migration and start the server for information on creating the database and obtaining the DATABASE_URL.

7. Enter '1234' for the remaining environment variables and then click Deploy. The deployment process will take a few minutes.

8. After you have successfully deployed to Vercel, you must update your environment variables. For more information, see Declare environment variables.

9. Redeploy your application to Vercel for the environment variable changes to take place. Click on the Deployments tab and select Redeploy from the three vertical dots on the right.

Troubleshooting

Issue: Environment variable not found when running the database migration

This error can occur when the /prisma/schema.prisma file contains the incorrect provider, or the .env file contains an incorrect DATABASE_URL. Verify that the information in both files is correct.

Issue: A "Not found" error during app installation

If you don't enable the proper OAuth scopes, the /api/auth request might fail. Go to the Dev Portal (opens in a new tab) to verify the proper OAuth scopes are enabled in your app's profile. To learn more, read Managing Apps in the Developer Portal. Make sure your scopes equal or exceed those listed in the Creating an app profile section.

Issue: Unable to migrate your data to another provider.

To manually switch the database provider, complete the following steps:

• Change the provider and url parameters in the datasource block of the /prisma/schema.prisma file
• Archive or remove the ./prisma/migrations folder
• Run prisma migrate dev to start a new migration history

Resources

Related articles

• Subscription Foundation README (opens in a new tab)
• Connecting with Stripe (opens in a new tab)
• Introducing the Subscription Foundation (opens in a new tab)
• Prisma Migrate limitations and known issues (opens in a new tab)