Management APIs
Building Apps
Quick Start
Building Channels
Quick Start
Building Headless Storefronts
Embedded Checkout
Next.js Commerce
Building Checkouts
Managing Currencies
Partner Information
Becoming A Partner
Getting Started
Staying Current with Platform Changes
POS Solutions
ERP Solutions
PIM Solutions
OMS Solutions
Marketing Solutions
Shipping Solutions
Payment Solutions

BigCommerce Apps Quick Start

In this quick start tutorial, you will create a single-click app using Node.js, React, Next.js, and BigDesign.


To successfully complete this tutorial, you will need the following:

Get started

  1. Start by forking the sample-app-nodejs repository.
  2. Navigate to the root directory of your project and install npm packages.
npm install

Add and start ngrok

You will need a publicly accessible URL to connect your sample app to BigCommerce. To add network access while in the development phase, you can use ngrok, a free tool that lets you expose local servers like localhost:3000 to the public internet over secure tunnels.

  1. In a new terminal window, install ngrok.
npm install ngrok -g
  1. Expose the web server on port 3000 to the internet.
ngrok http 3000

Register a draft app

Next, register a draft app in the Developer Portal using the sandbox’s app URL. To do so:

  1. Login to the Developer Portal.
  2. Click Create an app.
  3. Give the app a name.
  4. Click Technical.
  5. Enter Auth Callback URL as https://{ngrok_id} For example, You can get the ngrok_id from the terminal that is running ngrok http 3000.
  6. Enter Load Callback URL as https://{ngrok_id}
  7. Enter Uninstall Callback URL as https://{ngrok_id}
  8. Because you will be modifying the Products API resource, set the Products OAuth scope to MODIFY. To learn more about the available OAuth scopes, see OAuth scopes.
  9. Click Update & Close.
  10. Click View Client ID – this is the app’s client ID and client secret.

Keep this tab open for the next step.

Configure sandbox environment

After registering the app, enter the app’s credentials and auth callback into your sandbox’s environment variables (


If deploying on Heroku, skip the .env setup. Instead, enter env variables in the Heroku App Dashboard under Settings > Config Vars.

  1. Create an .env file in the root directory of your app.

  2. Copy the contents of .env-sample to .env.

# Get the Client ID and Secret from the Developer Portal
CLIENT_ID={app client id}
CLIENT_SECRET={app secret}


# Replace jwt key with a 32+ random character secret

# Specify the type of database

# If using firebase, enter your config here
FIRE_API_KEY={firebase key}
FIRE_DOMAIN={firebase domain}
FIRE_PROJECT_ID={firebase project id}

# If using mysql, enter your config here
MYSQL_HOST={mysql host}
MYSQL_DATABASE={mysql database name}
MYSQL_USERNAME={mysql username}
MYSQL_PASSWORD={mysql password}
MYSQL_PORT={mysql port *optional*}

See code in GitHub

  1. Replace the CLIENT_ID and CLIENT_SECRET with the app’s client ID and client secret from the Developer Portal.

  2. Update the AUTH_CALLBACK with the ngrok_id. You can get the ngrok_id from the terminal that is running ngrok http 3000.

  3. Enter a JSON Web Token (JWT) secret. To learn more about JWT, see the Internet Engineering Task Force documentation.


JWT key should be at least 32 random characters (256 bits) for HS256.

  1. Specify DB_TYPE:
  • If using Firebase, enter your Firebase config keys. For information on how to set up Cloud Firestore, see Firebase quick start.
  • If using MySQL, enter your MySQL database config keys (host, database, user/pass and optionally port).
  • If using Heroku with ClearDB, the database should create the necessary Config Var, namely, CLEARDB_DATABASE_URL.

Start dev environment

In a separate terminal from ngrok, start your dev environment.

npm run dev


If ngrok stops working or your ngrok session expires, restart the tunnel to get the new ngrok_id and update the callback URLs in the Developer Portal and the AUTH_CALLBACK in the .env file.

Install the app

  1. Log into your store and navigate to Apps > My Apps > My Draft Apps and install the app.
  2. If everything is configured correctly, you should get an Authorization Successful message.
  3. Navigate back to My Apps to see the list of installed apps.
  4. Click Launch on the draft app to test the /load callback.
  5. Navigate back to My Apps and click Uninstall to test the /uninstall callback.

Congrats! You’ve created and installed your first BigCommerce app.

Next steps