NAV
Subscribe to developer updates

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.

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.