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
Account configuration requirements
- Because there is a store email address constraint on draft and private apps, you need to make sure that both your sandbox store and your Dev Portal account use the same email address.
- We recommend that you use a sandbox store that has the same multi-storefront status as the production store. For example, if you're developing for a multi-storefront enabled merchant store, use a multi-storefront sandbox. For information on configuring multi-storefront, see Multi-Storefront (opens in a new tab).
To configure your accounts, complete the following steps:
- To develop and test apps, you need a BigCommerce sandbox store. If you don't have one, Create a Sandbox Store.
- 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:
- Fork the subscription-foundation repository (GitHub) (opens in a new tab) to your GitHub account.
- Clone your fork to your local development environment.
- 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.
Make note of your ngrok ID
After you successfully start ngrok, make sure to note your ngrok ID. You will use it to create an app profile. By default, ngrok generates a new ID every time you start it up. Make sure to update the callback URLs in your app profile each time the ngrok id changes.
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:
-
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.
-
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).
Callback | URL value |
---|---|
Auth Callback | https://{ngrok_url}/api/auth |
Load Callback | https://{ngrok_url}/api/load |
Uninstall Callback | https://{ngrok_url}/api/uninstall |
- In the OAuth scopes section, add the following scopes:
UI Name | Permission | Parameter |
---|---|---|
Orders | modify | store_v2_orders |
Order Transactions | modify | store_v2_transactions |
Products | modify | store_v2_products |
Customers | modify | store_v2_customers |
Content | modify | store_v2_content |
Carts | modify | store_cart |
Channel Listings | modify | store_channel_listings |
Channel Settings | modify | store_channel_settings |
Information & Settings | modify | store_v2_information |
Sites & Routes | read-only | store_sites_read_only |
Storefront API Tokens | generate tokens | store_storefront_api |
-
On the App Supported Features tab, select MULTI STOREFRONT to specify this is a multi-storefront enabled app.
-
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:
Order of creation | Description |
---|---|
Merchant account | This account simulates a merchant's pre-existing account |
App account | You'll configure this account as the app's dedicated Stripe Connect-enabled account |
Multi-tenant setup
Prior to installing the app, add the merchant account to the sandbox store as a payment method. When the app is installed, the UI prompts the store owner or authorized user to give the app permission to make charges on behalf of the store. Upon consent, the app initiates an OAuth code grant flow to link the merchant's Stripe account with the app's Stripe Connect-enabled account. The diagram below shows the configuration and the integration process.
Create Stripe accounts
To create a Stripe account, complete the following steps:
-
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.
-
Sign in to the Stripe Dashboard (opens in a new tab).
-
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:
-
On your Stripe Dashboard (opens in a new tab), click Connect to enable Stripe Connect for Platforms (opens in a new tab).
-
Click Get started.
-
Select Platform or Marketplace, then click Continue.
-
To configure the app-specific account's Stripe Connect settings, go to Settings > Connect settings (opens in a new tab) on your Stripe Dashboard.
-
Under Integration do the following:
a. Copy the Test mode client ID.
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 URIhttps://{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:
- 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.
- 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.
- 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:
-
Create a
.env
file in the root directory of your project. -
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:
Environment variable | Description | Reference location |
---|---|---|
NEXT_PUBLIC_APP_URL | A public-facing URL that can receive webhooks. | On this page, see Create an HTTPS tunnel; see also the HTTPS tunnel section of the Sample App Tutorial |
DATABASE_URL | A URL that connects to a database | On this page, see Run migration and start the server |
NEXT_PUBLIC_APP_ID | The app's ID | Find an App's ID |
BC_APP_CLIENT_ID | The app API account's client ID | View App Credentials |
BC_APP_SECRET | The app API account's client secret | View App Credentials |
NEXT_PUBLIC_STRIPE_CLIENT_ID | The app-specific Stripe Connect API account client ID | see Enable Stripe Connect for Platforms |
STRIPE_SECRET_KEY | The app-specific Stripe Connect API account client secret | see Create Stripe Accounts |
Run migration and start the server
Database note
This example uses Postgres as a data store. We recommend using Supabase (opens in a new tab) for a free database. For information on switching databases, see the Replacing Postgres section.
To run the migration and start the server, complete the following steps:
-
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.
-
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
- 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
- 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:
- Update the
/prisma/schema.prisma
file with aprovider
other thanPostgresql
. For a list of options, read Prisma's reference docs (opens in a new tab).
databse db {
provider = "sqlite"
url = env("DATABASE_URL")
-
In
/prisma/.env
, update the value of theDATABASE_URL
variable to match the connection string of your new database. Use the same string to update theDATABASE_URL
environment variable in the.env
file. -
Run the prisma migration script with the following command:
npx prisma migrate dev
If you miss the preceding step, the database provider will not be successfully switched. For a list of Prisma migrate limitations, see Prisma Migrate limitations and known issues (opens in a new tab).
- To generate a fresh app client that uses the new database provider, run the following script:
npx prisma generate
- 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
- 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:
- In the store control panel, navigate to the Channel Manager menu and click Stripe Subscriptions.
- 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:
- Login to GitHub, and then navigate to the BigCommerce Subscription Foundation README.md (opens in a new tab) file.
- Scroll down the page to the Deploy with Vercel section and click Deploy.
- In the Get started section, select a Git provider, and then authorize Vercel to connect to your provider.
- 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.
- (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.
-
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
. -
Enter '1234' for the remaining environment variables and then click Deploy. The deployment process will take a few minutes.
- After you have successfully deployed to Vercel, you must update your environment variables. For more information, see Declare environment variables.
- 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
andurl
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)