API v3 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.
All connections require authentication, and are secured by TLS encryption. As of June 30, 2016, all requests must support Server Name Indication (SNI).
With clever use of this API, you can automate various commerce, business, and publishing tasks and integrate all kinds of apps with our platform.
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.
|Internet Explorer 10 or later|
For a current list of target browsers (desktop and mobile) that BigCommerce supports for storefronts using our themes, please see
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.
These codes are returned for requests that were understood and processed successfully.
|201||Created||For a successful
|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
These codes are returned for requests that have resulted in the client needing to take further action to complete the request.
|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
|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
|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
|413||Request Entity Too Large||When the client requests too many objects. For example, the
|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.
|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.,
|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.|
An integer number, with a maximum value of 2147483647. Negatives are disallowed, unless otherwise specified.
A decimal number of up to
M digits in total, including
D digits after the decimal point. Negatives are disallowed, unless otherwise specified.
A string of text up to
M characters in length.
A string of text, up to ~16,777,216 bytes in length.
A boolean value:
false. In JSON, it will be represented using the native
boolean type. In XML, it will be the literal strings
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.
An enumeration of string values. The only allowed values are those specified in the field’s description.
An object with its own set of fields.
A valid email address. 250 characters maximum.
Variable data, depending on context. See the field definition for specifics.
A simple list of values. In JSON, this will be an array. In XML, the field will contain a set of
A string representing a URI reference to another resource within the current version of the API.
A null value. In JSON this is represented as the native
null type. In XML, it is represented as the literal string
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:
- Cloud integration
- Customer feedback
- Drop shipping
- Email marketing
- Live chat
- Multichannel listing
- Order fulfillment
- Order management
- Point of sale
- Product review
- Shopping comparison
- Social media
- Split testing
How does the approval process work?
Upon receiving an app submission, we review it to make sure that it meets our requirements. We will contact you directly if we require further information. When the app is approved, it instantly becomes available in the App 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?
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?