NAV

API Documentation

The BigCommerce Stores API features a RESTful architecture, allowing you to code in the language of your choice. This API supports the JSON media type, and uses UTF-8 character encoding.

With clever use of this API, you can automate various commerce, business, and publishing tasks, and can integrate all kinds of apps with our platform.

All connections require authentication, and are secured by TLS encryption.


We currently support two generations of our API:

API v3 Documentation

New Catalog/Customers/Orders API, with more-efficient variant/modifier model. OAuth-only, but fully backward-compatible with v2.

View v3 Docs

When a resource is availabe in the V3 API we recommended using that resource.

API v2 Documentation

View v2 Docs

App Quick Start

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

  1. Log in at Developer Portal’s top right.

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

  1. Click My Apps.

  2. Click Create an app.

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

  4. Click Next.

  5. Click Next again.

  6. Click Next one more time.

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

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

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

  10. 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.

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

  12. Click Update & Close.

  13. Back in My Apps, hover over your app.

  14. Click View Client ID.

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

Becoming a Partner

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.

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. To be approved as a partner, you will need:

Once approved, you will receive one or more emails listing your partner credentials and next steps. Your Partner ID will be required to submit your app for App Marketplace consideration. If you do not receive these credentials by email, please contact partnersupport@bigcommerce.com.

Types of Apps We Are looking for

We are looking for all kinds of apps. We want technology that provides an outstanding user experience for BigCommerce Merchants.

Getting a Sandbox Store

To build a Marketplace app or hidden app, you will need to have a sandbox store, a developer account at devtools.bigcommerce.com and be accepted as a BigCommerce partner. This account is separate from the account created when signing up for the store. A sandbox store cannot process transactions and is for developing and testing apps without the 15-day time time limit of a trial store.

Create a Sandbox Store

  1. Navigate to the BigCommerce Pricing page.
  2. Select START YOUR FREE TRIAL.
  3. Where prompted for an email address, enter the same email that you used when applying to become a Technology Partner.
  4. Select START YOUR TRIAL.
  5. In the trial store setup form, enter a store name, password, and other details. Then select CREATE YOUR STORE.
  6. Navigate to your Partner Portal > Support > Create a Case > Issue Type = Portal and Membership. In the case description, enter your new sandbox store’s friendly URL (for example: http://your-store-name.mybigcommerce.com) and request conversion to a Sandbox. We will flag this as a sandbox store. This will ensure your continued access to the store, as opposed to the normal 15-day trial. This can take around two days.
  7. When you log into your new store, use the same email that you used at step 3 above.

App Store Approval Requirements

Prerequisites

Make sure you’ve applied and been approved for our Technology Partner Program before you’re ready to submit your app - you’ll need a valid Partner ID to do so. You’ll also need to accept the Terms & Conditions in the Partner Portal before we can publish your app.

General Requirements

Listing Requirements

Name

App Images

Pricing & Categorization

App Details

Partner Information

Installation

Functionality

Recommendations

Technical

You will have already provided much of the information during the initial app registration. 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. Also, 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.

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

Submitting your App

Our submission guidelines aim to protect the merchant experience and to provide enough structure for you to develop apps efficiently and effectively. Before submitting your app, please be sure to carefully review the App Requirements, to avoid having your app rejected and going through resubmission. A fee of $99 is required for each submission. If the app is rejected you will be charged for a new submission. You can submit an app through the Dev Portal.

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.


Troubleshooting

Are all fields required?

While not all fields are required to publish edits for your listing, they are all highly recommended. Without filling in all fields, your listing will be missing information that merchants have seen on other listings and expect to see throughout the Marketplace.

I’ve logged in to the Developer Portal, but I don’t see my published listing. Where is it?

You may be logged in with the wrong account. Each listing can only be owned by one user, so it is likely assigned to another email address. If you’re unable to track down the correct owner account for your solution, please reach out to appstore@bigcommerce.com.

I saved my changes, but my listing detail page on BigCommerce.com/Apps has not updated yet. What’s the problem?

The changes will be effective immediately in your control panel app card, but the updates can take up to 24 hours to appear on the public BigCommerce Marketplace. Feel free to use this as a grace period to make additional edits as needed.


Types of Apps

Single-Click Apps

Single-Click Apps are listed in our App Marketplace and are made available for installation on all BigCommerce stores. The “single-click” app flow does not mean users install the app in a single click, but instead, the app does not require the customer to install OAuth credentials themselves or configure any settings for a third party service.

To put an app on the Marketplace, you must first be a BigCommerce partner and have your app approved through the App Submission Process. After becoming a partner and having the app approved you have the option of charging merchants to use the app.

For a Single-Click App, you will need a Client ID and Client Secret from the Developer Portal.

An OAuth token is obtained in the single-click app authentication flow.

Private Apps

In some cases, you might want to 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. Use Cases:

For Private Apps you need Client ID and Client Secret from the Developer Portal. Also a OAuth token from the store’s control panel or you can request a token during the installation flow.

Hidden Marketplace Apps

[Approved partners](/api/#apply-to-the-technology-partner-program 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. To create a hidden app you need to be a BigCommerce Partner.

Use Cases:

To have an app hidden, please contact appstore@bigcommerce.com.

Scripts

You can write a script to test an endpoint, check small portions of app code you are writing, or to create an application that will not be distributed in the BigCommerce Marketplace. Scripts do not have a user interface. To get started with writing scripts all you need is an API key from the store’s Control Panel. Learn more about creating your first request with the BigCommerce API.

Connector and Other OAuth Apps

Some apps qualify to be listed in the BigCommerce App Marketplace as “Connector” apps. These apps use manual OAuth token creation instead of the Single-Click App flow.

While we always recommend and prefer the Single-Click App flow’s programmatic OAuth exchange, certain use cases might not be compatible.

Use Cases:

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:

  1. Set the App Type option to Connector.

  2. Enter your app’s Signup URL.

  3. (This is the URL where a user would begin to configure the connection between your service and the BigCommerce store.)

  4. Under OAuth scopes, select the scopes that your app requires for BigCommerce review only.

  5. (Later, you will need to instruct store users to create a token with the production scopes your app needs.)

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 to discuss your plan.


Developer Portal Walkthrough

The Developer Portal can be found by clicking My Apps in the upper right corner of the page.

App Summary

Developer Portal App Summary

Contact Name

Use the email address that was created when applying for your Partner Id.

Partner Name

List the name of your company​, as you want it to be attributed on the detail page.

Partner Website

Provide the URL for your homepage so users can learn more about your company.

Support email

Email where users can get help with the app. This should be a formal group email at your company domain (Ex: support@app-partner.com) rather than a personal email. If not provided, this option will not be displayed.

Support website

A Support email and website for users to reach out as needed. These will be publicly visible on the Marketplace, so make sure to stay away from personal emails or non-support URLs. Your public detail page will include a button for users to “Get Support,” which will take them to this URL in a new tab. If not provided, the button will not be displayed on your detail page.

Partner ID

When you’re ready to submit your listing for review, you will need to enter your Partner ID for your Technology Partner account. This field is not required to create, save, or edit a Draft prior to submission.


Developer Portal App Summary Part Two

App Name

Use the brand name you’ve given your app for your app title throughout your app content. This listing name should be a concise title for easy identification and should not include additional taglines or descriptors. The name will always appear alongside your summary, so there’s no need to muddy your app’s branding with duplicate content when that tagline is already displayed with it.

Your primary app logo should be 350 x 130px (or larger at this ratio) with a white background and dark branding in the foreground. The logo should only include branding, no taglines necessary.

Price

Select one of our pre-formatted pricing options to call out your app’s starting price. If you offer a forever-free plan, choose the “Free” option. If your app does not fit one of our options, specify your details in a few words in the “Other” selection.

App Summary

A short tagline description of your app that will be used on your app card in category and search results within the Marketplace. 128 characters max.

App Icon

Your app icon will be included on the main app detail page and the sidebar in the BigCommerce control panel once the app is installed. This should be a square 200 x 200px image.

Category

Choose the most appropriate category for your app. Take a look at the live Marketplace for an idea of where solutions are currently assigned to help decide the right category. The category selection will also be a search attribute for your listing. BigCommerce will review your category assignment and may re-categorize your listing prior to launch. One category maximum.


Details

Developer Portal Details

App Details

A more in-depth value proposition for your listing, including how your solution works, why your solution stands out in its category, and why a merchant should choose you over other competitors. Avoid using fluff or buzzwords, as this field will not be indexed for search. 200 words max recommended.

Videos

Include videos that highlight the purpose and value of your solution. Select the video hosting platform (YouTube or Vimeo) and enter the video ID.

Video Best Practices

YouTube

Turn off ads for any videos you’ve already uploaded.

  1. Sign in to YouTube.

  2. In the top right, click your account icon > Creator Studio​.

  3. On the left, select Video Manager​.

  4. Select the video(s) where you want to turn ads off.

  5. Click Actions > More actions > Monetization​.

  6. Select Off​.

  7. Click Submit​.

Vimeo

Per Vimeo’s guidelines, businesses may not use Basic or Plus accounts to host videos. If you want to upload commercial videos, you must use Vimeo PRO or Business. Commercial content includes:

Videos promoting or representing a for-profit business or brand Videos containing any form of advertising Videos hosted on behalf of a business (i.e., uploaded to Vimeo and embedded on your company’s website) Product demos and tutorials

Note: Ads appear to viewers based on their level of Vimeo membership - not yours. Basic and non-logged in viewers may see ad banners below the video player.

Case Studies

These can either be “Thought Leadership” case studies and/or traditional case studies that demonstrate how BigCommerce merchants have benefited from using your solution with their business. Use the + ​icon to add a case study, and the x ​icon to remove. Four case studies maximum.

Features

Use these fields to enumerate the major features your platform or solution has to offer. Include a brief title for each feature, and a description of the feature to accompany it. The feature title will be search indexed in the Marketplace, so be specific with your feature names and include major functions potential users will search for. Use the + ​icon to add a feature, and the x ​icon to remove. Utilize the rich text editing of these fields to bold, underline, or italicize copy as needed. Up to five features can be added.


Legal International Help Guides

Links to your privacy policy and terms of service. This requirement is in place due to legal liability​ and is non-optional​.

International Optimization

Please add the countries for which your solution is optimized and those which your solution does not currently support.

Help Guides

Links to your User and Installation Guides as a reference for existing users and prospects. We now ask that you include links to your solution’s user installation guide (PDF, support articles, etc.) and standard user guide for prospective users to review before installation. If you do not submit links, this field will not be displayed on your listing detail page, however we highly recommend including these with your submission.

App Screenshots

App Screenshot

Add screenshots of your solution’s functionality or user interface as it appears when integrated with BigCommerce so users know what to expect.

Your alternate logo will be used if your app is featured on the homepage carousel of the Marketplace. This image should be 259 x 158px (or larger at this ratio) with a dark background and white or light branding in the foreground. The logo should only include branding, no taglines necessary.


Technical

Technical Step 3

Multiple Users

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:

App Type

Select the type of app. We recommend Single Click Apps although some qualify to Connector Apps.

Callback URLS

You must have an Auth Callback URI and a Load Callback URI to register your app.

Public URIs Required before Submission

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.

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

Scope

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: - Modify the scopes of your app in My Apps and save the changes. - Obtain the new OAuth token during the App Installation or Update flow. - Retest your app to make sure it still functions properly with the new token.

Add in any instructions needed to test the app thoroughly.

Test Instructions


Review

Review

Review the information added before submitting the app. Look over this page carefully, once the app is submitted, if it is rejected there will be another fee for submission.


Preview

Review

This is an approximation of what the app’s page will look like in the BigCommerce Marketplace.


Payment & Submission

Review

At this point you make sure the information has been filled out completely and the app has been thoroughly tested before submitting for review. Updates to the App will not require the submission fee again.

Authenticating with OAuth

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

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.)

Creating an API account

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

  1. Log into the store, using the store owner’s username/password.
  2. Select Advanced Settings.
  3. Select API Accounts. This will display the Store API Accounts page.
  4. Select Create API Account. This will display the Create API Account page shown above.
  5. In the Name field, summarize the purpose for which you will use these credentials. (This name is for internal use only, so assign any name that you will recognize.)
  6. In the OAuth Scopes section, select at least the minimal scopes your app will require (as explained here).
  7. Select Save at the page’s lower right-hand corner.

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.

Viewing and saving OAuth credentials

Revoking an OAuth Token

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

  1. Log into the store, using the store owner’s username/password.
  2. Select Advanced Settings.
  3. Select API Accounts. This will display the Store API Accounts page, shown below.
  4. In the Actions column at right, select the trash-can button next to the account you want to delete.

Creating an API account

OAuth API Requests

To see how to quickly make initial OAuth requests using the Postman app, please see our Postman/OAuth Quickstart Guide.

Client Libraries

Official BigCommerce SDKs

BigCommerce provides and maintains the following full-featured SDKs in a variety of languages.

PHP Ruby
The official BigCommerce PHP client, with minimal external dependencies. Uses either OAuth or Basic Authentication. The official BigCommerce Ruby client. Uses either OAuth or Basic Authentication.
Python
The official BigCommerce Python client, available as a PyPi package. Uses either OAuth or Basic Authentication.

Official BigCommerce OAuth Hello World Apps

BigCommerce provides and maintains the following hello world apps in a variety of languages. These allow you to get a quick start with your OAuth app development.

Silex Sinatra
PHP RUBY
A sample app written in PHP, using Silex and Guzzle. A sample app written in Ruby, using Sinatra with
DataMapper and RestClient.


Flask OmniAuth
Python Ruby
A sample app written in Python, using Flask. A Ruby gem that allows you to authenticate using
OmniAuth.

Community-Contributed Libraries

The following libraries and tools have been contributed by our community. They’re not officially supported, but we think they’re great.

PHP Python
PHP-cURL-lib-for-Bigcommerce-API python-bigcommerce-api
laravel-bigcommerce bigcommerce-api-elixir


Ruby C#
bigcommerce_api bigcommercerestapi


Node.js .NET
node-bigcommerce BigCommerce4Net


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.

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:

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.

Auth Callback and Load Callback URIs

You must have an Auth Callback URI and a Load Callback URI to register your app.

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:

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:

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.

  1. Log in at Developer Portal’s top right.
  2. In the resulting login page, provide your sandbox store credentials.
  1. Click My Apps.
  2. Click Create an app.
  3. In the Create an App dialog, type a name for your app.
  4. Click Next.
  5. Click Next again.
  6. Click Next one more time.
  7. In the Auth Callback URL box, type your Auth Callback URI.
  8. In the Load Callback URL box, type your Load Callback URI.
  9. In the Uninstall Callback URI box, provide your Uninstall Callback URI if you have one.
  10. 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.
  11. Select the OAuth scopes that your app requires. If you do not yet know, select minimal scopes, such as Information: Read-Only.
  12. Click Update & Close.
  13. Back in My Apps, hover over your app.
  14. Click View Client ID.
  15. 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.

The following diagram illustrates the entire sequence.

UML diagram: App installation/update sequence

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

  1. Receiving the GET Request
  2. Responding to the GET Request
  3. Making the POST Request
  4. Receiving the POST Response

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:

GET /auth?code=qr6h3thvbvag2ffq&scope=store_v2_orders&context=stores/g5cd38 HTTP/1.1  
Host: app.example.com

Example – Updating Scopes

The following example requests a scope of store_v2_products, in addition to the initially requested scope of store_v2_orders:

GET /auth?code=qr6h3thvbvag2ffq&scope=store_v2_orders+store_v2_products&context=stores/g5cd38 HTTP/1.1  
Host: app.example.com

(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 one of the following HTTP headers:
Content-Type: application/x-www-form-urlencoded or Content-Type: application/json

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.

Parameters

Include values for each of the following parameters.

Parameter Description
client_id The Client ID for your app, obtained during registration.
client_secret The Client Secret for your app, obtained during registration.
code Temporary access code received in the GET request discussed above.
scope List of OAuth scopes received in the GET request discussed above.
grant_type Always use the following: authorization_code.
redirect_uri Must be identical to your registered Auth Callback URI.
context The store hash received in the GET request, in the format: stores/{_store_hash_}

Examples – Initial Installation

POST /oauth2/token HTTP/1.1
Host: login.bigcommerce.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 186

client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&code=qr6h3thvbvag2ffq&scope=store_v2_orders&grant_type=authorization_code&redirect_uri=https://app.example.com/oauth&context=stores/{STORE_HASH}
use Bigcommerce\Api\Connection;
$tokenUrl = "https://login.bigcommerce.com/oauth2/token";
$connection = new Connection();
$connection->useUrlencoded();
$response = $connection->post($tokenUrl, array(
    "client_id" => "CLIENT_ID",
    "client_secret" => "CLIENT_SECRET",
    "redirect_uri" => "https://app.example.com/oauth",
    "grant_type" => "authorization_code",
    "code" => $request->get("code"),
    "scope" => $request->get("scope"),
    "context" => $request->get("context"),
));
$token = $response->access_token;

Examples – Updating Scopes

The following examples request a scope of store_v2_products, in addition to the initially requested scope of store_v2_orders:

POST /oauth2/token HTTP/1.1
Host: login.bigcommerce.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 186

client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&scope=store_v2_orders+store_v2_products&grant_type=authorization_code&redirect_uri=https://app.example.com/oauth&context=stores/{STORE_HASH}
use Bigcommerce\Api\Connection;

$tokenUrl = "https://login.bigcommerce.com/oauth2/token";
$connection = new Connection();
$connection->useUrlencoded();
$response = $connection->post($tokenUrl, array(
    "client_id" => "CLIENT_ID",
    "client_secret" => "CLIENT_SECRET",
    "redirect_uri" => "https://app.example.com/oauth",
    "grant_type" => "authorization_code",
    "code" => $request->get("code"),
    "scope" => $request->get("scope"),
    "context" => $request->get("context"),
));

$token = $response->access_token;

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

{
  "access_token": "ACCESS_TOKEN",
  "scope": "store_v2_orders",
  "user": {
    "id": 24654,
    "email": "merchant@mybigcommerce.com"
  },
  "context": "stores/STORE_HASH"
}

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:

{
  "access_token": "ACCESS_TOKEN",
  "scope": "store_v2_orders store_v2_products",
  "user": {
    "id": 24654,
    "email": "merchant@mybigcommerce.com"
  },
  "context": "stores/STORE_HASH"
}

Load, Uninstall, and User Removal Requests

In addition to the Auth Callback URI, the App Registration wizard requests the following URIs.

Name Required? Event Discussion
Load Callback URI Yes Called when the store owner or user clicks to load your app.
Uninstall Callback URI No Called when the store owner clicks to uninstall your app.
Remove User Callback URI No Called when the store admin revokes a user’s access to your app.

Each BigCommerce request is a GET request and includes a signed payload that allows your app to:

The remainder of this entry discusses:

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.

The GET request contains a signed payload, as shown below.

GET /load?signed_payload=hw9fhkx2ureq.t73sk8y80jx9 HTTP/1.1
Host: app.example.com

Upon receiving a GET request to the Load Callback URI, your app needs to process the signed payload.

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.

GET /uninstall?signed_payload=hw9fhkx2ureq.t73sk8y80jx9 HTTP/1.1
Host: app.example.com

Upon receiving the GET request, your app will need to process the signed payload.

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.

GET /remove-user?signed_payload=hw9fhkx2ureq.t73sk8y80jx9 HTTP/1.1
Host: app.example.com

Upon receiving the GET request, your app will need to process the signed payload.

Processing the Signed Payload

Processing the signed payload involves splitting and decoding it verifying the HMAC signature, and processing the JSON object.

Splitting and Decoding the Signed Payload

The signed payload is a string containing a base64url-encoded JSON string and a base64url-encoded HMAC signature. The parts are delimited by the . character:

encoded_json_string.encoded_hmac_signature

To decode the signed payload, complete the following steps:

  1. Split signed_payload into its two parts at the . delimiter.
  2. Decode encoded_json_string using base64url.
  3. Convert the decoded JSON string into an object. See Processing the JSON object for more about this object.
  4. Decode encoded_hmac_signature using base64url.
  5. Use your client secret to verify the signature. See the next section for more details.

Verifying the HMAC Signature

To verify the payload, you need to sign the payload using your client secret, and confirm that it matches the signature that was sent in the request.

Examples
function verifySignedRequest($signedRequest)
{
    list($encodedData, $encodedSignature) = explode('.', $signedRequest, 2);

    // decode the data
    $signature = base64_decode($encodedSignature);
        $jsonStr = base64_decode($encodedData);
    $data = json_decode($jsonStr, true);

    // confirm the signature
    $expectedSignature = hash_hmac('sha256', $jsonStr, $clientSecret(), $raw = false);
    if (!hash_equals($expectedSignature, $signature)) {
        error_log('Bad signed request from BigCommerce!');
        return null;
    }
    return $data;
}
require "base64"
require "openssl"

def verify(signed_payload, client_secret)
  message_parts = signed_payload.split(".")

  encoded_json_payload = message_parts[0]
  encoded_hmac_signature = message_parts[1]

  payload_object = Base64.strict_decode(encoded_json_payload)
  provided_signature = Base64.strict_decode(encoded_hmac_signature)

  expected_signature = OpenSSL::HMAC::hexdigest("sha256", client_secret, payload_object)

  return false unless secure_compare(expected_signature, provided_signature)

  JSON.parse(payload_object)
end

def secure_compare(a, b)
  return false if a.blank? || b.blank? || a.bytesize != b.bytesize
  l = a.unpack "C#{a.bytesize}"

  res = 0
  b.each_byte { |byte| res |= byte ^ l.shift }
  res == 0
end

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.
store_hash string Unique identifier for the store.
timestamp float The time (in Unix time) when the callback was generated.

JSON Example

{
    "user":
         {
        "id":9128,
        "email":"user@mybigcommerce.com"
     },
     "owner":
          {
         "id":9128,
         "email":"user@mybigcommerce.com"
     },
     "context":"stores/z4zn3wo",
     "store_hash":"z4zn3wo",
     "timestamp":1469823892.9123988
}

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.

To opt into multi-user support:

  1. Log into My Apps.
  2. In the Technical panel > Supported Features area, select Multiple Users.
  3. In the Remove User Callback URI box, provide a Remove User Callback URI.
  4. Save and close your app.

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:

For further details, please see Load Request and Response.

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.

For further information, please see Remove User 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.

Scope GUI Name Resources Description
Content store_v2_content View and modify store content
/v2/pages
/v2/blog
/v2/redirects
/v3/widgets
store_v2_content_read_only View Site Content
/v2/pages
/v2/blog
/v2/redirects
/v3/widgets
Checkout Content store_content_checkout View and modify content on checkout pages
/v3/scripts
Customers store_v2_customers View and modify customer information
/v2/customers
/v2/customer_groups
/v3/customers/subscribers
store_v2_customers_read_only View customer information
/v2/customers
/v2/customer_groups
/v3/customers/subscribers
Customers Login store_v2_customers_login Log in any of your customers to your storefront
Access to the Customer Login API
Information & Settings store_v2_information View and modify general store information and settings
/v2/shipping/methods
/v2/shipping/zones
/v2/shipping/carrier
store_v2_information_read_only View general store information and settings
/v2/shipping/methods
/v2/shipping/zones
/v2/shipping/carrier
/v2/payments/methods
/v2/tax_classes
/v2/store
Marketing store_v2_marketing View and modify marketing information
/v2/coupons
/v2/gift_certificates
/v2/banners
store_v2_marketing_read_only View marketing information
/v2/coupons
/v2/gift_certificates
/v2/banners
Orders store_v2_orders View and modify orders
/v2/orders
/v2/order_statuses
store_v2_orders_read_only View orders
/v2/orders
/v2/order_statuses
Order Transactions store_v2_transactions_read_only View order transactions
/v3/orders/{id}/transactions
Products store_v2_products View and modify products
/v3/catalog
/v3/pricelists
/v2/option_sets
/v2/categories
/v2/options
/v2/brands
/v2/products
store_v2_products_read_only View products
/v3/catalog
/v3/pricelists
/v2/option_sets
/v2/categories
/v2/options
/v2/brands
/v2/products
Themes store_themes_manage View and modify themes
/v3/themes
store_themes_read_only View themes
/v3/themes
Carts store_cart View and Modify carts
/v3/carts
store_cart_read_only View Carts
/v3/carts
Sites & Routes This scope is for an upcoming API that is not ready for production.

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.

API Rate Limits:

Enterprise plans and Enterprise Sandboxes (Enterprise-Test): Unlimited (7mil / 30sec)

Pro plans: 80k per hour (450 / 30sec)

All other sandboxes (Dev/Partner/Employee): 20k per hour (150 / 30sec)

Plus & Standard plans: 20k per hour (150 / 30sec)

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:

    X-Rate-Limit-Time-Window-Ms: 5000
    X-Rate-Limit-Time-Reset-Ms: 3000
    X-Rate-Limit-Requests-Quota: 25
    X-Rate-Limit-Requests-Left: 6

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:

    HTTP/1.1 429 Too Many Requests
    Date: Mon, 03 Feb 2017 20:36:00 GMT
    Content-Type: application/json
    X-Rate-Limit-Time-Reset-Ms: 15000

Parse the X-Rate-Limit-Time-Reset-Ms header to determine how long you have to wait. In this case, it would be 15000 milliseconds.

Your client can sleep on the specified interval:

    $milliseconds = $response->getHeader("X-Rate-Limit-Time-Reset-Ms");
    usleep($milliseconds * 1000);

After waiting for the given number of milliseconds, you can go back to making API requests.

Making Requests in Parallel

You might wish to increase the amount of work your application can do in a given unit of time, by sending multiple HTTP requests to the BigCommerce API in parallel. This is perfectly acceptable.

However, your application should monitor the rate-limiting headers to avoid an HTTP 429 response. Methods for doing this might include:

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.

Review the guidelines under App Store Approval Requirements.

Allowing External App Installation

You might want to enable merchants to install your application from outside the BigCommerce control panel. This section provides a step-by-step guide.

Create an Install Button

First, embed an install button like the one below, at any Web location from which you’d like to enable app installation:

Image of install button

Redirect anyone who presses your button to: https://login.bigcommerce.com/app/<your-app's-client-id>/install

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.

Migrating to OAuth

This section outlines how to migrate to using OAuth authentication for your API integration.

Migrating to OAuth comes with several benefits:

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:

  1. 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.
  2. If you use one of the Client Libraries, follow the relevant guide (within the library’s documentation) for establishing an OAuth connection.
  3. 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 https://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, where abc123 is the store hash.
  4. 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.
  5. 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.

API Environment

The following sections describe the environment in which BigCommerce apps run.

Request Headers

Header Allowed Values Description Example
Accept application/json (for .json requests) application/xml (for .xml requests) The MIME type for the format you want to receive a response in. application/xml
Authorization Basic The user credentials for accessing the API Basic YWRtaW46cGFzc3dvcmQ=
Content-Type application/json (for JSON requests) application/xml (for XML requests) 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.

Response Headers

Header Possible Values Description Example
Date An RFC 2822 date. The date the response was sent. Tue, 15 Nov 2011 12:45:26 GMT
Last-Modified An RFC 2822 date. The date the resource was last modified. Please refer to the individual resource pages for support for this header. Tue, 15 Nov 2011 12:45:26 GMT
Content-Type application/json (for JSON requests) application/xml (for XML requests, or if no extension is supplied) The MIME type of the response, dependent on the extension of the endpoint that was requested. application/json
Content-Location A URI. Sent if the request was redirected. /api/v2/orders/5.json
WWW-Authenticate Basic Indicates the authentication scheme that should be used to access the API. Sent with a 401 Unauthorized response if HTTP Basic Authentication credentials weren’t supplied. Basic
Location A URI The URI of a newly created resource. Sent with a 201 Created response. /api/v2/products/7
X-Retry-After An integer Rate limited response, indicating the number of seconds before the quota refreshes. See the OAuth rate limits documentation for more information. 15
X-BC-ApiLimit-Remaining An integer The number of API requests remaining for the current period (rolling one hour). See the Basic Auth rate limits documentation for more information. 987
X-BC-Store-Version A version number 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.)

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.

The priority in which these methods are processed is outlined below:

  1. Accept header high-priority types (eg. Accept: application/xml) extensions on the resource (e.g.: customers.xml).

  2. Accept header low priority types (priorities less than 1, e.g.: Accept: application/json;q=0.9).

JSON

JSON has a content type of application/json.

Request Structure

The body of a JSON request is simply an object containing a set of key-value pairs. A simple representation of a product object is:

{
     "id": 5,
     "name": "iPod",
     "description": "A portable MP3 music player."
 } 

Response Structure

Responses are structured similarly to requests. If a request returns a single object, then the response will contain a single object, containing the fields for that resource.

The response will also contain links to any sub-resource – for example, images on the product below:

{
  "id":1,
  "name":"[Sample Product] iPod Shuffle",
  "sku":"IPOD-SHUFFLE",
  "description":"The world’s smallest digital music player, ...",
  "date created":"Mon, 12 Jan 2009 10:22:39 +0000",
  "categories":[
    2,
    3
  ],
  "date modified":"Sun, 28 Aug 2011 23:08:56 +0000",
  "custom url":"\/products\/sample-product-ipod-shuffle.html",
  "brand":{
    "url":"https:\/\/www.example.com\/api\/v2\/brands\/1.json",
    "resource":"\/brands\/1"
  },
  "images":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/images.json",
    "resource":"\/products\/1\/images"
  },
  "discount rules":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/discountrules.json",
    "resource":"\/products\/1\/discountrules"
  },
  "configurable fields":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/configurablefields.json",
    "resource":"\/products\/1\/configurablefields"
  },
  "custom fields":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/customfields.json",
    "resource":"\/products\/1\/customfields"
  },
  "videos":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/videos.json",
    "resource":"\/products\/1\/videos"
  },
  "skus":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/skus.json",
    "resource":"\/products\/1\/skus"
  },
  "rules":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/rules.json",
    "resource":"\/products\/1\/rules"
  },
  "option_set":{
    "url":"https:\/\/www.example.com\/api\/v2\/optionsets\/15.json",
    "resource":"\/optionsets\/15"
  },
  "options":{
    "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/options.json",
    "resource":"\/products\/1\/options"
  },
  "availability":"available"
}

If the request returns more than one result, then the response will consist of an array of objects for each result:

[
  {
    "id":1,
    "name":"[Sample Product] iPod Shuffle",
    "sku":"IPOD-SHUFFLE",
    "description":"The world’s smallest digital music player, ...",
    "search_keywords":"",
    "availability_description":"",
    "is_price_hidden":false,
    "price_hidden_label":"",
    "categories":[
      2,
      3
    ],
    "date_modified":"Sun, 28 Aug 2011 23:08:56 +0000",
    "bin_picking_number":"",
    "custom_url":"\/products\/sample-product-ipod-shuffle.html",
    "brand":{
      "url":"https:\/\/www.example.com\/api\/v2\/brands\/1.json",
      "resource":"\/brands\/1"
    },
    "images":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/images.json",
      "resource":"\/products\/1\/images"
    },
    "discount_rules":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/discountrules.json",
      "resource":"\/products\/1\/discountrules"
    },
    "configurable_fields":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/configurablefields.json",
      "resource":"\/products\/1\/configurablefields"
    },
    "custom_fields":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/customfields.json",
      "resource":"\/products\/1\/customfields"
    },
    "videos":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/videos.json",
      "resource":"\/products\/1\/videos"
    },
    "skus":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/skus.json",
      "resource":"\/products\/1\/skus"
    },
    "rules":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/rules.json",
      "resource":"\/products\/1\/rules"
    },
    "option_set":{
      "url":"https:\/\/www.example.com\/api\/v2\/optionsets\/15.json",
      "resource":"\/optionsets\/15"
    },
    "options":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/1\/options.json",
      "resource":"\/products\/1\/options"
    },
    "availability":"available"
  },
  {
    "id":2,
    "name":"[Sample Product] iPod Nano",
    "sku":"",
    "description":"Color isn't the only brilliant new iPod Nano feature. ...",
    "date_created":"Mon, 12 Jan 2009 10:28:58 +0000",
    "brand_id":1,
    "view_count":11,
    "page_title":"",
    "meta_keywords":"",
    "meta_description":"",
    "layout":"product.html",
    "is_price_hidden":false,
    "price_hidden_label":"",
    "categories":[
      3
    ],
    "date_modified":"Thu, 18 Aug 2011 05:42:15 +0000",
    "bin_picking_number":"",
    "custom_url":"\/products\/sample-product-ipod-nano.html",
    "brand":{
      "url":"https:\/\/www.example.com\/api\/v2\/brands\/1.json",
      "resource":"\/brands\/1"
    },
    "images":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/images.json",
      "resource":"\/products\/2\/images"
    },
    "discount_rules":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/discountrules.json",
      "resource":"\/products\/2\/discountrules"
    },
    "configurable_fields":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/configurablefields.json",
      "resource":"\/products\/2\/configurablefields"
    },
    "custom_fields":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/customfields.json",
      "resource":"\/products\/2\/customfields"
    },
    "videos":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/videos.json",
      "resource":"\/products\/2\/videos"
    },
    "skus":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/skus.json",
      "resource":"\/products\/2\/skus"
    },
    "rules":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/rules.json",
      "resource":"\/products\/2\/rules"
    },
    "options":{
      "url":"https:\/\/www.example.com\/api\/v2\/products\/2\/options.json",
      "resource":"\/products\/2\/options"
    },
    "availability":"available"
  }
]

XML

XML has a content type of application/xml. All XML transactions begin with the standard XML declaration:

<?xml version="1.0" encoding="UTF-8"?>

Request Structure

The body of an XML request should first contain an element that is named according to the resource, in singular form, such as product for the products resource:

<?xml version="1.0" encoding="UTF-8"?>
<product> 
</product>

The resource element should then contain a set of elements that match the fields described in that resource’s documentation:

<?xml version="1.0" encoding="UTF-8"?>
<product>
    <id>5</id>
    <name>iPod</name>
    <description>A portable MP3 music player.</description>
</product>

Response Structure

To receive an XML response, the request URI should include an .xml extension, as shown here:

GET /customers/1.xml

Here is a corresponding response:

<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <id>1</id>
  <company>BigCommerce<company>
  <first_name>Mister</first_name>
  <last_name>Big</last_name>
  <email>mister.big@bigcommerce.com</email>
  <phone></phone>
  <date_created>Tue, 16 Aug 2011 23:15:07 +0000</date_created>
  <date_modified>Tue, 16 Aug 2011 23:16:37 +0000</date_modified>
  <store_credit>0.0000</store_credit>
  <registration_ip_address>10.1.1.102</registration_ip_address>
  <customer_group_id>0</customer_group_id>
  <notes>NULL</notes>
  <addresses>
    <link rel="resource" href="https://www.example.com/api/v2/customers/1/addresses.xml">/customers/1/addresses</link>
  </addresses>
</customer>

If the request returns more than one result, then the response will consist of an element named according to the resource, in plural form, which contains a set of objects for each result:

<?xml version="1.0" encoding="UTF-8"?>
<customers>
  <customer>
    <id>1</id>
    <company>BigCommerce</company>
    <first_name>Mister</first_name>
    <last_name>Big</last_name>
    <email>mister.big@bigcommerce.com</email>
    <phone></phone>
    <date_created>Tue, 16 Aug 2011 23:15:07 +0000</date_created>
    <date_modified>Tue, 16 Aug 2011 23:16:37 +0000</date_modified>
    <store_credit>0.0000</store_credit>
    <registration_ip_address>10.1.1.102</registration_ip_address>
    <customer_group_id>0</customer_group_id>
    <notes>NULL</notes>
    <addresses>
      <link rel="resource" href="https://www.example.com/api/v2/customers/1/addresses.xml">/customers/1/addresses</link>
    </addresses>
  </customer>
</customers>

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 8601 datetime 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

An object with its own set of fields.

country code

A two-character, ISO 3166-1 alpha-2 country code.

email address

A valid email address. 250 characters maximum.

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.

Want to get started sending webhooks right away? Checkout our guide on Testing Webhooks.

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

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

     Accept: application/json
     Content-Type: application/json
     X-Auth-Client: <the OAuth client id>
     X-Auth-Token: <the OAuth token>

Prerequisites

Before you can send any requests or receive any responses, you will need the following:

Creating Webhooks: Sending the POST Request

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

An HTTP 201 response indicates that the webhook was set successfully.

Please see the hooks resource and webhook object sections for more details on creating, updating and deleting webhooks.

List of Webhook Events

Orders

Name Description
store/order/* Subscribe to all store/order events
store/order/created A new order is created. It can be manual or created on the storefront
store/order/update Order is updated
store/order/archived Order is archived
store/order/deleted Order is deleted
store/order/statusUpdated Order status is changed
store/order/message/created Order message is created by customer or in control panel
{
  "scope": "store/order/statusUpdated",
  "store_id": "123456",
  "data": {
    "type": "order",
    "id": 169,
    "status": {
      "previous_status_id": 5,
      "new_status_id": 9
    }
  },
  "hash": "6923dda2313a5709b13f9b217a3acd6f8308a0c2",
  "created_at": 1535486277,
  "producer": "stores/abcdefg"
}

Products

Name Description
store/product/* Subscribe to all store/product events
store/product/deleted Product is deleted
store/product/created A new product is created
store/product/updated Events that fire this webhook are below:
Brand Changed Product Type
Category Inventory
Number Sold Availibility
Thumbnail Changed Visibility
Featured Name
Description Sort Order
Price Dimensions
Condition Tax Price
store/product/inventory/updated Product inventory is updated.
store/product/inventory/order/updated When an order is placed and product inventory is changed. If subscribed the webhook will fire for products where inventory is being tracked by sku or not.

Included in the response for store/product/inventory/order/updated is an inventory object:

value: the number of items that the inventory changed by. This can be negative if the inventory is decreased -3 or positive if an item is returned to the inventory from an order, +2

method : Will always return relative.

id: The product id

product_id: The product id

{
  "scope": "store/product/inventory/order/updated",
  "store_id": "123456",
  "data": {
    "type": "product",
    "id": 185,
    "inventory": {
      "product_id": 185,
      "method": "relative",
      "value": -1
    }
  },
  "hash": "dc475e1059f2a67a55818bea29bf6b23ebbda707",
  "created_at": 1535480603,
  "producer": "stores/abcdefg"
}

Category

Name Description
store/category/* Subscribe to all store/category events
store/category/created Category is created
store/category/updated Category is updated
store/category/deleted Category is deleted
{
  "scope": "store/category/updated",
  "store_id": "123456",
  "data": {
    "type": "category",
    "id": "19"
  },
  "hash": "9bb5584b3c28e3bb07164405626bd913c14d2209",
  "created_at": 1535487935,
  "producer": "stores/abcdefg"
}

SKU

Name Description
store/sku/* Subscribe to all store/sku events
store/sku/created A new sku is created
store/sku/updated Sku is updated
store/sku/deleted Sku is deleted
store/sku/inventory/updated
store/sku/inventory/order/updated This webhook will fire if inventory is being tracked by sku on a product. It will also fire the store/product/inventory/order/updated webhook.

Included in the response is a data object:

value: the number of items that the inventory changed by. This can be negative if the inventory is decreased -3 or positive if an item is returned to the inventory from an order, +2

method : Will always return relative.

type: Will always be sku

variant_id: Id of the variant

{
  "scope": "store/sku/inventory/order/updated ",
  "store_id": "123456",
  "data": {
    "type": "sku",
    "id": 330,
    "inventory": {
      "product_id": 184,
      "method": "relative",
      "value": +2,
      "variant_id": 364
    }
  },
  "hash": "dc475e1059f2a67a55818bea29bf6b23ebbda707",
  "created_at": 1535480603,
  "producer": "stores/abcdefg"
}

Customer

Name Description
store/customer/* Subscribe to all store/customer events
store/customer/created A new customer is created
store/customer/updated Customer is updated
store/customer/deleted Customer is deleted
{
  "scope": "store/customer/deleted",
  "store_id": "123456",
  "data": {
    "type": "customer",
    "id": 10
  },
  "hash": "4bf08f1ad81eeb460eb12f99f7fd2226b6ea0911",
  "created_at": 1535488840,
  "producer": "stores/abcdefg"
}

Store

Name Description
store/app/uninstalled Occurs when a client store is cancelled and uninstalled from the platform
store/information/updated Events that fire this webhook:
Store Name Store Address
Store Phone Number Admin Email
Order Email Display Date Format
Export Date Format Store DTS Correction
Store Time Zone Language
Default Currency Currency Token
Decimal Token Thousands Place
Currency Location Weight Measurement
Length Measurement Length Measurement
Dimensions Decimal Places Dimensions Decimal Token
Plan Name Plan Level
Store Logo Mobile Template Logo
Tax Entered With Prices Stencil Template Enabled
{
  "scope": "store/information/updated",
  "store_id": "123446",
  "data": {
    "type": "store"
  },
  "hash": "c553845e0a5e28dc8b0ea494458692a25586a294",
  "created_at": 1535489273,
  "producer": "stores/abcdefg"
}

Cart

Name Description
store/cart/lineItem/* This webhook will fire when a change occurs to line items in the cart. This can be items added to a cart, removed or updated.(Ex. change to quantity, product options or price).
store/cart/lineItem/created When a new item is added to the cart
store/cart/lineItem/updated When an item’s quantity has changed or the product options change.
store/cart/lineItem/deleted When an item is deleted from the cart
store/cart/created This webhook will fire whenever a new cart is created either via a storefront shopper adding their first item to the cart or when a new cart being created via an API consumer. If it is from the storefront, then it fires when the first product is added to a new session.(The cart did not exist before) For the API it means a POST to /carts, (V3 and Storefront API). The store/cart/updated will also fire.
store/cart/updated This webhook is fired whenever a cart is modified through the changes in its line items. Eg. when a new item is added to a cart, an existing item’s quantity is updated, when the email changes during guest checkout or an existing item is deleted, the cart is modified triggering this webhook. The payload will include the ID of the cart being updated.
This webhook is also fired along with cart created because the first product being added to an empty cart triggers an update.
- Logging into customer account after creating a cart (email is inherited from customer account email)
- Entering email address via guest checkout
-Changing the email in guest checkout
store/cart/deleted This webhook will fire whenever a cart is deleted. This is can be either when all items have been removed from a cart and it was auto-deleted or it was explicitly removed via a DELETE request by an API consumer. This ends the lifecycle of the cart. The store/cart/updated webhook will also fire when the last item is removed.
store/cart/couponApplied This webhook will fire whenever a new coupon code is applied to a cart. It will include the ID of the coupon code
store/cart/abandoned This webhook will fire whenever a cart is considered abandoned. In the BigCommerce store settings if enabled this is usually set to one hour. See Abandoned Cart.
store/cart/converted This hook fires when a cart is converted into an order, which is typically after the payment step of checkout on the storefront. At this point, the Cart is no longer accessible and has been deleted. This hook returns both the Cart ID and Order ID for correlation purposes.
{
    "scope": "store/cart/lineItem/created",
    "store_id": "12074048",
    "data": {
        "type": "cart_line_item",
        "id": "c676e997-10fc-4049-bf18-1077a062e16d",
        "cartId": "351a367f-4198-4108-996a-753ffc1bce21"
    },
    "hash": "23d6ae55d612514cbc3f79619535a184bbf10fc0",
    "created_at": 1518405112,
    "producer": "stores/ojgwnqqd0g"
}
{
    "scope": "store/cart/created",
    "store_id": "12074048",
    "data": {
        "type": "cart",
        "id": "6121f45e-e3d9-4fcf-828e-b507594a1f96"
    },
    "hash": "54eef7f35f37d770aefcb61c5d3f1df6ed0d5a31",
    "created_at": 1518403916,
    "producer": "stores/ojgwnqqd0g"
}

Shipment

Name Description
store/shipment/* Subscribe to all store/shipment events
store/shipment/created Shipment is created
store/shipment/updated Shipment is updated
store/shipment/deleted Shipment is deleted
{
    "scope": "store/shipment/created",
    "store_id": "123456",
    "data": {
        "type": "shipment",
        "id": 12,
        "orderId": "319"
    },
    "hash": "a6bc11ea25e8f389a16ee919f0c0db6d4099d7de",
    "created_at": 1534951410,
    "producer": "stores/abcdefg"
}

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.

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.

An example payload follows:

{
 "store_id":11111,
 "producer":"stores/abcde",
 "scope":"store/order/statusUpdated",
 "data":{
         "type":"order",
         "id":173331
        },
 "hash":"3f9ea420af83450d7ef9f78b08c8af25b2213637"
 }

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.

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:

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

Retry Intervals

  1. 60 seconds after the most recent failure
  2. 180 seconds after the most recent failure
  3. 300 seconds after the most recent failure
  4. 600 seconds after the most recent failure
  5. 900 seconds after the most recent failure
  6. 1800 seconds after the most recent failure
  7. 3600 seconds after the most recent failure
  8. 7200 seconds after the most recent failure
  9. 21600 seconds after the most recent failure
  10. 50400 seconds after the most recent failure
  11. 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:

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:

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.

Webhook Tester

https://webhook.site/#/


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.
created_at int The time at which the webhook was created.
updated_at int The time at which the webhook was last updated.

List Hooks

Index of registered webhooks.

Response

Example JSON returned in the response:

[
  {
    "id": 101,
    "store_hash": "5ueh97",
    "client_id": "40c672b9177b5d3a8dbfad24321be15d",
    "scope": "store/order/*",
    "headers": {
      "X-Custom-Auth-Header": "{secret_auth_password}"
    },
    "destination": "https://app.example.com/orders",
    "created_at": "2013-01-17T11:27:50+11:00",
    "updated_at": "2013-01-17T11:27:50+11:00",
    "is_active": true
  },
  {
    "id": 102,
    "store_hash": "5ueh97",
    "client_id": "40c672b9177b5d3a8dbfad24321be15d",
    "scope": "store/product/created",
    "headers": {
      "X-Custom-Auth-Header": "{secret_auth_password}"
    },
    "destination": "https://app.example.com/products",
    "created_at": "2013-01-17T11:27:50+11:00",
    "updated_at": "2013-01-17T11:27:50+11:00",
    "is_active": true
  }
]

Get a Hook

Gets a registered webhook.

Response

Example JSON returned in the response:

{
  "id": 101,
  "store_hash": "5ueh97",
  "client_id": "40c672b9177b5d3a8dbfad24321be15d",
  "scope": "store/order/*",
  "headers": {
    "X-Custom-Auth-Header": "{secret_auth_password}"
  },
  "destination": "https://app.example.com/orders",
  "created_at": "2013-01-17T11:27:50+11:00",
  "updated_at": "2013-01-17T11:27:50+11:00",
  "is_active": true
}

Create a Hook

Register a new webhook.

Requirements

The following properties of the webhooks are required. The request won’t be fulfilled unless these properties are valid.

Notes

Scopes can be specified using wildcard syntax, or the full path to an event.

Request

Example request object:

{
  "scope": "store/order/*",
  "headers": {
    "X-Custom-Auth-Header": "{secret_auth_password}"
  },
  "destination": "https://app.example.com/orders",
  "is_active": true
}

Update a Hook

Edit the details of a registered webhook.

Request

Example request object:

{
  "destination": "https://app.example.com/orders_changed",
  "is_active": true
}

Response

Example JSON returned in the response:

{
  "id": 101,
  "store_hash": "5ueh97",
  "client_id": "40c672b9177b5d3a8dbfad24321be15d",
  "scope": "store/order/*",
  "headers": {
    "X-Custom-Auth-Header": "secret_hooks_auth_password"
  },
  "destination": "https://app.example.com/orders_changed",
  "created_at": "2013-01-17T11:27:50+11:00",
  "updated_at": "2013-01-18T11:27:50+11:00",
  "is_active": true
}

Delete a Hook

Deletes a single webhook.

FAQ

This section covers:

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:

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?

Basic Authentication requests are rate-limited 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?

Yes. Please review our list of supported browsers and the documentation on user interface constraints for details.

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:

For 403 errors , there are 4 common causes:

500 errors almost always indicate an internal server error on BigCommerce’s side. Steps to resolve these:

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:

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.