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. As of June 30, 2016, all requests must support Server Name Indication (SNI). We currently support two generations of our API:

API v3 Documentation

New, more-efficient catalog API, offering a simplified variant/modifier model. OAuth-only, but fully backward-compatible with v2.

API v2 Documentation

Core API, supporting all currently exposed resources via Basic Auth or OAuth.

API/Apps First Steps

The following sections list initial steps for two different development scenarios:

These two scenarios are not mutually exclusive – some developers will work under both scenarios – but some of their instructions are redundant. Please use the links above to jump to the section that best matches your immediate scenario.

Apps Quick Start: Obtaining API Credentials

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

Creating a Trial Store

  1. Go to the BigCommerce home page.

  2. Select either GET STARTED or START YOUR FREE TRIAL.

  3. Enter an email address where prompted, and select START YOUR TRIAL.

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

  5. Wait for the store-creation animation to stop, then select either FINISH or Ask Me Later.

Logging In

If you have just created your trial store, you will already be logged into the store’s control panel. Skip ahead to Creating Basic Auth Credentials.

Otherwise, you might need to log into your store:

  1. Return to the BigCommerce home page.

  2. Select LOG IN at the upper right.

  3. If prompted to Log in to your store, enter the email address and password you set when you created your trial, then select LOG IN.

    This will reopen your store’s control panel.

Creating Basic Auth Credentials

  1. From your store’s control panel, go to Advanced Settings > Legacy API Settings.

  2. Select Create a Legacy API Account.

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

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

Creating OAuth Credentials

When you log in to the BigCommerce Developer Portal to get OAuth credentials for the first time, you’ll be prompted to authorize the Developer Portal application.

  1. Select My Apps in this Developer Portals’s upper-right-hand corner, and log in to your BigCommerce account.
  2. Within the Developer Portal, select Create an app. You can give your app any name you’d like, such as Test.
  3. Once the app is created, select View Client ID. This will display the modal shown below, from which you can copy your
    Client ID and Client Secret.

BigCommerce Client ID and Secret

Making an API Request

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

Joining the BigCommerce App Marketplace

Build Best-Of-Breed Solutions for Fast-Growing Online Businesses

The following sections outline the steps required to become a vendor of Single-Click Apps on the BigCommerce platform.

Apply to the Technology Partner Program

Before you can submit an app to the BigCommerce Marketplace, you must become an official Partner. BigCommerce offers app developers free sandbox stores through its Technology Partner Program. You can apply for a technology partnership here. To be approved as a partner, you will need:

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

Create a Sandbox Store

To open your sandbox store, log into the Partner Portal, then click Create a Trial Store.

When you log into your new store, use the same email that you used when applying to become a Technology Partner.

NOTE: Although the Create a Trial Store option’s name indicates that the store might be temporary, it is actually permanent.

Create Your Draft App

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

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

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

Submit Your App

Once your app is fully functional, and meets all of BigCommerce’s approval requirements, submit the app from My Apps. We will get back to you as soon as we have reviewed your submission.

About Client Libraries

To make facilitate app development on the BigCommerce platform, we provide client libraries in a variety of popular programming languages.

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 both accept requests and respond in JSON or XML. Requests should be encoded using the UTF-8 character set. Other character sets may 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>

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


Webhooks Overview

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

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

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.

List of Webhook Events

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.

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

Respond to Webhook Callbacks

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

Callback Retry Mechanism

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

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:

RequestBin

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

ngrok

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

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

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

Building OAuth Apps

OAuth apps (also known as public apps or Single-Click Apps) can be listed in the App Store for easy installation in all BigCommerce stores. They use OAuth to obtain an access token and to communicate with the central BigCommerce API endpoint.

About Single-Click Apps

Building an OAuth app is the recommended approach in almost all cases. BigCommerce plans to deprecate the alternative Basic Auth mechanism that currently supports private apps for individual stores.

Before you start building an app for the App Store, we suggest reviewing the App Store acceptance requirements. To start making API requests, you’ll need a Client ID and Client Secret, and an OAuth token.

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 the standard contract, 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.

App Registration

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

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

Technical Prerequisites

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

Auth Callback and Load Callback URIs

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 (ie. 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.

  3. Click My Apps.

  4. Click Create an app.

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

  6. Click Next.

  7. Click Next again.

  8. Click Next one more time.

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

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

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

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

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

  14. Click Update & Close.

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

  16. Click View Client ID.

  17. 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 (bc-oauth-install+update-seq.svg)

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

Making the POST Request

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

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

Initial Installation

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

Updates

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

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 example requests 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 Store, 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.

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

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 Store, 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 Store 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 review 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 Scope Strings Resources
Content store_v2_content blog/posts
store_v2_content_read_only blog/tags
redirects
Customers store_v2_customers customers
store_v2_customers_read_only customers/{id}/addresses
customer_groups
Customer Login store_v2_customers_login [Grants access to Customer Login API)]
Default default countries
countries/{id}/states
hooks
time
Information store_v2_information payments/methods
store_v2_information_read_only shipping/methods
store
tax_classes
Marketing store_v2_marketing coupons
store_v2_marketing_read_only
gift_certificates
Orders store_v2_orders orders
store_v2_orders_read_only orders/{id}/coupons
orders/{id}/messages
orders/{id}/products
orders/{id}/shipping_addresses
orders/{id}/order_statuses
orders/{id}/taxes
orders/{id}/shipments
Products store_v2_products brands
store_v2_products_read_only products/{id}/discount_rules
categories
products/{id}/configurable_fields
products/{id}/custom_fields
products/{id}/googleproductsearch
options
option_sets
option_sets/{id}/options
options/{id}/values
products
products/{id}/images
products/{id}/options
products/{id}/reviews
products/{id}/rules
products/{id}/videos
products/{id}/skus

Rate Limits – OAuth

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

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

The store’s overall quota is evenly distributed across all apps that are accessing that store. 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:

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-Retry-After header, specifying a time (in seconds) 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 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 2014 20:36:00 GMT
    Content-Type: application/json
    X-Retry-After: 15

Parse the X-Retry-After header to determine how long you have to wait. In this case, it would be 15 seconds.

Your client can sleep on the specified interval:

    $seconds = $response->getHeader("X-Retry-After");
    sleep($seconds);

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

App Store Approval Requirements

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 it against the following requirements, to avoid having your app rejected and needing to re-submit it:

App Approval Requirements

Types of Apps We’re Accepting

Accepting Not Accepting
Accounting Real-Time Tax
Advertising Customized Checkout
Analytics Real-time Shipping Rate updates
Cloud integration Payment Methods
Customer feedback
Drop shipping
Email marketing
Live chat
Marketing
Merchandising
Mobile
Multichannel listing
Order fulfillment
Order management
Point of sale
Product review
Shipping
Shopping comparison
Social media
Split testing

Questions? Please contact appstore@bigcommerce.com

App Submission

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

App Summary

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

Details

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

Launch Bar

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

Technical

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

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

Submitting your App

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

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

Questions? Please contact appstore@bigcommerce.com

For inspiration, take a look at some of the apps in our current App Store!

Sample Contract

Before your app can be published in the App Store, you must sign a contract. To expedite this process, we provide our standard contract below.

Questions? Please contact appstore@bigcommerce.com

Contract Text

BigCommerce provides a software and services platform to enable individuals and entities (“BigCommerce Clients”) to build their own online marketplace (collectively, such platform and products/services are referred to as the “BigCommerce Products”); andIn connection with the provision of BigCommerce Products, BigCommerce has created the BigCommerce Apps Marketplace pursuant to which certain companies may make available software applications (“Apps”) that are integrated to operate with the BigCommerce Products.

Participant has developed an App or Apps that have been approved by BigCommerce and included in the BigCommerce Apps Marketplace, and in consideration of Participant’s participation in such marketplace, Participant agrees to the terms and conditions of this Agreement, including the revenue share commission payments payable to BigCommerce as outlined in Section 2.

1. TERM AND TERMINATION; REMOVAL OF APP.

1.1. This Agreement will commence on the Effective Date and continue in full force and effect for one year, unless earlier terminated or canceled as set forth herein (the “Initial Term”). Following the Initial Term, this Agreement shall be automatically renewed for additional one year terms unless either party provides the other with written notice, no later than 90 days prior to the end of the then- current term, that it does not wish to renew this Agreement (the Initial Term and all renewal terms shall be referred to herein as the “Term”).

1.2. Either party may terminate this Agreement at any time if the other party breaches any of its obligations hereunder or there exists any failure of any warranty or representation made hereunder, and such breach or failure is not cured within thirty (30) days of written notice of such breach from the other party.

1.3. All provisions of this Agreement that by their terms or nature should survive termination or expiration of this Agreement shall so survive. Upon termination of this Agreement for any reason, Participant will continue to make the commission payments under the Revenue Share Program as set forth in Section 2 below, and such obligation shall survive, indefinitely.

1.4. Notwithstanding any other provision of this Agreement, BigCommerce may remove an App from the BigCommerce Apps Marketplace without notice at any time for any or no reason in its sole and complete discretion. In addition, BigCommerce may remove an App from the BigCommerce Apps Marketplace at any time for any of the following reasons: multiple complaints regarding an App from BigCommerce Clients, recurring bugs and/or support issues, Participant fails to promptly and comprehensively respond to and solve bugs or other support issues or any other performance issues with the App.

2. FEES FOR PARTICIPATION IN BIGCOMMERCE APPS MARKETPLACE PARTNER PROGRAM.

2.1. Revenue Share Program. Participant will pay BigCommerce a commission percentage equal to the Revenue Share Percentage as specified on the cover page hereto on Participant Sales (defined below) to BigCommerce Clients or other parties referred to Participant by BigCommerce through the BigCommerce website, platform or otherwise. “Participant Sales” means all amounts received by Participant and its affiliates from the sale of Apps, products or services, less (a) the amount of all refunds, allowances and discounts, (b) the amount of all return credits and refunds and © shipping and handling charges; provided that Participant has notified BigCommerce of any such amounts as set forth in subsections (a) through ©, in which case such amounts shall be credited in the next billing cycle.

2.2. Reports; Payment Terms. Participant agrees to provide monthly commission payment statements to BigCommerce for any fees or commissions due and owing under this Section 2 within 10 days following the end of each month. Commission payment statements shall be sent by Participant to partnerpayments@bigcommerce.com and include the following information: (a) the name of the App(s), (b) the revenue per App (i.e. Participant Sales and calculation thereof), © the total revenue for all App(s) (i.e. the total Participant Sales for all Apps), and (d) the shared client count. Payments shall be made by Participant to BigCommerce within 30 days of the end of the month in which the fee was earned. Payments shall be made by Participant either via PayPal to accounts@interspire.com or via ACH (where available). The parties agree to use good faith efforts to resolve any discrepancy between their respective records, should any occur. Each party shall be solely responsible for payment of all taxes assessed against it as a result of this Agreement and/or sales to BigCommerce Clients, regardless of which party is required to collect and remit such taxes.

3. AUDIT RIGHTS.

3.1. At any time and from time to time, both during and after the Term, BigCommerce may review, audit and make copies of, and/or have its advisors, agents, accountants and/or attorneys on its behalf review, audit and make copies of, all books and records (including without limitation any digital or electronic records) kept or maintained by Participant or on its behalf relating to transactions with BigCommerce Clients or that otherwise results in a fee payable to BigCommerce hereunder (collectively, “Participant Records”).

Participant shall maintain complete and accurate Participant Records during the Term and for a period of five years following termination or expiration of this Agreement. Participant Records not relating to transactions with BigCommerce Clients or fees payable to BigCommerce under this Agreement are not subject to audit rights set forth in this Section 3.1.

4. INTELLECTUAL PROPERTY. For the avoidance of doubt, BigCommerce owns, and will continue to own, all right, title and interest in and to the BigCommerce Products, including all accompanying worldwide intellectual property rights. Participant receives no rights in the foregoing.

5. REPRESENTATIONS, WARRANTIES AND COVENANTS.

5.1. Each party represents and warrants to the other that it has the right to enter into this Agreement and to perform its obligations hereunder.

5.2. Each party represents and warrants that (i) the execution, delivery and performance of this Agreement does not conflict in any material respect with or constitute a material breach or default of any organizational document, agreement or other writing to which it is a party, and (ii) it has all licenses, permissions and agreements necessary or appropriate to perform its obligations under this Agreement.

5.3. Participant represents and warrants to BigCommerce that Participant’s Apps, products and services and other items provided to BigCommerce or any BigCommerce Clients do not and will not (i) infringe on any third party’s copyright, patent, trademark, trade secret or other proprietary rights or right of publicity or privacy; (ii) violate any applicable law, statute, ordinance or regulation; (iii) be defamatory or libelous; (iv) be lewd or obscene; (v) violate any laws regarding unfair competition, anti-discrimination or false advertising; (vi) promote violence or contain hate speech; or (vii) contain viruses, trojan horses, worms, time bombs, cancelbots or other similar harmful or deleterious programming routines.

6. INDEMNIFICATION. Participant agrees, at its own expense, to indemnify, defend and hold harmless BigCommerce, its officers, directors, employees, affiliates, agents, contractors, and its attorneys from and against any claims, actions, liabilities, damages, costs or expenses, including attorneys’ fees and costs incurred in defending against third party claims based on or arising as a result of: (a) Participant’s breach of Section 5; (b) a BigCommerce Client’s dissatisfaction with Apps, goods or services provided by Participant, or as a result of any action or omission of Participant; © products liability claims related to Participant’s Apps, products or services, or (d) any action or omission of Participant constituting negligence, gross negligence, willful misconduct or fraud.

7. LIMITATION OF LIABILITY. IN NO EVENT SHALL EITHER PARTY BE LIABLE TO THE OTHER PARTY FOR ANY LOST OR PROSPECTIVE PROFITS OR FOR ANY INDIRECT, SPECIAL, EXEMPLARY, PUNITIVE, CONSEQUENTIAL OR INCIDENTAL DAMAGES, WHETHER SUCH DAMAGES ARE ALLEGED IN TORT, CONTRACT OR ANY OTHER CAUSE OF ACTION. The foregoing limitations on liability shall not apply to Participant’s payment or indemnification obligations hereunder or a breach of Section 5.

8. CONFIDENTIALITY.

8.1. Each party agrees that it shall hold in confidence and shall not use or disclose (except as expressly allowed herein) any “Confidential Information” of the other party. For purposes of this Agreement, Confidential Information shall include all business, technical and financial information one party obtains from the other, specifically including (i) all information which is obtained from the other party and which is marked “confidential” or “proprietary”; (ii) the source code, object code, and algorithms, contained in the software and technology used by BigCommerce to provide the BigCommerce Products; and (iii) any lists of BigCommerce clients or data related thereto. However, neither party shall be obligated under this section with respect to information: (i) that is or has become generally available or known to the public through no fault of the recipient; (ii) that is developed independently by the recipient; (iii) that was rightfully received by the recipient without obligation of confidentiality from a third party; (iv) that was in the recipient’s possession prior to its disclosure by the other party; or (v) whose disclosure is required by law, provided that the recipient gives the disclosing party prompt notice of the request for disclosure, gives the disclosing party the opportunity to obtain a protective order or other remedy, and discloses only that portion of the confidential information which it is legally compelled to disclose. Neither party may disclose the terms of this Agreement to any third party other than its financial and legal advisors without the other party’s prior written consent.

8.2. Neither party may create, publish or distribute any items that reference the other party without first obtaining the other party’s written consent, which consent may be granted or withheld in such other party’s sole and absolute discretion.

9.1. BigCommerce will provide Participant with a method to contact BigCommerce for support and questions relating to the BigCommerce Products and other matters relating to this Agreement. Participants may also enter a support ticket for BigCommerce support help via their Professional Application Developer Store Account.

9.2. Participant will provide competent and timely support for all Apps and will provide assistance to BigCommerce and BigCommerce Clients to promptly resolve any identified bugs or other issues relating to the Apps. Participant consents and agrees to BigCommerce publicly posting Participant’s support contact information to BigCommerce Clients, and Participant must provide written notice to BigCommerce at least ten days prior to any change in such support contact information.

10. NON-SOLICITATION. Both parties agree not to solicit employees of the other party during the term of this Agreement and for 12 months after the effective date of the termination of this Agreement except pursuant to a general solicitation through the media or online.

11. MISCELLANEOUS.

11.1. Notices. All notices under this Agreement shall be in writing, and shall be deemed given when personally delivered, when sent by confirmed fax, when sent by confirmed e-mail, or three days after being sent by overnight courier, prepaid certified or registered U.S. mail to the address of the party set forth above, or such other address as such party last provided to the other by written notice.

11.2. Status. For all purposes of this Agreement, each party shall be and act as an independent contractor and not as partner, joint venturer, or agent of the other and shall not bind nor attempt to bind the other to any contract.

11.3. Assignment. Participant shall not have any right or ability to assign, transfer, or sublicense (whether by merger, operation of law or otherwise) any obligations or benefit under this Agreement without the written consent of BigCommerce (and any such attempt shall be void).

11.4. Waiver. The failure of either party to enforce its rights under this Agreement at any time for any period shall not be construed as a waiver of such rights.

11.5. Entire Agreement. This Agreement supersedes all proposals, oral or written, any letters of intent, all negotiations, conversations, or discussions between or among parties relating to the subject matter of this Agreement and all past dealing or industry custom. No changes, modifications, or waivers are to be made to this Agreement unless evidenced in writing and signed for and on behalf of both parties.

11.6. Severability. In the event that any provision of this Agreement shall be determined to be illegal or unenforceable, that provision will be limited or eliminated to the minimum extent necessary so that this Agreement shall otherwise remain in full force and effect and enforceable.

11.7. Governing Law. This Agreement shall be governed by and construed in accordance with the laws of the State of Texas, without regard to conflicts of law provisions thereof. Each party acknowledges that any breach of the provisions of this Agreement may cause the other party immediate and irreparable harm for which there are no adequate remedies at law and will entitle such party to seek immediate injunctive relief, in addition to any other remedies which may be available. Any litigation pertaining to the interpretation or enforcement of this Agreement shall be filed in and heard by the Federal and State courts located in Travis County, Texas.

Building Basic-Auth Apps

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

Private Apps with OAuth?

A few private apps use OAuth. These exceptions must meet the following restrictions:

The remainder of this “Building Basic-Auth/Private Apps” section applies only to Basic Authentication apps.

Making Requests

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

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

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

Obtaining an API Token

To get an API token, complete the following steps.

  1. Log into the store.
  2. Click Advanced Settings.
  3. Select Legacy API Accounts.
  4. Click Create a Legacy API Account.
  5. Type the name of the user in the Username box.
  6. Copy the contents of the API Path box and paste this value into a text editor.
  7. Copy the contents of the API Token box and paste this value into a text editor.
  8. Click the Save button.
  9. Provide the user name, API base path, and API token to the app developer using a secure channel.

Revoking App Access

To revoke app access to a store, complete the following steps.

  1. Log into the store.
  2. Click Advanced Settings.
  3. Select Legacy API Accounts.
  4. Click the gears icon in the Action column and select Edit.
  5. Click the Generate New Token button.
  6. Select the Save button.
  7. Select the check box next to the user.
  8. Click the trash can button.
  9. Click OK in the confirmation prompt.

Regenerating an API Token

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

  1. Log into the store.
  2. Click Advanced Settings.
  3. Select Legacy API Accounts.
  4. Click the gears icon in the Action column and select Edit.
  5. Click the Generate New Token button.
  6. Select the Save button.

Rate Limits – Basic Auth

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

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

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

HTTP Headers and Response Codes

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

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

X-BC-ApiLimit-Remaining: 900

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

HTTP/1.1 509
Date: Wed, 04 Dec 2013 10:36:32 GMT
Content-Type: application/json
X-BC-ApiLimit-Remaining: 0

[
  {
    "status": 509,
    "message": "The requests-per-hour limit has been reached."
  }
]

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

Working with Rate Limits

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

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

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

Caching

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

Throttling

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

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

Pause and Resume

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

Migrating to OAuth

Apps in the App Store that use Basic Authentication are now deprecated, and will eventually be sunsetted. We will contact you directly to let you know the details and the timeline of this transition. This page discusses how to migrate your public app from Basic Authentication to OAuth.

OAuth allows you to authenticate and access the Stores API on behalf of any merchant who authorizes your app. Merchants no longer have to bounce between multiple browser tabs or cut and paste API keys to install apps.

Other benefits of updating include:

How to Migrate

To update your public Basic Authentication app to an OAuth app, you will need to make the following changes:

  1. Get a Client ID and a Client Secret by registering your app.
  2. Get a permanent OAuth token as discussed in App Installation.
  3. Update your app so that it can process the signed payloads that BigCommerce sends when a merchant loads your app.
  4. Change your base paths.
  5. Update your app to observe the OAuth rate limits.
  6. Prepare your app’s UI to run within the BigCommerce iframe, once installed.

Change Your Base Paths

Apps using Basic Authentication used a path that had the store’s hash as part of the domain. Store owners provide the store hash to the Basic Authentication app using a manual copy and paste procedure.

Apps using OAuth place the store’s hash inside a context path. OAuth apps receive the store’s hash during the app installation sequence.

The following table provides a quick comparison of the syntax and example paths.

Basic Auth OAuth
SYNTAX https://store-{store_hash}.mybigcommerce.com/api
EXAMPLE https://store-g5cd38.mybigcommerce.com/api/v2/time

Rate Limiting after OAuth Migration

Rate limiting affects only high-volume applications, but there are several changes that all consumers of the API should be aware of:

cURL Quickstart Guide

This section provides some sample cURL commands, for quickstart purposes. These use Basic Authentication, so before you can issue these commands, you must generate Basic Authentication credentials by following the steps discussed here. Once you have your Basic Authentication credentials, you can issue cURL commands as listed below.

    curl --request GET \
    -H "Authorization: Basic _username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/time

If the request is made using the Authorization header, you need to encode the credentials using base64. Or, a simple way to accomplish the same task as above is:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/orders.json

Orders cURL Commands

Here are sample cURL commands to handle orders.

Get a List of Orders from the Store

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/orders.json

By default, the API request returns only 50 orders. If you want to return all the orders from the store, you must use filters, as shown in the next example below.

Get All Orders from the Store

Use the limit and page filter parameters to get a data beyond what the default query returns. Note that 200 orders is the maximum returned per page:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/orders.json?limit=200&page=1

Update an Order

Orders take many fields upon update requests. (For details, please see this documentation.) Here, we update an order using just the mandatory fields:

    curl --request PUT \
    -u "_username_:_API_key_" \
    -H "Content-Type: application/json" \
    --data-binary '{"status_id":1}' \
    https://store.mybigcommerce.com/api/v2/orders/101

Get Orders Created since a Certain Date

You can use the If-Modified-Since header to request orders that have been created after a given date:

    curl -I --request GET \
    -u "_username_:_API_key_" \
    -H "Content-Type: application/json" \
    -H "If-Modified-Since: Tue, 4 Dec 2012 00:00:00 GMT" \
    https://store.mybigcommerce.com/api/v2/orders.json

Get Coupons Associated with an Order

An order can contain coupons, which might be applied to the order to offer discounts to the customer. You can look at all the available coupons in an order as follows:

    curl --request GET \
    -u "_username_:_API_key_"\
    https://store.mybigcommerce.com/api/v2/orders/115/coupons.json

Create a Shipment for an Order

You can create a shipment for an order via the Orders > Create a Shipment endpoint. As an example, third-party shipping services can query orders from a store when the orders are created, and create shipments for those:

    curl --request POST \
    -u "_username_:_API_key_" \
    -H "Content-Type: application/json" \
    -d '{"order_address_id":15,"tracking_number":"123-123-123","items":[{"order_product_id":15,"quantity":1}]}' \
    https://store.mybigcommerce.com/api/v2/orders/114/shipments.json

Products cURL Commands

Here are sample cURL commands to handle products.

Get a List of Products from the Store

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/products.json

By default, the API request returns only 50 products. If you want to return all the products from the store, you must use filters, as shown in the example below.

Get All Products from the Store

Use the limit and page filter parameters to get data beyond what the default query returns. Note that a maximum of 200 products are returned per page:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/products.json?limit=200&page=1

Create a Product

Products have many fields. For details on the product fields allowed as part of a POST request, please see this page.

Let’s assume that we want to create a product using only the fields that are for a POST request. Here, price must specified as a string, while weight is a decimal. The is_visible flag is not mandatory, but if it is not set to true, the product would not be visible by default:

    curl --request POST \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"name":"startrek","price":19.99,"categories":[2],"type":"physical","availability":"available", "weight":0}' \
    https://store.mybigcommerce.com/api/v2/products.json

Update a Product

To update the product created above, you could use the following:

    curl --request PUT \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"name":"startrek","sku":"STREK-DVD","categories":[2,3],"inventory_tracking":"simple","inventory_level":"500", "inventory_warning":100}' \
    https://store.mybigcommerce.com/api/v2/products/id.json

Search a Product by SKU

To search by a product SKU, we could use the following code. Remember that when a product has optionset/variations defined, and if the individual options have SKUs defined, then the product SKU is overriden by the option SKUs. Currently, there are two ways to search for SKUs: GET /products?sku="something" or GET /products/skus?sku="something". The first call returns only product-level SKUs and not option-level SKUs.

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/products/skus.json?sku="abcd"

Coupons cURL Commands

Here are sample cURL commands to handle coupons.

Get a List of Coupons from the Store

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/coupons.json

Coupons can be filtered by code, type, name, min_id and max_id. Without these filters, the call returns all the coupons in the store. So for example, if we wanted to return a list of only those coupons of type=percentage_discount, we could make the following request:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/coupons.json?type=percentage_discount

For details on filter fields, please see the Coupons resource.

Create a Coupon

Coupons can be created by a POST request on the coupons endpoint. For example, if we want to create a coupon to take 50% off an order, then our coupon will have percentage_discount as the type. The applies_to field is optional, and can be used to restrict the coupon to a set of products or categories. In the example shown below, the coupon is being restricted to a set of products:

    curl --request POST \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"code":"50OFF", "type":"percentage_discount", "name":"testcoupon1", "amount":50.00, "enabled":"true", "applies_to":"{\"entity\":\"products\",\"ids\":[32]}"}' \
    https://store.mybigcommerce.com/api/v2/coupons.json

Update a Coupon

Updating a coupon is almost similar to the Create example above, except that we work off an ID via a PUT request. For example, assume that we want to change the above coupon from a 50% to a 30% discount, and that the coupon ID is 15. We can update the coupon using the following:

    curl --request PUT \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"code":"30OFF", "type":"percentage_discount"' \
    https://store.mybigcommerce.com/api/v2/coupons/15.json

Option Sets cURL Commands

Here are sample cURL commands to handle option sets.

Connect Options to Option Sets

This is currently a four-step process.

  1. Create the option.
  2. Add some values to the option.
  3. Create the option set.
  4. Create option-set options, using the options you just created.

Use the following command to create an option:

    curl --request POST \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"name":"homer simpson", "type":"T"}' \
    https://store.mybigcommerce.com/api/v2/options.json

BigCommerce returns the following, which includes an option ID:

{"id":33,"name":"homer simpson","display_name":"homer simpson","type":"T","values":{"url":"https://store.mybigcommerce.com-bwvr466.mybigcommerce.com/api/v2/options/33/values.json","resource":"/options/33/values"}}

Next, create a new option set:

    curl --request POST \
    -u "admin:key" \
    -d '{"name": "Simpson family"}' \
    -H "Content-Type: application/json" \
    https://store.mybigcommerce.com/api/v2/optionsets.json

The API returns the following, which includes an option-set ID:

{"id":27,"name":"Simpson family","options":{"url":"https://store.mybigcommerce.com-bwvr466.mybigcommerce.com/api/v2/optionsets/27/options.json","resource":"/optionsets/27/options"}}

The final step is to connect the option with the option set:

    curl --request POST \
    -u "_username_:_API_key_" \
    -d '{"option_id": "33", "display_name":"Simpson family"}' \
    -H "Content-Type: application/json" \
    https://store.mybigcommerce.com/api/v2/optionsets/27/options.json

Which yields the following:

{"id":44,"option_id":33,"option_set_id":27,"display_name":"Simpson family","sort_order":0,"is_required":false,"option":{"url":"https://store.mybigcommerce.com-bwvr466.mybigcommerce.com/api/v2/options/33.json","resource":"/options/33"}}

Building Storefront Apps

Storefront apps interact directly with the storefront. They use JWT (JSON Web Token) authentication, rather than OAuth or Basic Auth.

Customer Login API

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

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

Customer Login Token

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

Example URL

https://storedomain.com/login/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9
.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
{
"typ": "JWT",
"alg": "HS256"
}

Payload

{
"iss": "<application_client_id>",
"iat": "<issued_at>",
"jti": "<unique_string>",
"operation": "customer_login",
"store_hash": "<store_hash>",
"customer_id": "<customer_id>",
"redirect_to": "<relative_path (optional)>",
"request_ip": "<ipv4_address (optional)>"
}

Fields

Field Name Type Description
iss string Indicates the token’s issuer. This is your application’s client ID, which is obtained during application registration in Developer Portal.
iat integer Time when the token was generated. This is a numeric value indicating the number of seconds since the Unix epoch.
jti string Request ID string that must be unique across all requests made by your app. A UUID or other random string would be an appropriate value.
operation enum Must contain the string “customer_login”.
store_hash string Store hash identifying the store you are logging into.
customer_id integer ID of the customer you are logging in, as obtained through the Customer API.
redirect_to string Optional field containing a relative path for the shopper’s destination after login. Will default to /account.php.
request_ip string Optional field containing the expected IP address for the request.

Signature

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

Sample Code

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

PHP Sample

    public static function getCustomerLoginToken($id, $redirectUrl = '', $requestIp = '')
    {
        if (empty(self::$client_secret)) {
            throw new Exception('Cannot sign customer login tokens without a client secret');
        }

        $payload = array(
            'iss' => self::$client_id,
            'iat' => time(),
            'jti' => bin2hex(random_bytes(32)),
            'operation' => 'customer_login',
            'store_hash' => self::$store_hash,
            'customer_id' => $id
        );

        if (!empty($redirectUrl)) {
            $payload['redirect_to'] = $redirectUrl;
        }

        if (!empty($requestIp)) {
            $payload['request_ip'] = $requestIp;
        }

        return JWT::encode($payload, self::$client_secret, 'HS256');
    }

Python Sample

import os
import time
import uuid
import jwt


class CustomerLoginTokens(object):
    @classmethod
    def create(cls, client, id, redirect_url=None, request_ip=None):

        # Get the client_secret needed to sign tokens from the environment
        # Intended to play nice with the Python Hello World sample app
        # https://github.com/bigcommerce/hello-world-app-python-flask
        client_secret = os.getenv('APP_CLIENT_SECRET')

        if not client_secret:
            raise AttributeError('No OAuth client secret specified in the environment, '
                                 'please specify an APP_CLIENT_SECRET')

        try:
            client_id = client.connection.client_id
            store_hash = client.connection.store_hash
        except AttributeError:
            raise AttributeError('Store hash or client ID not found in the connection - '
                                 'make sure an OAuth API connection is configured. Basic auth is not supported.')

        payload = dict(iss=client_id,
                       iat=int(time.time()),
                       jti=uuid.uuid4().hex,
                       operation='customer_login',
                       store_hash=store_hash,
                       customer_id=id
                       )

        if redirect_url:
            payload['redirect_url'] = redirect_url

        if request_ip:
            payload['request_ip'] = request_ip

        token = jwt.encode(payload, client_secret, algorithm='HS256')

        return token.decode('utf-8')

    @classmethod
    def create_url(cls, client, id, redirect_url=None, request_ip=None):
        secure_url = client.Store.all()['secure_url']
        login_token = cls.create(client, id, redirect_url, request_ip)
        return '%s/login/token/%s' % (secure_url, login_token)

Ruby Sample

require 'bigcommerce'

Bigcommerce.configure do |config|
  config.store_hash = ENV['BC_STORE_HASH']
  config.client_id = ENV['BC_CLIENT_ID']
  config.client_secret = ENV['BC_CLIENT_SECRET']
  config.access_token = ENV['BC_ACCESS_TOKEN']
end

# Get a customer
customer = Bigcommerce::Customer.all(page: 1).first

# Generate token login url
puts customer.login_token

OAuth Scope

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

Redirection

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

Notes

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

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

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

Identifying Logged-In Customers Securely

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

Current Customer API

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

Example JavaScript

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

<script type="text/javascript">
function customerJWT() {  
    var appClientId = "**BC_CLIENT_ID**"; // TODO: Fill this in with your app's client ID
    var xmlhttp = new XMLHttpRequest();
    xmlhttp.onreadystatechange = function() {
        if (xmlhttp.readyState == XMLHttpRequest.DONE ) {
           if (xmlhttp.status == 200) {
               alert('Customer JWT:\n' + xmlhttp.responseText);
           }
           else if (xmlhttp.status == 404) {
              alert('Not logged in!');
           }
           else {
               alert('Something went wrong');
           }
        }
    };
    xmlhttp.open("GET", "/customer/current.jwt?app_client_id="+appClientId, true);
    xmlhttp.send();
}
customerJWT();
</script>

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

The JWT returned from this endpoint (example below) can be decoded on JWT.IO, or via any of these libraries.

Example Output

{
  "customer": {
    "id": 4927,
    "email": "john.doe@gmail.com",
    "group_id": "6"
  },
  "iss": "bc/apps",
  "sub": "abc123",
  "iat": 1480831863,
  "exp": 1480832763,
  "version": 1,
  "aud": "6sv16tfx3j5gsopm42ss5dd67g2srvq",
  "application_id": "6sv16tasdgr2b5hs5dd67g2srvq",
  "store_hash": "abc123",
  "operation": "current_customer"
}

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

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

Add-to-Cart URLs

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

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

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

Structure:

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

Example:

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

Add Specific SKU to Cart

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

Structure:

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

Example:

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

Add Specific SKU to Cart and Go Directly to Checkout

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

Structure:

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

Example:

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

Add Specific SKU, Go to Checkout, and Include Source

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

Structure:

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

Example:

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

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

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 have resulted in the client needing to take further action to complete the request.

Code Definition Purpose
301 Moved Permanently When the API routes have changed (unlikely) or if the incoming request is not secure (http) then it will be redirect to the secure (https) version.
302 Found When the resource was found at a different location. When a request to a deprecated version of the API is received, a 302 Found response will be issued to the current API version.
304 Not Modified If an If-Modified-Since header is sent in the request and the resource has not been modified since the specified date, then this response will be sent. See resource specific pages for support for the If-Modified-Since header.

4xx Client Error

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 or when the operation exceeds a limit.
* Check your app in My Apps to review the OAuth scopes you requested, and whether they support the request that you made.
* Changes to the store owner’s account can cause this error, including a change to the email address. Roll back those changes to correct this issue.
* 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 documentation of the resource in question.
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 are:
* The header specifies an unsupported content type.
* The header is missing (except with the webhooks resource, which returns a 400 in this case).
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.

FAQ

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 Store, 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 Store.

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