These two scenarios are not mutually exclusive – some developers will work under both scenarios. But some of their setup instructions are redundant. Therefore, we suggest that you start with the section that best matches your immediate scenario.

Hidden Marketplace Apps

BigCommerce partners also have the option of uploading hidden/private apps to our App Marketplace. For details, please see Building Apps with OAuth.

Apps Quick Start

Private or Saleable Apps?

This section is intended for developers who want to immediately start developing and testing private apps for a particular store. If your ultimate goal is to distribute apps on the BigCommerce Apps Marketplace, you can avoid repeated steps (like creating trial/sandbox stores for app testing) by jumping directly to the instructions under Joining the BigCommerce App Marketplace.

To obtain Basic or OAuth credentials to use this API, you will first need to create a trial store. (If you already have a store, skip ahead to Logging In.)

Managing API Credentials

We recommend OAuth, because this authentication method is compatible with all current and planned BigCommerce APIs. Also, OAuth is required for apps intended to be sold on the BigCommerce App Marketplace. You can find details about building OAuth apps here.

Basic Auth is still supported as a legacy option for connecting with most of our v2 API. However, Basic Auth is not compatible with webhooks, and is not compatible with our v3 API. You can find details about building Basic-Auth apps here.

Authenticating with OAuth

The following sections outline how to create and manage OAuth tokens in the BigCommerce control panel.

Future-Proof with OAuth

We strongly recommend that you build all BigCommerce apps using OAuth. OAuth is compatible with all current and planned BigCommerce APIs, including v2 Webhooks and our v3 API. Also, any apps intended for sale on the BigCommerce App Marketplace (our app store) must use OAuth. BigCommerce is gradually deprecating its legacy support for Basic Authentication.

Obtaining OAuth Tokens

You can create and manage OAuth tokens in the BigCommerce control panel by creating an API account, as described below. (Only the store owner can create API accounts; accounts are limited to 50 per store.)

To create your API account and its corresponding token, use the following steps:

A successful save will display the pop-up shown below, containing the API credentials that your app will need to run authenticated requests – your Client ID and Access Token. (Certain APIs also need the Client Secret for signing.) A .txt file containing the same credentials will (on most browsers) automatically download to your computer. This file also contains the base API Path for your store, preconfigured for the v3 API.

Keep Your Credentials

There is no way to re-display this pop-up after you select Done to dismiss it.

So make sure you store your credentials – either by copying/pasting the contents of each field out of the pop-up, or by keeping the downloaded .txt file. Otherwise, you will need to repeat all the above steps to generate new credentials.

From a security perspective, these credentials are sensitive – please treat them with the same caution that you would treat a private key or root password.

Revoking an OAuth Token

To revoke an OAuth token, use the following steps to delete the associated API account:

Obtaining an API Token

Enter a Username. Reusing the app’s name is a good way to keep track of which account corresponds to which app. After saving, you can use the API credentials listed on this page.

Copy the API Path field’s value and paste it into a text editor. You will need this value to authenticate your app.

Copy the API Token field’s value and paste it into a text editor. You will need this value to authenticate your app.

Select Save if you’re creating or changing the API account.

Revoking App Access

To revoke app access to a store, use the following steps:

Log into your store’s control panel.

Select Advanced Settings.

Select Legacy API Accounts.

Select the gears icon in the Action column, then select Edit.

Select the Generate New Token button.

Select the Save button.

Select the check box next to the user.

Select the trash-can button.

Select OK in the confirmation prompt.

Regenerating an API Token

To change the API token that an app is using to access a store, use the following steps:

Log into your store’s control panel.

Select Advanced Settings.

Select Legacy API Accounts.

Select the gears icon in the Action column, then select Edit.

Select the Generate New Token button.

Select the Save button.

Basic-Auth API Requests

Many tools are available to interact with APIs. For example, to see how to quickly make initial requests using cURL commands, please see our cURL Quickstart Guide.

Joining the App Marketplace

The following sections outline the steps required to become a vendor of Single-Click Apps on the BigCommerce platform. Doing so requires a partnership application, but acceptance will authorize you to provide best-of-breed solutions to the fast-growing online businesses we host.

Want a Quicker Start?

If you only want to develop private apps for a particular BigCommerce store, you can get started faster by jumping to the streamlined instructions under Apps Quick Start.

Apply to the Technology Partner Program

Before you can submit an app to the BigCommerce App Marketplace (which merchants also know as our “app store”), you must become an official Partner. BigCommerce offers app developers free sandbox stores through its Technology Partner Program. You can apply for a technology partnership here. To be approved as a partner, you will need:

A website.

Intent to offer your app publicly.

Ability to support users of your app.

Evidence of expertise in app development.

Notes

If you are an existing BigCommerce partner, you do not need to re-apply for the Technology Partner Program.

The email address you use in the partnership application form must be the same email address as you use to log into your sandbox store, and to log into My Apps.

Once approved, you will receive one or more emails listing your partner credentials and next steps. Your Partner username and ID will be required to submit your app for App Marketplace consideration.

Create a Sandbox Store

Where prompted for an email address, enter the same email that you used when applying to become a Technology Partner.
Then select START YOUR TRIAL.

In the trial-store setup form, enter a store name, password, and other details. Then select CREATE YOUR STORE.

Email partnersupport@bigcommerce.com your new sandbox store’s friendly URL (for example:http://<your-store-name>.mybigcommerce.com). We will flag this on the back end as a development environment
(“sandbox store”). This will ensure your continued access to the store, as opposed to the normal 15-day trial.
Sandbox “Trial” Stores Don’t Expire

Although the Create a Trial Store option’s name indicates that the store might be temporary, your store will actually be permanent.

When you log into your new store, use the same email that you used at step 3 above.

Create Your Draft App

Once you’re ready to start on your app, navigate to the Developer Portal home page, select the My Apps link, and log in using the same email address you’ve used for your sandbox store.

The My Apps page is where you will add, edit, and manage any of your BigCommerce Single-Click Apps. Start by clicking Create an app, and initiating registration of your app. (You can always come back to edit your draft app’s name and other details later.)

Once your draft app is created, you will be able to install and test it privately in your sandbox store.

Note

To access your draft app in the store, make sure the email address you enter for your sandbox store’s Owner is identical to the email address you use for the BigCommerce Developer Portal.

Building Apps with OAuth

Public OAuth Apps (applications) can be listed in the App Marketplace for easy installation in all BigCommerce stores. They use OAuth for token exchange during installation: The user installing the app will approve the scopes for your app to access and/or modify their store’s data.

Building an OAuth app is the recommended approach in all cases. BigCommerce plans to eventually deprecate the alternative “Basic Authentication” method for accessing our APIs.

Private Apps and API Scripts

Shortcut

In some cases, you might want to simply create an API Account in your store’s control panel, as the fastest way to establish an API connection to an individual store and to start running requests. This might make sense in cases like these:

You are not creating an application for distribution in the BigCommerce App Marketplace.

You simply want to run API requests, and don’t need your application to provide a visual interface within your store.

API Endpoint

Public API requests are protected by TLS, and use the following base URI: https://api.bigcommerce.com. The exact paths are noted in the Reference section for each resource.

Request Headers

Public API requests are authenticated by the following HTTP headers:

X-Auth-Client: the Client ID. To get your Client ID, you must complete App Registration.

X-Auth-Token: the OAuth token. To get your OAuth token, you must complete App Installation.

In addition, while not all resources require the Accept and Content-Type headers, many do. To ensure that your calls succeed, always include these headers.

Managing Users’ Session Timeouts

We recommend that you add BigCommerce’s JavaScript SDK to your Single-Click Apps, to protect your apps’ users from getting logged out of the BigCommerce control panel after a period of idleness. To include our SDK, add this script tag to your Single-Click App:

<script src="//cdn.bigcommerce.com/jssdk/bc-sdk.js">

Optionally, you can pass a logout callback function within the initialization call:

Bigcommerce.init({onLogout:callback});

This callback function will run when the user explicitly logs out of the BigCommerce control panel, or is automatically logged out. The callback will allow your app to respond to this logout.

Monetizing Your App

If you want to charge merchants for your app, please note that BigCommerce expects you to handle the billing aspects of the transaction. Your app needs to take care of collecting the fee from the merchant.

Under BigCommerce’s Technology Partner Program, within 30 days of collecting this revenue, you must send BigCommerce 20% and retain the remaining 80% for yourself. Once your app is published, a mandatory revenue-share reporting form will be sent to the primary contact on your partner account, at the beginning of each month.

Hidden Marketplace Apps

Approved technology partners have the option of uploading “hidden” apps to the App Marketplace. A hidden app is a published app that does not show up in the public BigCommerce marketplace. This might make sense if, for example:

A partner is beta-testing an integration prior to a full Marketplace launch.

A BigCommerce user with several stores wants to install a custom app on all of them. (Submitting a hidden app offers a streamlined alternative to creating separate “draft” apps for each store.)

Apps that do not provide Web- or cloud-hosted components for a dashboard.

To create a Connector app that uses manual OAuth token creation, make the following selections on the My Apps Create/Edit flow’s Technical tab:

Set the App Type option to Connector.

Enter your app’s Signup URL.
(This is the URL where a user would begin to configure the connection between your service and the BigCommerce store.)

Under OAuth scopes, select the scopes that your app requires for BigCommerce review only.
(Later, you will need to instruct store users to create a token with the production scopes your app needs.)

Approval Required

BigCommerce must review and approve your Connector app proposal before we will accept the app’s submission to the Marketplace.

If you’re interested in submitting your integration as a Connector app, please contact out to [appstore@bigcommerce.com](mailto:appstore@bigcommerce.com) to discuss your plan.

App Registration

Once you have a sandbox store, you must register your app to get your Client ID and Client Secret.

The Client ID value uniquely identifies your app and you will need to pass it in the header of all your requests to the Stores API.

The Client Secret value is a secret that your app and BigCommerce share. You do need to pass the Client Secret value once during the app installation sequence. Thereafter, BigCommerce uses it to sign payloads in load, uninstall, and remove user requests, and your app uses it to verify the signature to ensure that the request is coming from BigCommerce.

The app registration wizard requests a number of details that you may not know just yet. You can come back and fill in the additional information later (discussed in App Submission).

Technical Prerequisites

Before you register your app, consider the required and optional steps below.

Auth Callback and Load Callback URIs

Because the Auth Callback URI and Load Callback URI requests originate from the browser and not from BigCommerce, you can use non–publicly-available URIs and a self-signed certificate for a quick start. However, you must switch to – and test your app with – a publicly available Auth Callback URI and Load Callback URI before submitting your app for consideration in the App Marketplace.

Uninstall Callback (Optional)

If you want to receive a callback when the store owner uninstalls your app, you can provide an Uninstall Callback URI.

Multi-User Support (Optional)

By default, your app will only be accessible to the store owner (i.e., the user who created the store). Optionally, you can allow your app to be accessible to other store users. Consider the following before enabling multi-user support:

Once you enable multi-user support, a store admin will still need to grant access to other users from within the store control panel. For each user account, there are settings that grant access to specific apps.

Your app should be aware that when it receives the Load Callback, the user information passed in might not be the store owner’s. You’ll need to determine how to respond if you see a different user. For example, you may want to provision a new user account in order to personalize the experience.

Requesting OAuth Scopes

If you know the OAuth scopes that your app requires, you should select these. If you do not yet know the scopes that you need, you can just request minimal permissions (such as Information: Read-Only) to get started. However, once you determine the scopes you need, you must:

Retest your app to make sure it still functions properly with the new token.

Registering Your App

The following procedure takes you through the minimum number of steps to successfully register your app and get your Client Secret and Client ID.

Log in at Developer Portal’s top right.

In the resulting login page, provide your sandbox store credentials.

NOTE:
These must be the credentials of the owner of the store where you plan to install your draft app.

Click My Apps.

Click Create an app.

In the Create an App dialog, type a name for your app.

Click Next.

Click Next again.

Click Next one more time.

In the Auth Callback URL box, type your Auth Callback URI.

In the Load Callback URL box, type your Load Callback URI.

In the Uninstall Callback URI box, provide your Uninstall Callback URI if you have one.

If you want to support multiple users: In the Supported Features area, select Multiple Users; and in the Remove User Callback URI box, provide a Remove User Callback URI.

Select the OAuth scopes that your app requires. If you do not yet know, select minimal scopes, such as Information: Read-Only.

Click Update & Close.

Back in My Apps, hover over your app.

Click View Client ID.

Copy the Client ID and Client Secret values from the dialog, and paste them into a safe and secure place.

App Installation and Update Sequence

A user at a store’s control panel kicks off the installation or update sequence by clicking to install your app, or by clicking an installed app to update its scopes. BigCommerce redirects the user to the Auth Callback URI provided during app registration. The Auth Callback URI must be publicly available, fully qualified, and served over TLS.

Handling Requests Securely

The request comes from the client browser, rather than directly from BigCommerce. This allows you to use a non-publicly-available Auth Callback URI while testing your app.

For security, Auth and Load callback should be handled server-side. If you are building a client-side application (such as an AngularJS Single Page App), you should handle Auth and Load callbacks outside that application. Use a separate service that accepts the Auth and Load callback requests, generates tokens, validates requests, and then redirects the user to your client-side app’s entry point.

The following diagram illustrates the entire sequence.

The remainder of this section discusses each action your app needs to take during the sequence.

Receiving the GET Request

The GET request to your Auth Callback URI contains a temporary code that you can exchange for a permanent OAuth token. It also includes a unique value that identifies the store installing or updating your app, as well as other values.

Parameters

The following table details the full list of parameters and values included in the GET request from BigCommerce to your Auth Callback URI. BigCommerce passes these within the URI itself as query parameters.

Parameter

Description

code

Temporary code to exchange for a permanent OAuth token. See Making the POST request below for more information about this exchange.

scope

List of scopes authorized by the user. As a best practice, your app should validate this list to ensure that it matches the app’s needs, and fail if it does not. However, at this time, the user does not have any opportunity to pick and choose between scopes. The dialog presented to the user requires the user to approve all scopes or none.

context

The store hash: a unique value that identifies the store on which a logged-in user has clicked to install or your app. BigCommerce passes this along with a context path, as follows: stores/{store_hash}. Save the store hash value, because you will need to pass it in all your requests to the Stores API.

Example – Initial Installation

This example initiates the token exchange, with a requested scope of store_v2_orders:

(Note that when your app receives a new token, any previously issued token is invalidated.)

Responding to the GET Request

Upon receiving the GET request at your Auth Callback URI, your app should return some HTML to the merchant browser. BigCommerce renders this in an iframe inside of the control panel. It could be a form that collects further information from the user, or you could redirect the user to your app’s main page. If you do not pass back some HTML, the user will be left looking at a blank screen. Such an app would not be accepted into the App Marketplace.

Making the POST Request

The POST request’s primary purpose is to exchange the temporary access code for a permanent OAuth token. However, your app must pass a number of additional values to accomplish the exchange. Pass the parameters and their values inside the request body, using query parameters and URL-encoding. To achieve this, you must include the following HTTP header:Content-Type: application/x-www-form-urlencoded

Make the POST request to the following address: https://login.bigcommerce.com/oauth2/token.

Initial Installation

During initial installation, upon receiving the POST, BigCommerce marks the status of your app as “Installed”, removes the progress-indicator overlay, and places your app icon in the control panel’s left-hand navigation. With the progress-indicator overlay removed, the user can interact with the HTML that you returned in your GET response.

Updates

During app updates, upon receiving the POST, BigCommerce removes the update prompt from the control panel.

Receiving the POST Response

The POST response will include a JSON object containing the permanent OAuth token, user information, and other values. Upon receiving the permanent OAuth token, store it securely. You should also store the user and store hash values, to identify the user and store at load and uninstall. The following sections detail the contents of the JSON body.

JSON Values

Name

Data Type

Value Description

access_token

string

The permanent OAuth token that your app can use to make requests to the Stores API on behalf of the user. Store this value securely.

scope

string

List of authorization scopes.

id

integer

Unique identifier for the user. Store this value to identify the user at load and uninstall.

email

string

The user’s email address. Store this value to identify the user at load and uninstall.

context

string

The store hash, as well as a base path: stores/{_store_hash_}

JSON Example – Initial Installation

JSON Example – Updating Scopes

Update requests will refresh the payload’s access_token and scope values. Here again, the following example requests a scope of store_v2_products, in addition to the initially requested scope of store_v2_orders:

Load Request and Response

Once your app has been installed, the store owner or user can click its icon in the control panel to launch it. This causes BigCommerce to send a GET request to the Load Callback URI that you provided. In a production environment, the Load Callback URI must be publicly available, fully qualified, and served over TLS/SSL.

Handling Requests Securely

The request comes from the client browser, rather than directly from BigCommerce. This allows you to use a non-publicly-available Auth Callback URI while testing your app.

For security, Auth and Load callback should be handled server-side. If you are building a client-side application (such as an AngularJS Single Page App), you should handle Auth and Load callbacks outside that application. Use a separate service that accepts the Auth and Load callback requests, generates tokens, validates requests, and then redirects the user to your client-side app’s entry point.

After processing the payload, your app returns its user interface as HTML. BigCommerce renders this inside of an iframe. Please see User Interface Constraints for important information about your app’s user interface.

Uninstall Request (Optional)

Store owners have the option to uninstall any app at any time. When a store owner uninstalls an app, the app’s OAuth token is revoked and the app cannot make requests to the Stores API on the store’s behalf anymore.

You do not need to provide an Uninstall Callback URI. The lack of an Uninstall Callback URI does not prevent uninstallation. Instead, the Uninstall Callback URI allows you to track store owners who uninstall your app and to run cleanup operations, such as removing the store’s user accounts from your system.

Should you choose to avail of this option and provide an Uninstall Callback URI, please note that it must be publicly available, fully qualified, and served over TLS/SSL. If provided, BigCommerce will send a GET request to your Uninstall Callback URI when a store owner clicks to uninstall your app. An example follows.

Remove User Request (Optional)

If you have not enabled multi-user support, you will not provide a Remove User Callback URI and can ignore this section. If you enable multi-user support, you can optionally specify a Remove User Callback URI. It must be fully qualified, publicly available, and served over TLS/SSL. BigCommerce will send a GET request to your Remove User Callback URI when a store admin revokes a user’s access to your app. An example follows.

Processing the JSON Object

The JSON object embedded in the signed_payload contains information about the BigCommerce store and the store owner or user.

Identifying the Store

You should use the store information to identify the store to which the request pertains.

Interpreting the User Information

Interpreting the user information varies as follows:

Request type

Multiple users enabled

Multiple users not enabled

Load

Compare the user information to see if it matches that of the store owner, received at the time of app installation or that of an existing user. If the user information does not match either of these, then it represents a new user that you should add to your database or other storage.

The information should match that of the store owner, received at the time of app installation.

Uninstall

The user information should match that of the store owner. Only the store owner can uninstall your app.

Should match the store owner.

Remove user

The user information should match one of the users that you have stored. After locating the stored user, delete it from your database or other storage.

N/A

JSON Values

Name

Data Type

Value Description

user.id

integer

Unique identifier for the user who initiated the callback.

user.email

string

Email address of the user who initiated the callback.

owner.id

integer

Unique identifier for the user listed as the store owner.

owner.email

string

Email address of the user listed as the store owner.

context

string

The context value is part of the API path for this store and includes the store_hash.

JSON Example

Multi-User Support

When you register your app with BigCommerce, if you enable multi-user support, this will allow store admins to manually authorize users – other than the store owner – to load the app. This feature is not available for basic-auth apps.

Enable Multi-User Support

As soon as you enable multi-user support, this affects the control panel of any store that has your app installed. If you already have an app published in the App Marketplace, be aware that this setting takes effect immediately. Therefore, we recommend testing your multi-user support using a separate app that is in draft status.

Tell Your Customers

Let your customers know that you’ve enabled this feature. Otherwise, they won’t know that they can start granting access to users.

About the Control-Panel Experience

Store admins will be able to adjust user permissions to grant/deny other store users’ access to your app.

The next time the user logs in, they will see any apps for which they have been granted access. The user can then click on the app icon in the left navigation to load it.

Use your draft app and your sandbox store to review this behavior.

About the Load Request

Apps with multiple users enabled can expect more than just the store owner’s email and ID in the JSON object sent in the load request. If a load request is sent with user information you haven’t seen yet, you should provision the user account and associate it with the store in your database.

Because you know the store owner’s email and ID from the App Installation sequence, your app can distinguish store owners from other users. This allows you to provide different user experiences based on the information in the load request. Here is a summary of the two types of users:

Store owner: Can install, uninstall, and load apps.

Users: Cannot install or uninstall apps. Permitted only to load the apps that a store admin has authorized.

About the Remove User Request

In addition to their ability to add users, store admins can also remove users. This action generates a GET request to the Remove User Callback URI that you provided in My Apps. Your app should delete from its records the user identified in the request.

UI Constraints

OAuth apps benefit from a high level of integration with the BigCommerce platform. Users interacting with your app will enjoy a seamless experience. BigCommerce achieves this by rendering your app’s user interface inside of an iframe within the control panel. To ensure acceptance into the App Marketplace, your app should be able to perform all of its functions inside of the iframe.

While very usable and friendly, the iframe approach does require special attention from app developers. The remainder of this page discusses several functional areas to consider when designing and developing your app.

About Mixed Content

The BigCommerce control panel is served over TLS/SSL. Your app must be hosted on a web server that accepts and sends TLS/SSL requests. In addition, all of the resources referenced in the HTML that you present to the end users must be served over TLS/SSL. You may find protocol-agnostic addressing helpful.

If the user interface retrieves images, scripts, or other assets over a connection not encrypted with TLS/SSL, the user will experience errors and possibly an inability to interact with your app. Before submitting your app, use an online crawler to check for insecure content.

About Same-Origin Policies

Same-origin policies restrict apps running within iframes from performing certain activities, such as interacting with other services and making OAuth connections. While apps that operate within the BigCommerce iframe get strong preference during App Marketplace considerations, we sometimes make exceptions for apps that need to interact with, and authenticate to, other services. If your app requires this, we advise you to open a new tab for actions that cannot occur within the iframe.

About P3P and Cookies

Internet Explorer is one of the browsers that BigCommerce supports, and our merchants do use it to access the control panel. If your app needs to set a cookie, you will need to craft a P3P policy. Otherwise, your app will experience issues on Internet Explorer. Please see the following pages for more information:

OAuth Scopes

The following table identifies the name used for each OAuth scope in the My Apps and control panel GUIs, along with the corresponding resources and the strings that get passed to your app during apps’ installation or scope updates.

All OAuth scopes except default have read_only scopes that allow only GET and HEAD requests.

Rate Limits – OAuth

Apps that authenticate with OAuth are rate-limited, based on a quota that is refreshed every few seconds. The maximum quota for a store will vary depending on the store’s plan.

Each request to the API consumes one available request from the quota. When an app hits the quota limit, subsequent requests are rejected until the quota is refreshed.

The store’s overall quota is distributed across all apps that are accessing the store at a given time. This provides fairness for multiple apps that are accessing the API simultaneously – preventing a single greedy app from consuming the store’s entire quota by itself.

Playing Nicely with the Platform

Honoring the rate limiter is very easy. Every API response’s HTTP headers give you full visibility into your position in the rate-limiting algorithm:

The X-Rate-Limit-Time-Window-Ms header shows the size of your current rate-limiting window. In this case, it’s 5000 milliseconds.

The X-Rate-Limit-Time-Reset-Ms header shows how many milliseconds are remaining in the window. In this case, 3000 milliseconds – so, 3000 milliseconds after this request, the API quota will be refreshed.

The X-Rate-Limit-Requests-Quota header shows how many API requests are allowed in the current window for your client. In this case, the number is 25 requests.

The X-Rate-Limit-Requests-Left header details how many remaining requests your client can make in the current window before being rate-limited. In this case, you would expect to be able to make 6 more requests in the next 3000 milliseconds; on the 7th request within 3000 milliseconds, you would be rate-limited and would receive an HTTP 429 response.

If your request to the API triggers a 429 Too Many Requests response, then you know you’ve been limited.

The rate-limited response will contain the X-Rate-Limit-Time-Reset-Ms header, specifying a time (in milliseconds) that your client must wait before its quota has refreshed.

Retry the request after this time has elapsed, and your API service will resume as normal.

Example

When you see a response with a HTTP 429 status code, your client shouldn’t make any further requests until your quota has refreshed:

Publishing OAuth Apps

The following sections cover how to submit your OAuth app to the BigCommerce App Marketplace, and how to enable merchants to install your app from the BigCommerce control panel or from other locations.

Apps must include contact information should a merchant need support on the app. Any relevant reference docs or media should also be included or linked.

Apps must be production-ready and free of defects.
Test before Submitting
Install and test your app thoroughly prior to submission. Be sure to install and run your app inside of your sandbox store, as a draft area to conduct your tests.

The entire app should operate within the iframe that opens when the user clicks on your app icon in the control panel’s launch bar. Exceptions may be made for apps that need to authenticate to other services using OAuth – as long as they open a new tab to do so.

Apps must be easy to use.

Whenever possible, apps must use the API resources to auto-fill and obtain information, rather than prompting the user. BigCommerce will reject apps requesting information that can be auto-filled.

Auto-Filling API You can obtain the store name, phone number, and other information from the Store Information resource.

The user ID and email address from the OAuth flow should allow you to automatically log the merchant into any additional systems. BigCommerce prefers apps that provide the merchant with a single-sign-on experience.

App Submission

When you first get up and running with your app development, you will leave many fields in My Apps blank, as discussed in the App Registration section. Before submitting your app for consideration, you must come back through the My Apps wizard and fill in the missing information. This section discusses each page of the wizard, and identifies the information and files required for App Marketplace approval.

Check for Complete Information

The wizard validates for your Partner username and ID, as well as for correctly formatted URLs. However, additional information is required to get your app accepted into the App Marketplace.

If you submit your app without the required information and files identified in this section, it will be rejected.

App Summary

The required fields in the App Summary panel are identified and discussed below:

Username: your Partner account user name.

Partner ID: your Partner account ID.

Logo: upload the image that you want to be displayed in the App Marketplace. To ensure optimal quality, you should use your image processing software to size it to 340 by 160 pixels before uploading.

Price: defaults to Free. If you do not want to receive any payment for your app, you can leave this in place. Otherwise, select the price that you want to charge merchants.

Free-Trial Templates

The App Summary price setting offers several predefined formats that include an optional Free Trial. Where possible, we suggest using these, to offer merchants uniform formatting in the App Marketplace.

If you select Free Trial, make sure that you select a price to charge at the end of the trial period.

Summary: A brief description of your app (your value proposition) to show alongside the logo in the App Marketplace. Maximum length is 140 characters.

Category: Select a minimum of one, maximum of two.

Details

All of the fields in the Details panel are required. Each is discussed below:

App Screenshots: You must include at least one, and may include up to four. Each screenshot should be 860 by 560 pixels.

Launch Bar

You must provide an app icon. To ensure optimal quality, you should use your image processing software to size it to 100 by 100 pixels before uploading. Your app icon will appear in the merchant’s control panel once your app has been installed.

Technical

You will have already provided much of the information during the initial app registration. However, before submitting your app, please review the information that you initially provided, to make sure that all of the URIs are publicly available, fully qualified, and served over TLS/SSL. In addition, ensure that your app is requesting all of the scopes that it needs now, as well as the scopes that you anticipate needing in the future.

Prior to submission, you must also provide detailed testing instructions, as well as test accounts.

Scope Changes

Changing scopes once your app has been launched will require all of your current users to re-authorize the app before they can launch it again.

Submitting your App

You can submit your app from the last panel. A fee of $99 is required for each submission. If your app is rejected and you need to resubmit it, you will be charged again, so be sure that it’s ready for review before submitting. Updates to the app will not require an additional submission fee.

After receiving the submission, BigCommerce will use the information that you have provided to interact with, evaluate, and test your app.

Configure Your Button

Upon click, your button should open a modal similar to the image below. We recommend a modal sized 900px wide by 450px high:

Your button will link merchants to BigCommerce’s install endpoint for your application. Once the merchant clicks the link, they will be prompted to log in, then authorize your application, just like in the normal installation flow.

Call Our Endpoint To Render Success/Failure Confirmation Pages

Next, modify your application code to serve either a success or failure page, depending on whether the external installation was successful or unsuccessful.

Provide the Confirmation Page for Good UX

If you skip this step, your application will load in the iframe created by your button. To ensure a good experience for your merchants, we strongly recommend that you return a confirmation page, instead of allowing your application to be loaded in that modal.

Handling Errors

If your application’s installation was initiated and completed through an external link, BigCommerce will send your auth callback endpoint an extra parameter called external_install.

Depending on which endpoint you call, we will render one of the following success/failed pages to the modal.

This is the “success” page:

This is the “failed” page:

We recommend that you call our endpoints to return the confirmation page, as we have formatted our HTML pages to fit well with our recommended modal size of 900px by 450px.

However, you also have the option of returning your own HTML page. If you do so, please optimize your page for the same 900px by 450px dimensions.

Building Apps with Basic Auth

“Private” apps require the manual creation of an API token for each store. They are most useful for custom integrations for a single BigCommerce store. They generally use HTTP Basic Authentication (with the exception of Draft apps), and communicate directly with the store’s API endpoints.

Limited Support for Basic Auth

BigCommerce is gradually deprecating Basic Authentication. Apps must use OAuth to access our v3 API.
Even within the v2 API, apps relying on Basic Authentication cannot access some features. (For example, the Webhooks resource requires OAuth.) Also, apps intended for sale on the BigCommerce App Marketplace must use OAuth.

Obtaining Basic-Auth API Tokens

Making Basic-Auth Requests

To allow an app to connect to a store using Basic Authentication, the store owner must manually generate an API key and provide this to the app developer along with a base path and user name.

To connect to a store using Basic Authentication, an app must:

Include the user name and API key in the Authorization field of each HTTP request header, using the following syntax: Basic <username:API_key>, where <username:API_key> is base64-encoded. Here is a specific example:
Authorization: Basic YWRtaW46ZTBhMDJiMDM5NzczNWI4NzNlZGQ5NWE1ZmQ1Y2I5YmI=

Use the base path provided by the store owner.

Use TLS encryption.

If the user name and/or API token are invalid or missing, the app will get a 401 Unauthorized response.

Rate Limits – Basic Auth

Requests from apps using Basic Authentication to the Stores API are limited to 20,000 per hour, with a rolling window that updates every minute.

These limits help to manage load on our servers, ensuring that high API request volumes don’t impact on overall store performance. They also help to protect stores from deliberate or accidental denial of service as a result of the API being flooded with requests.

It is important for API client applications to be aware of these limits and handle them appropriately.

HTTP Headers and Response Codes

Every response from the Stores API has an X-BC-ApiLimit-Remaining header, which provides information about how many requests are remaining in your client’s quota. This limit is based on total requests across the entire API.

For example, the following response header signals that your client can make up to 900 additional requests within the current window:

X-BC-ApiLimit-Remaining: 900

When the limit remaining drops to zero, additional requests result in Bandwidth Limit Exceeded responses with the 509 status code:

If your client is rate limited, you won’t be able to make further requests until your quota resets.

Working with Rate Limits

Applications that make a large volume of parallel requests or frequently poll resources to detect changes are particularly susceptible to being limited.

We recommend spreading API requests across the full one hour rolling window using the rate limit information returned to you from API responses, and minimizing the number of simultaneous API requests per store.

If you’re writing a high volume application, the following strategies will help you get the most out of the API.

Caching

Cache everything and refer to local information in your app where possible, rather than making repetitive API calls.

Throttling

You can limit the rate at which you send requests to the API by using a queue to keep track of outgoing calls, and throttling back calls that are going faster than your predefined limit.

For example, if you wanted to limit your outgoing API usage to four calls per second, you could use the following pattern:

Send first API call and record the timestamp

Send second, third, and fourth API calls

Check the timestamp before sending the fifth call

If less than a second has passed, wait until the second has elapsed

Send the next request

Pause and Resume

Simple applications running as background tasks can use the standard sleep function in their host environment to pause between outgoing requests.

Migrating to OAuth

Apps in the App Marketplace that use Basic Authentication are now deprecated, and will eventually be removed. This section outlines how to migrate your public app from Basic Authentication to OAuth.

OAuth allows API authentication and access on behalf of any merchant who authorizes your app. Merchants no longer have to bounce between multiple browser tabs, nor cut and paste API keys, to install apps.

Other benefits of updating include:

Improved Rate Limits. For apps that access the API using OAuth, we’re able to offer quota-based limits, with the possibility to increase the overall volume of requests for stores on higher plans.

How to Migrate

First of all, consider whether your application should reside within the public App Marketplace, where any BigCommerce merchant can easily discover and install it. To learn more about how to set up this kind of app, see Joining The App Marketplace.

If you would simply like to update your API connection from Basic Authentication to OAuth, you will need to make the following changes:

Get a Client ID and a Access Token, by creating an API Account within the control panel. You’ll want to make sure the account has the correct Scopes for the API endpoints you need to access. We recommend that you provide the minimum scopes that your application requires to function, as a good security practice.

If you use one of the Client Libraries, follow the relevant guide (within the library’s documentation) for establishing an OAuth connection.

If you have created your own connection, you’ll want to update your connection parameters:

Where you previously used the BigCommerce store’s secure hostname, you will instead use the api.bigcommerce.com gateway URL.

As an example, requests to https://store-abc123.mybigcommerce.com/api/v2/orders/123 or https://my-custom-store-domain.com/api/v2/orders/123 would instead go to _https://api.bigcommerce.com/stores/abc123/v2/orders/123, whereabc123` is the store hash.

With Basic Auth, you use an Authentication HTTP Header to authenticate your connection. With OAuth, you’ll want to use two headers - the X-Client-Id for your Client ID, and the X-Auth-Token header for your Access Token. You can read more here.

Rate limiting of API requests works differently for OAuth API connections. To become familiar with the OAuth system, please see the Rate Limits – OAuth documentation.

Storefront API/Apps Reference

Storefront apps interact directly with the BigCommerce storefront. They typically use JWT (JSON Web Token) authentication, rather than OAuth or Basic Auth. Storefront APIs currently available for building such apps are:

Customer Login API

The Customer Login API enables single sign-on (SSO). It allows your apps to generate a token to programmatically log in a storefront customer, by using the login entry point at /login/token/{token}. Here, {token} must be a JSON Web Token (JWT) containing the parameters for the customer login request in its payload, and must be signed by your OAuth application’s client secret.

For a full overview of the JWT standard, please see JWT.IO, where you will find links to client libraries (in many languages) that facilitate the generation and verification of JWT tokens. BigCommerce also supplies helper methods for generating login tokens in our API Client Libraries.

Customer Login Token

A valid JWT token is a string composed of three parts, separated by periods (“.”). Please refer to JWT.IO and RFC 7519 for more details on the format.

Example URL

Header

{"typ":"JWT","alg":"HS256"}

Example Payload

{"iss":"abc123","iat":123456789,"jti":"This is a completely unique string, ideally a UUID","operation":"customer_login","store_hash":"abc123","customer_id":12345,"redirect_to":"/account.php","request_ip":"111.222.333.444"}

Fields

Field Name

Type

Description

iss

string

Indicates the token’s issuer. This is your application’s client ID, which is obtained during application registration in Developer Portal.

iat

integer

Time when the token was generated. This is a numeric value indicating the number of seconds since the Unix epoch.

jti

string

Request ID string that must be unique across all requests made by your app. A UUID or other random string would be an appropriate value.

operation

enum

Must contain the string “customer_login”.

store_hash

string

Store hash identifying the store you are logging into.

customer_id

integer

ID of the customer you are logging in, as obtained through the Customer API.

redirect_to

string

Optional field containing a relative path for the shopper’s destination after login. Will default to /account.php.

request_ip

string

Optional field containing the expected IP address for the request.

Signature

The headers and payload must be signed using HS256 (HMAC-SHA256) and the application’s client secret.

Sample Code

Code to generate a valid JWT token for a storefront login request is provided in our API Client Libraries. (The headings below are linked to the live code, which might have been updated since the publication of the code samples here:)

importosimporttimeimportuuidimportjwtclassCustomerLoginTokens(object):@classmethoddefcreate(cls,client,id,redirect_url=None,request_ip=None):# Get the client_secret needed to sign tokens from the environment# Intended to play nice with the Python Hello World sample app# https://github.com/bigcommerce/hello-world-app-python-flaskclient_secret=os.getenv('APP_CLIENT_SECRET')ifnotclient_secret:raiseAttributeError('No OAuth client secret specified in the environment, ''please specify an APP_CLIENT_SECRET')try:client_id=client.connection.client_idstore_hash=client.connection.store_hashexceptAttributeError:raiseAttributeError('Store hash or client ID not found in the connection - ''make sure an OAuth API connection is configured. Basic auth is not supported.')payload=dict(iss=client_id,iat=int(time.time()),jti=uuid.uuid4().hex,operation='customer_login',store_hash=store_hash,customer_id=id)ifredirect_url:payload['redirect_url']=redirect_urlifrequest_ip:payload['request_ip']=request_iptoken=jwt.encode(payload,client_secret,algorithm='HS256')returntoken.decode('utf-8')@classmethoddefcreate_url(cls,client,id,redirect_url=None,request_ip=None):secure_url=client.Store.all()['secure_url']login_token=cls.create(client,id,redirect_url,request_ip)return'%s/login/token/%s'%(secure_url,login_token)

OAuth Scope

In order to use this feature, your app must be installed in the store, and must have the store_v2_customers_login scope.

Redirection

For flexibility in navigation after login, we support an optional redirect parameter (redirect_to), which in turn supports relative URLs. If the parameter is not specified, the storefront customer will land on their My Account page at /account.php.

Notes

Tokens will be valid for a very short timeframe after they are first generated, so tokens should not be generated in advance. Instead, the application should generate the token and then immediately redirect the user’s browser to /login/token/{token}.

Once a request has been made with a given jti, it cannot be made again. This parameter is used to prevent replay attacks by malicious actors intercepting the request or obtaining it after the fact.

The request_ip field can be used as an additional security precaution, to prevent a malicious actor from intercepting the request and making it from another browser or system before you do. If you supply this value, BigCommerce will check the incoming request to ensure that it is being made from the stated IP address – and will otherwise fail the request. We strongly encourage setting this IP address value; but doing so is optional, to support those cases where this information is not available.

Identifying Logged-In Customers Securely

If your application interacts dynamically with the BigCommerce storefront, and conveys information that is specific to a particular logged-in customer, you must confirm that customer’s identity within the insecure environment of the user’s browser.

Current Customer API

To address this need, BigCommerce provides a Current Customer endpoint, which your app can access via JavaScript on the storefront. This endpoint returns a JWT (JSON Web Token) with identifying details about the customer. The information is signed with your OAuthclient secret.

Example JavaScript

Below is example JavaScript that will access this JWT. To test the JWT functionality, you can install this JavaScript on your sandbox BigCommerce store. Your application’s Client ID must be included in the request (to identify the requesting application):

If you are logged into the storefront with a customer account, the above JavaScript should alert to the browser with a JWT token. If no customer is logged in, BigCommerce will return a 404 response, and you will see an error message.

By design, your application should send this token to the application’s server, validate it against your client secret, and then use it as a trusted indication of the logged-in customer’s identity, before displaying confidential information to them.

An end-to-end example, which displays a customer’s recently purchased products, is available in our Ruby and PHP sample apps.

Add-to-Cart URLs

Your apps can use a product’s or variant’s SKU to create custom product URLs in order to perform specific actions, like:

Add a specific SKU to the cart, go directly to checkout, and include a source parameter for analytics and conversion tracking.

Limitation: One Item per URL

Each of the custom links described here can add only a single item (quantity 1) to the cart at a time.

Select Specific SKU (Product/Variant) on Product Detail Page

To link to a specific product variant, append ?sku=INSERT-SKU-HERE to the product URL, as shown below. This will link to the product page, with the variant’s options already selected.

Structure:

site.com/sample-test-product-w-options/?sku=INSERT-SKU-HERE

Example:

myawesomestore.com/shirt/?sku=SHIRT-SM-RED

Add Specific SKU to Cart

To automatically add a product or variant to a shopper’s cart and take them directly to the cart page, appendcart.php?action=add&sku=INSERT-SKU-HERE to the store’s domain.

Structure:

site.com/cart.php?action=add&sku=INSERT-SKU-HERE

Example:

myawesomestore.com/cart.php?action=add&sku=SHIRT-SM-RED

Add Specific SKU to Cart and Go Directly to Checkout

To automatically add a product or variant to a shopper’s cart and forward them directly to checkout, appendcart.php?action=buy&sku=INSERT-SKU-HERE to the store’s domain.

Structure:

site.com/cart.php?action=buy&sku=INSERT-SKU-HERE

Example:

myawesomestore.com/cart.php?action=buy&sku=SHIRT-SM-RED

Add Specific SKU, Go to Checkout, and Include Source

To automatically add a product or variant to a shopper’s cart, forward them to checkout, and also include a source parameter for analytics/conversion tracking, append cart.php?action=buy&sku=INSERT-SKU-HERE&source=SOURCE-HERE to the store’s domain. (The source parameter can be any string.)

Storefront Cart API (Early Access)

This API exposes many of the same resources and operations that are provided in BigCommerce’s v3 Server-to-Server Cart API. However, to maintain stores’ security, some operations are not provided here. The limitations basically correspond to BigCommerce’s restrictions on the actions a shopper would be allowed to take on a BigCommerce storefront.

Early Access

During this early access release, the Storefront Cart API is stable, but does not yet contain all the features that we anticipate adding.

The MIME type of the request body. Use to validate and parse the request to the API.

application/json

User-Agent

String

While it is not required, we ask that you specify a user agent which identifies your integration/client with your requests.

X-Auth-Client

String

Client ID of the requesting app

X-Auth-Token

String

Access token authorizing the app to access resources on behalf of a user

Deprecated Headers

The following headers are deprecated and will eventually be removed from the API.

Header

Description

Use Instead

If-Modified-Since

Uses an RFC 2822 date. If supplied, then only resources modified since the specified date will be returned. If there are no modified objects, then a 304 Not Modified response will be sent. Please refer to the individual resource pages for support for this header.

Use min_date_modified and max_date_modified query parameters on resources that support them.

The version of BigCommerce the store is running on. This header is available on versions 7.3.6+.

7.3.6

Media Types

Introduction to Media Types

The BigCommerce API can accept requests, and respond, in either JSON or XML. You should encode requests using the UTF-8 character set. (Other character sets might have unpredictable results.)

Restricted XML Support

The XML media type is deprecated. Our v2 webhooks support JSON only, and Stores API versions after v2 will support JSON only.

Request Content Type

When performing a request that contains a body (eg. POST or PUT), the type of content you are sending needs to be specified in the Content-Type header. The values for this header are specified in the data types below. For example, to send an XML body, the header would be: Content-Type: application/xml

Response Content Type

There are several ways in which you can specify the type of content you would like to receive. The first method is by specifying an Accept header, the second is by supplying an extension to the resource you are request. Extensions are useful for browser-based testing.

API Status Codes

The API responds to requests with different HTTP status codes depending on the result from the request. Error responses might also include an error message in the body to assist the client in resolving the problem.

2xx Success

These codes are returned for requests that were understood and processed successfully.

Code

Definition

Purpose

200

OK

For successful GET and PUT requests.

201

Created

For a successful POST request.

202

Accepted

For a request that resulted in a scheduled task being created to perform the actual request.

204

No Content

For a successful request that produced no response (such as DELETE requests).

3xx Redirection

These codes are returned for requests that require the client to take further action.

Code

Definition

Purpose

301

Moved Permanently

When the API routes have changed (unlikely), or if the incoming request is not secure (http), the request will be redirected to the secure (https) version.

304

Not Modified

This response will be sent if the request included an If-Modified-Since header, but the resource has not been modified since the specified date. Please refer to individual resources’ documentation regarding support for the If-Modified-Since header.

4xx Client Error

These codes are returned for requests that could not be processed due to problems with the request or the data.

Code

Definition

Purpose

400

Bad Request

Issued when a malformed request was sent. Examples are:

* Invalid syntax

* Missing required data

* Webhook requests missing Content-Type in the HTTP header.

401

Unauthorized

This response is sent when your client failed to provide credentials or its credentials were invalid.

403

Forbidden

Returned when permissions do not allow the operation. To correct:

* Check your app in My Apps to review the OAuth scopes you requested, and check whether they support the request that you made.

* Changes to the store owner’s account (including a change to the email address) can also cause this error. Roll back those changes to correct it.

* This error can also occur when your request exceeds a limit imposed on the resource in question. For example, a store cannot exceed 16,000 categories. For more information, see the corresponding resource’s documentation.

404

Not Found

When a particular resource doesn’t exist or couldn’t be found.

405

Method Not Allowed

The resource was found, but doesn’t support the request method. Issued when either a specific method isn’t yet implemented on a resource, or the resource doesn’t support the method at all. For example, a PUT on /orders is invalid, but a PUT on /orders/{_id_} is valid.

406

Not Acceptable

When the client specifies a response content type in the Accept header that is not supported.

409

Conflict

A change requested by the client is being rejected, due to a condition imposed by the server. The exact reasons for this response will vary from one resource to the next. An example might be attempting to delete a category whose deletion would cause products to be orphaned. Additional information about the conflict, and about how to resolve it, might be available in the response’s details section.

413

Request Entity Too Large

When the client requests too many objects. For example, the limit parameter exceeded the maximum.

415

Unsupported Media Type

Returned due to issues with the Content-Type header. Examples of such issues are:

* The header specifies an unsupported content type.

* The header is missing (except with the webhooks resource, which returns a 400 in this case).

422

Missing or Invalid Data

The request cannot be processed either because it omitted required fields, or because it contained invalid data. See the response for more details.

429

Too Many Requests

When an OAuth client exceeds the rate limit for API requests to a store.

5xx Server Error

These codes are returned for requests that could not be processed due to an internal error with the API or server.

Code

Definition

Purpose

500

Internal Server Error

When an error has occurred within the API.

501

Not Implemented

When a request method is sent that is not supported by the API (e.g., TRACE, PATCH).

503

Service Unavailable

When the store is marked as “Down for Maintenance,” or the store is being upgraded to a new version.

507

Insufficient Storage

When the store has reached a limitation for the resource, according to their BigCommerce plan (e.g., 500-product limit).

509 (Deprecated)

Bandwidth Limit Exceeded

Returned to apps using Basic Authentication that have exceeded their rate limits.

Data Types

int

An integer number, with a maximum value of 2147483647. Negatives are disallowed, unless otherwise specified.

decimal(M, D)

A decimal number of up to M digits in total, including D digits after the decimal point. Negatives are disallowed, unless otherwise specified.

string(M)

A string of text up to M characters in length.

text

A string of text, up to ~16,777,216 bytes in length.

boolean

A boolean value: true or false. In JSON, it will be represented using the native boolean type. In XML, it will be the literal strings true or false.

date

An RFC 2822 date. All dates output by BigCommerce API responses are in GMT (+0000) time. However, you can use any time zone on inputs, as the offset information will be converted accordingly.

datetime

An ISO 8601datetime value. This is currently supported only as an input parameter on filters. Date values in responses remain in the RFC 2822 format.

enum

An enumeration of string values. The only allowed values are those specified in the field’s description.

object

country code

email address

variable

Variable data, depending on context. See the field definition for specifics.

array

A simple list of values. In JSON, this will be an array. In XML, the field will contain a set of <value> elements.

resource

A string representing a URI reference to another resource within the current version of the API.

null

A null value. In JSON, this is represented as the native null type. In XML, it is represented as the literal string NULL.

Supported Browsers

Below are the browsers supported for the BigCommerce control panel. We drop support when a version falls below 2% of usage. The browsers are sorted by popularity, with the most popular browsers at the top.

Desktop

Chrome latest

Firefox latest

Internet Explorer 11 or later

Safari latest

For a current list of target browsers (desktop and mobile) that BigCommerce supports for storefronts using our themes, please see this support page.

Webhooks Overview

Webhooks allow developers to build apps that receive information, in near–real time, about events that happen on BigCommerce stores. Webhooks require you to provide a callback URI where you want us to send information about the events that your app subscribes to. When the event happens we’ll send a POST request to your callback URI and then your app can perform some action based on that event.

For example, you might build an app that needs to know when:

An order is placed.

A product is added.

A customer record is updated.

Webhooks Requirements and Limitations

Webhooks differ from the rest of the Stores API as follows:

OAuth is required; basic authentication is not supported.

Self-signed certificates are not supported.

JSON is required; XML is not supported.

All webhooks requests must include the following in their HTTP headers:

Creating Webhooks: Sending the POST Request

To create a webhook, send a POST request to the hooks resource, including:

As the scope value, the event for which you would like to receive notification. See next section for the list of possibilities.
Wildcards are supported for scope.

As the destination value, the callback’s fully qualified URI.

A headers object containing one or more name-value pairs, both string values (optional). If you choose to include a headers object, BigCommerce will include the name-value pair(s) in the HTTP header of its POST requests to your callback URI at runtime. While this feature could be used for any purpose, one is to use it to set a secret authorization key and check it at runtime. This provides an additional level of assurance that the POST request came from BigCommerce instead of some other party, such as a malicious actor.

By default, new webhooks will be set to be inactive and will have a blank value. If you want to create a webhook that should be active initially, you can also pass the following name-value pair: "is_active": true.

Receiving Webhook Callbacks

You’ll need to build an application, and configure your server, to receive the callback that we send when events are triggered.

One-Minute Timeout

Following the creation of a webhook, it can take up to one minute for BigCommerce to start sending POST requests to your callback URI.

Lightweight Callback Payload

In the callback, we send a light payload with only minimum details regarding the event that’s been triggered. This gives you maximum flexibility as to how you want to handle the notification in your application. For instance, if you subscribe to the store/product/update event, we’ll send you the product ID when it’s been updated, and you might want to handle it by fetching the product via a request to the Products resource.

Multiple Events Are Triggered during Bulk Data Imports

Bulk data imports will trigger the relevant events for every record affected. For example, if you have a hook on store/product/created, when the merchant imports 2,000 products, then we will send 2,000 individual callback events.

Payloads Are Serialized

Payloads are serialized per hook per store.

In the future, we are looking at enabling a replay feature, allowing you to replay select events. What this means is, based on the serialized payload IDs, you can detect if you’ve missed certain callbacks and then, via a future update, you will be able call a replay method to get the missing events.

Respond to Webhook Callbacks

To acknowledge that you received the webhook without issue, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3_xx_ codes, will indicate to us that you did not receive the webhook. When a webhook is not received (for whatever reason), we will attempt to callback as described just below.

Callback Retry Mechanism

Webhooks will do their best to deliver the events to your callback URI. The dispatcher will attempt several retries until the maximum retry limit is reached, as follows:

Whenever a webhook gives a non-2_xx_ response, or times out, the app will be blocked for 60 seconds.

Webhooks created during that 60-second block will be queued up to send on the next scheduled retry attempt after the block expires, so that webhooks are not lost.

The dispatcher will then attempt several retries (at increasing intervals) until the maximum retry limit is reached, as follows:

Retry Intervals

60 seconds after the most recent failure

180 seconds after the most recent failure

300 seconds after the most recent failure

600 seconds after the most recent failure

900 seconds after the most recent failure

1800 seconds after the most recent failure

3600 seconds after the most recent failure

7200 seconds after the most recent failure

21600 seconds after the most recent failure

50400 seconds after the most recent failure

86400 seconds (24 hours) after the most recent failure

After the final retry attempt above (cumulatively, 48 hours after the first delivery attempt), the webhook will automatically be deactivated, and we will send an email to the developer’s email address registered on the subscribing app. Should you wish to reactivate the hook, you can set the is_active flag back to true via a PUT request to the hooks resource.

Updating a Webhook

Using your OAuth access token, send a PUT request to the hooks resource.

Deleting a Webhook

Using your OAuth access token, send a DELETE request to the hooks resource.

Troubleshooting

Below are remedies for certain errors commonly encountered with webhooks:

Not Receiving the POST Requests to My Callback URI

As noted above, if your app does not return an HTTP 2_xx_ to BigCommerce upon receipt of the POST request to the callback URI, BigCommerce considers it a failure. BigCommerce will keep trying for a little over 48 hours. At the end of that time, BigCommerce sends an email to the email address set during app registration and flips the is_active flag to false.

You can proactively check to make sure that everything is OK by periodically making a GET request and checking the is_active flag.

If you receive an email or discover that the is_active flag has been flipped to false, try the following:

Check to see if your app is responding to the POST request with something other than HTTP 200.

Check to make sure that your server has a valid TLS/SSL setup. One way to do this is by visiting the following website: https://sslcheck.globalsign.com. Any of the following will cause the TLS/SSL handshake to fail:

Self-signed certificate.

Host name of the certificate does not match the server’s DNS.

Your server’s key or trust store has not been loaded up with the intermediate certificates necessary to establish the chain of trust.

Once you have resolved the issue preventing the connection, send a PUT request to flip the is_active flag back to true. This will cause BigCommerce to start trying to send the POST requests to your callback URI again.

Not Receiving an HTTP 201 Response after Sending POST to Create Webhook

After sending a POST request to create a webhook, you should get an HTTP 201 back. If you do not, check your TLS/SSL setup and the HTTP header in your request. The requirements for the HTTP header are discussed in the introduction above.

Tools for Debugging and Testing Webhooks

We recommend these diagnostic tools:

RequestBin

While planning your integration, RequestBin is a very helpful tool for viewing the webhooks that we send, without much setup. In seconds, you can start seeing the webhooks we are firing, and their data.

ngrok

As you are building your integration, you might want the abilty to test webhooks on your dev machines.

We suggest using ngrok, which you can use to easily set up tunnels between a server running on localhost and a public URL.

This will enable you to send our webhooks to your localhost environments via a public URL. No production push is required.

Webhooks Reference

The Webhooks object, and endpoints, register and manage webhooks that connect events from a store to external URLs.

Webhook Object – Properties

Name

Type

Description

id

int

A read-only value that uniquely identifies a webhook object. Do not attempt to set this value in a PUT or POST.

client_id

string

The OAuth client ID that uniquely identifies your application. BigCommerce returns this name-value pair in the JSON body of its responses.

store_hash

string

The hash value that uniquely identifies the store. Your application does not need to set this value via the JSON object; instead, you pass it in the path of your API requests.

scope

enum

The events that the webhook listens on. The full list of possibilities is in this overview.

destination

string

The fully qualified URI that BigCommerce uses as a callback. At runtime, when there is an event that your webhook is listening on, BigCommerce will send a POST request to this URI. Must be HTTPS.

headers

object

Optional name-value pairs that you can set when you create the webhook. At runtime, BigCommerce will include the name-value pair(s) in the HTTP header of its POST request to your callback URI.

is_active

boolean

Can contain one of three values: true, false, or <blank>. Default is no value, i.e., <blank>. If false, the webhook is inactive and will not send POST requests to the callback URI when an event occurs. If true, the webhook is active.

FAQ – App Submissions

Below are answers to several common questions about submitting apps to BigCommerce.

What kind of apps can I submit?

You can build any kind of app to test the capabilities of the platform. For inclusion in the App Marketplace, we’re looking for apps that that make online retail better and help our merchants to sell more.

Apps should target one or more of the following categories:

Accounting

Advertising

Analytics

Cloud integration

Customer feedback

Drop shipping

Email marketing

Live chat

Marketing

Merchandising

Mobile

Multichannel listing

Order fulfillment

Order management

Point of sale

Product review

Shipping

Shopping comparison

Social media

Split testing

How does the approval process work?

Upon receiving an app submission, we review it to make sure that it meets our requirements. We will contact you directly if we require further information. When the app is approved, it instantly becomes available in the App Marketplace.

Is the API rate limit per-store or per-app?

OAuth requests are rate-limited per store. A single store’s quota applies to all OAuth apps connecting to that store. Our OAuth rate limiting algorithm is designed to distribute quotas fairly across multiple apps, so that a single greedy app cannot consume the entire quota on its own.

Do apps need to make special considerations for certain browsers?

What if I need to update my app after App Marketplace submission/acceptance?

You can modify your app at any time within My Apps, free of charge. As soon as you click Update & Close, your changes will be live. Therefore, we recommend creating a copy of your app and using this to test the changes first. Once you have made sure that they work properly, you can go ahead and modify your production app.

Will BigCommerce host my server-side code?

No. BigCommerce does not support the upload of server-side code to a store. The server-side code must hosted elsewhere. The storefront can use JavaScript to access it.

FAQ – API Request/Response Troubleshooting

Below are steps to resolve several common API errors.

Why am I getting 4XX/5XX errors from the API?

A 401 error indicates that your API call is being received, but isn’t properly authenticating with our API. Either credentials are absent from the request, or we are receiving invalid credentials. Steps to resolve this:

Double-check your Access Token and Client ID.

If your credentials are valid, try sending a cURL request with the same credentials. This will test whether the problem is something within your application, rather than a credentials issue.

For 403 errors , there are 4 common causes:

Your app lacks the appropriate scopes to make the request that it sent. Resolution: Check the OAuth scopes that you requested, either in control panel > API Accounts or in Developer Portal’s My Apps section.

The store-owner account has changed on a store that installed your app. Resolution: This might require a reinstall by the new store owner, or a rollback of the store-owner changes.

Your API request exceeded an enforced platform limit. Among other limits, each store is limited to a maximum of 30,000 brands and 16,000 categories. For more information about these limits, see either the API resource you are using or our support documentation on platform limits.

500 errors can also be caused by particularly expensive API calls. To avoid these errors on stores with very complex data, try reducing how many objects you are requesting. In the v2 API, you can request fewer objects by using ?limit={count}. In either the v2 or v3 API, you can request fewer objects by excluding certain fields, or only requesting certain fields.

Why am I having trouble authenticating my app with a store?

When you first install your draft application into a store, we send the Auth Callback Request to the Auth Callback URI that you specified when you registered your app in Developer Portal’s My Apps section. Your application should receive and handle the GET request that we send to this registered URI. Your server’s response to the Auth Callback Request is what we display in the BigCommerce control panel’s iframe during app installation.

After you have successfully generated an API token, based on the details that we sent you in the Auth Callback Request, your app is considered installed.

Once you have refreshed the page and “launched” your app, this will trigger a Load Callback Request to the Load Callback URI that you specified during the app registration. The Load Callback Request is also a GET request. Your server’s response to the Load Callback Request is what we will then display in the iframe.

If either the Auth Callback or the Load Callback fails, the app will appear not to be installed, or it will fail to authenticate. You can review our “Hello World” Single-Click App examples to see how we’ve handled this workflow.

Why am I getting an HTTP 204 or 301/302 response to an API request?

Double-check the URL to which you are making an API request. If the response code is 301/302, try the WWW or non-WWW version of the URL.

Best Practices – BigCommerce API Calls (in General)

For trouble-free high performance, BigCommerce recommends building apps and scripts according to the following guidelines:

Build with OAuth authentication

While the BigCommerce control panel still allows the creation of “Legacy API Accounts” (Basic Authentication credentials), we discourage using this option. We strongly recommend that you instead build integrations against the OAuth authentication method.

OAuth offers several additional features – including using v3 API endpoints, registering webhooks, and maintaining separation of concerns via scopes. Just as importantly, BigCommerce plans to deprecate the Basic Authentication option.

Ensure that your integration is up-to-date

BigCommerce frequently enhances its core product, and is actively developing v3 API endpoints. By using the newest API version, you will ensure that your app has access to the latest resources. You will also be better positioned to provide a user experience consistent with what merchants will see in their BigCommerce store’s control panel. The newest API endpoints (primarily from v3) will also provide additional features or considerations, which we incorporated based on feedback about the v2 API.

If you would like to stay informed about the latest API updates, please subscribe to our developer newsletter in the sidebar, and join our partner program.

Use webhooks effectively within your application

To keep data in your application up-to-date, webhooks provide a great alternative to doing periodic checks. In order to register a webhook that your application can listen for, you will need to use OAuth (not legacy “Basic Authentication”).

A limited number of webhooks are available, generally covering when an object is created (store/order/created) or updated
(store/order/updated). BigCommerce will send only a partial payload with these webhooks, so this payload will need to trigger your application to make a subsequent request to the API, based on the identifier (such as the order ID included in the webhook payload).

Thread your requests to the BigCommerce API

In order to quickly update information in the API, you can use threaded requests. The BigCommerce Ruby API client is thread-safe: It satisfies the need for multiple threads to access the same shared data, and the need for a shared piece of data to be accessed by only one thread at any given time. These attributes can reduce the total time that your app will require to complete a series of requests.

Best Practices – BigCommerce Marketplace Apps

BigCommerce recommends building Marketplace apps according to the following further guidelines:

Support multi-user access

Merchants often have more than one person working with them on their store. BigCommerce allows such additional users to access your app when the store owner has granted them appropriate permissions. The requirements for supporting multi-user access are:

Tokens must be stored against the store hash and not against user info.

In the payload, users are distinguished by owner_email versus user_email. If these two emails match, the user is the store owner.

If you wish to enable user removal, you can do by filling in the app’s Technical > Remove User Callback URL field. (Enabling user removal is optional.)

For more advanced implementations, you can enable the store owner to grant specific permissions to different non-admin users. For example, person1@email.com could be restricted to editing product inventory but not seeing orders. If you decide to include this feature in your app, it’s a great feature to advertise.