BigCommerce
Getting Started
About Our APIs
Overview

About Our APIs

The BigCommerce suite of APIs empowers you to create apps, automate store processes, and build headless ecommerce solutions.

If you're new to building BigCommerce apps, we recommend that you start by exploring the App Marketplace (opens in a new tab) to get a feel for what's possible.

When you're ready to play with our APIs, check out the API Request Quick Start.

Available APIs

BigCommerce has several APIs that let you manage store data, authenticate customers, make client-side queries for product information, and more.

REST Store Management APIs

BigCommerce's Store Management and Payment APIs (for example, the Catalog API) allow you to manage transactions, modify store data, and act as store administrator. Example use cases include the following:

  • Add and update products in a store
  • Update a customer's order and change the order status
  • Create a coupon
  • Manage a customer's store account details

REST Storefront API

The REST Storefront API lets you manage customer carts, checkouts, and order information client-side. Example use cases include the following:

  • Add an item with JavaScript to a shopper's cart from a Stencil storefront
  • Programmatically retrieve and display information to a customer about their recent order
  • Update the billing address of a checkout
  • Clear a customer's current cart

GraphQL Storefront API

BigCommerce's GraphQL Storefront API lets you query and mutate products, customers, and carts, then launch a checkout on a headless storefront as well as from a native storefront's frontend. Example use cases include the following:

  • Add additional product data to a Stencil storefront
  • Access customer data on the frontend of a site
  • Manage shopper's carts on a headless storefront
  • Fetch category and brand details from a store's frontend

Customer Login API

The Customer Login API lets you programmatically sign customers in to a BigCommerce storefront. Example use cases include the following:

  • Sign customers in to a BigCommerce store from a third-party account or a headless storefront
  • Enable login using credentials other than email and password, such as a phone number
  • Integrate a BigCommerce store with an SSO provider

Current Customer API

BigCommerce's Current Customer API lets you determine which customer is logged in to a storefront during a session.

  • Confirm a customer's identity in the browser
  • Validate a customer's identity to display specific information to them from an external app

API authentication and context

Make BigCommerce API requests in the context of the storefront, BigCommerce API server, or app server. Each of the following APIs listings links to its section of our Authentication and Example Requests article, which contains the base URL of the API in question.

API or Use CaseContext
GraphQL Account API, including Usersserver
GraphQL Admin APIserver
GraphQL Storefront APIstorefront
REST Store Management APIsserver
REST Storefront APIstorefront
Customer Login APIstorefront
Current Customer APIstorefront
Payments APIserver
Apps that host REST Provider APIs (provider apps)server
Apps hosted in the store control panel (single-click apps)server
Single-store frontend scriptsstorefront
Headless storefronts with backend or request proxyserver
Serverless headless storefrontsstorefront, GraphQL-only

Available store resources

ResourceDescription
CatalogThe Catalog API manages products, brands, and categories for a store.
Store InformationGet system timestamp and basic store information.
CurrencyManage currency displayed on the storefront.
GeographyGet a list of states and countries.
Tax ClassManage tax classes available on a store.
Storefront CartCreate a cart or scrape cart data from the frontend.
Storefront CheckoutCreate a checkout or scrape checkout data from the frontend.
Store Management CartCreate a cart and bypass the BigCommerce frontend.
Store Management CheckoutCreate a checkout and bypass the BigCommerce frontend.
Store Management OrdersCreate and manage orders.
Store Management Order TransactionsView order payment information.
Storefront OrdersView storefront order information.
Customers V2Manage store customers.
Customers V3Manage store customers. To learn about using Customers V3 versus V2, see the Customers Overview.
SubscribersManage newsletter subscribers.
Price ListsCreate variations of catalog pricing.
ScriptsAdd and remove scripts from storefront pages.
MarketingCreate and manage coupons, banners, and gift certificates.
Payments - Create a payment access tokenCreate an order-specific token to process a shopper's payment.
Payments - Get accepted methodsGet a list of accepted payment methods available on a store.
Payments - Get methods (deprecated)Get a list of payment gateways available on a store.
Payments - Process PaymentsProcess payments using a payment access token and accepted payment method.
ShippingCreate and manage shipping methods and zones.
Store ContentManage a store's blog posts and blog tags.
Storefront GraphQL APIQuery storefront data headlessly or from within a Stencil theme.
PagesManage a store's web pages.
RedirectsManage a store's redirects.
ThemesManage store's themes.
WidgetsProgrammatically inject content into a BigCommerce theme.
WishlistsCreate and manage customer wishlists.

Anatomy of REST Store Management APIs

The following sections describe the configuration of well-formed requests and responses to and from BigCommerce-hosted REST APIs.

Media types

A media type is the format of the request or response body. BigCommerce APIs accept requests and send responses in JSON. Encode requests using the UTF-8 character set; other character sets can have unpredictable results.

Requests

For more information about required request headers, consult the API reference for the endpoint or graph you want to use.

Standard request headers

HeaderExpected value or typeDescriptionExample
AcceptMIME typesThe MIME type format that indicates which response type the request expects. For more information, see HTTP Docs: Accept Header (MDN) (opens in a new tab).application/json
Content-TypeMIME typesThe MIME type of the request body. The API uses this value to validate and parse the request. For more information, see HTTP Docs: Content-Type Header (MDN) (opens in a new tab).application/json
User-AgentStringWe ask that you specify a user agent to identify your integration or client.PostmanRuntime/7.32.3
AuthorizationStringRequests to the Process payments endpoint and the GraphQL Storefront API use the Authorization header to authenticate. For more information, see HTTP Docs: Authorization Header (MDN) (opens in a new tab).Bearer {{storefront_token}} or PAT {{payment_access_token}}

BigCommerce-specific request headers

HeaderExpected value or typeDescription
X-Auth-TokenAPI account access tokenRequests to the REST Management, Catalog, GraphQL Admin, and GraphQL Account APIs use this header to authenticate. Some Payment endpoints also use this header.
X-Auth-ClientAPI account client IDNo longer required for any requests to BigCommerce.
X-Correlation-IdUUID in an 8-4-4-4-12 formatAn identifier unique to a set of related requests. For use on headless storefronts, excluding BigCommerce for WordPress. For more information, see Best Practices or the Headless Guide.

Request content type

When performing a request that contains a body, specify the type of content you are sending with the Content-Type header. This typically applies to PUT and POST requests.

Request structure

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

Example request body: Product object
{
 "id": 5,
 "name": "iPod",
 "description": "A portable MP3 music player."
}

Responses

Response headers

HTTP response header names are case-insensitive; see the HTTP specification on field names (opens in a new tab) for more information. For example, your application may receive x-rate-limit-requests-left rather than X-Rate-Limit-Requests-Left, so plan your implementation accordingly. Most open source HTTP clients treat headers with the appropriate case insensitivity.

Standard response headers

HeaderPossible ValuesDescriptionExample
DateAn RFC 2822 date.The date the response was sent.Tue, 15 Nov 2011 12:45:26 GMT
last-modifiedAn 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-Typeapplication/jsonThe MIME type of the response, dependent on the extension of the endpoint that was requested.application/json
Content-LocationA URISent if the request was redirected./api/v2/orders/5.json
LocationA URIThe URI of a newly created resource. Sent with a 201 Created response./api/v2/products/7
Content-EncodinggzipAllows API clients to request content to be compressed before being sent back in the response to an API request.gzip
Transfer-EncodingchunkedSpecifies the form of encoding used to transfer the resource.chunked

BigCommerce-specific response headers

HeaderPossible ValuesDescriptionExample
X-Rate-Limit-Time-Window-MsnumberShows the size of your current rate-limiting window, in milliseconds.30000
X-Rate-Limit-Time-Reset-MsnumberShows how many milliseconds are remaining in the window. In this case, 15000 milliseconds – so, 15000 milliseconds after this request, the API quota will be refreshed.15000
X-Rate-Limit-Requests-QuotanumberShows how many API requests are allowed in the current window for your client.150
X-Rate-Limit-Requests-LeftnumberDetails how many remaining requests your client can make in the current window before being rate-limited. In this case, you would expect to be able to make 35 more requests in the next 15000 milliseconds; on the 36th request within 15000 milliseconds, you would be rate-limited and receive an HTTP 429 response.35
X-Retry-AfterintegerRate limited response, indicating the number of seconds before the quota refreshes. See Rate Limits for more information.15
X-BC-ApiLimit-RemainingintegerThe number of API requests remaining for the current period (rolling one hour).987
X-BC-Store-VersionA version numberThe version of BigCommerce on which the store is running. This header is available on versions 7.3.6+. 7.3.6

Response content type

When requesting a resource that returns a body, specify the type of content you want to receive with the Accept header. Alternatively, you can supply an extension to the resource you're requesting.

The priorities with which you can process these methods are:

  • Accept header high-priority types (eg. Accept: application/json) extensions on the resource (e.g. customers.json).
  • Accept header low priority types (priorities less than 1, e.g. Accept: application/json;q=0.9)

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.

Example request: Get a category
GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/categories/{{category_id}}
Example response: Get a category
{
  "data": {
    "id": 39,
    "parent_id": 19,
    "name": "Bath",
    "description": "",
    "views": 0,
    "sort_order": 0,
    "page_title": "",
    "meta_keywords": [
      ""
    ],
    "meta_description": "",
    "layout_file": "category.html",
    "image_url": "",
    "is_visible": true,
    "search_keywords": "",
    "default_product_sort": "use_store_settings",
    "custom_url": {
      "url": "/garden/bath/",
      "is_customized": false
    }
  },
  "meta": {}
}

Support

Developer community

The developer community is a great place to get help from other developers who work on the BigCommerce platform. If you have BigCommerce-specific questions, this online forum is the best place to ask. It's also an excellent place for beginners to get assistance.

BigCommerce at Stack Overflow

Are you a more experienced developer or have a programming language-specific question? Stack Overflow (opens in a new tab) is a good place to ask questions and get help. The developer community is the best place to get answers about the BigCommerce platform.

Resources

Did you find what you were looking for?