NAV
Subscribe to developer updates

Changelog

2017

September

Version 1.9.3 of Stencil’s default Cornerstone theme is now available. For stores/themes that have enabled Stencil Optimized One-Page Checkout, this release’s checkout sequence now includes any storewide footer scripts by default. The checkout sequence’s default color contrast now matches WCAG 2.0 accessibility guidelines, and there are several new Theme Editor options for further customizing theme colors. This release also corrects display and selection bugs in the Quick View and Cart Preview modals. For details, please see the Cornerstone 1.9.3 release notes.

Our v3 API documentation’s right column now sorts sample Python requests, sample JSON requests (where provided), and sample JSON responses into separate tabs.

August

The Cart API is now available on all store plans.

BigCommerce is providing early access to a new v3 Storefront Widgets API. This API enables developers to associate content (HTML, CSS, JavaScript, Handlebars variables, and rich media) with a storefront’s display regions. This release is currently available only to partners who have opted in to participate. If you would like to apply to join this beta, please contact partnersupport@bigcommerce.com.

Version 1.9.2 of Stencil’s default Cornerstone theme is now available. This release also , along with several other display enhancements and corrections. For details, please see the Cornerstone 1.9.2 release notes.

We have expanded our v3 API documentation’s Object References to include models for all basic objects in our public v3 API. (We will continue to expand this section as we make more v3 API objects generally available.)

Our v3 API landing page now links to our public v3 API’s Swagger in YAML format, and to a collection of Postman requests. (We will expand both links’ targets as we make more v3 resources public.)

July

Version 1.9.1 of Stencil’s default Cornerstone theme is now available. This release enables product-image carousels; enables the exposure of Foundation styles (grid, panel, etc.) via Stencil’s Citadel library; enables the translation and responsive styling of several alert messages; corrects a bug that blocked JavaScript from running in custom templates; and includes other improvements and fixes. For details, please see the Cornerstone 1.9.x release notes.

To deter automated spam submission through storefront forms, we have published instructions on upgrading Stencil and Blueprint themes to incorporate reCAPTCHA v2 challenges. BigCommerce encourages all theme developers to incorporate this upgraded anti-spam protection.

Version 1.9.0 of Stencil’s default Cornerstone theme is now available. This release provides two new region tags to support the flexible placement of payments banners; adds a new Theme Editor check box to toggle on/off the display of Shop by Price facets; and reduces the size of theme bundles, by minifying two JavaScript libraries. It also corrects several display bugs. For details, please see the Cornerstone 1.9.x release notes.

Version 1.8.2 of Stencil’s default Cornerstone theme is now available. This release provides several new options for displaying products, enables the use of third-party gift certificates. and corrects the “Down for Maintenance” page’s styling. For details, please see the Cornerstone 1.8.2 release notes.

The Stencil theming platform’s new stencil push command allows theme developers (with appropriate OAuth tokens and scopes) to upload bundled themes directly to a BigCommerce store from the command line. For context and details, please see our documentation on Uploading Your Theme.

BigCommerce has added a v3 Themes API, which you can use to programmatically upload and manage BigCommerce storefront themes. For usage instructions and sample responses, please see this new API’s documentation.

BigCommerce is providing early access to a new v3 Cart API. This server-to-server API provides endpoints for creating a shopping cart on a BigCommerce store, and for modifying the cart’s contents. This release is currently available only to partners who have opted in to participate. For details, including sample requests and responses, please see the documentation.

June

BigCommerce has added a v2 Shipping Carrier Connections API, to handle the carrier-specific settings required to establish a connection to a given shipping carrier. For usage instructions and sample requests, please see this new API’s documentation.

BigCommerce has updated our v2 API to support merchants’ new control-panel option to customize Order Status labels, so as to better match their brand’s overall tone. The Order Statuses resource now provides new custom_label, system_label, and system_description fields. The Orders resource provides a new custom_status field, whose value matches the Order Statuses > custom_label property’s value. For expanded property descriptions and sample responses, please see the documentation linked above.

The BigCommerce App Marketplace now displays more-specific app categories. These new categories are intended to help merchants locate needed apps and features faster, and with greater accuracy. Please log into Developer Portal to see the new categories applied to your apps (including draft apps). If you would like to change these assignments, please contact appstore@bigcommerce.com. You can see the full list of available new categories by editing or creating an app.

The BigCommerce App Marketplace now supports “Connector” apps, which use manual OAuth token creation instead of the Single-Click App flow. For details, please see our new documentation on Connector and Other OAuth Apps.

May

As of Stencil CLI version 1.10.0, the stencil init command requires that you generate any new API accounts/tokens as OAuth. For details, please see our revised documentation starting at Creating an API Account. (For themes that you have already initialized/authorized, the
stencil start command still supports Legacy API accounts/tokens that rely on Basic Auth.)

BigCommerce now supports real-time carrier shipping methods. This new API enables third-party carriers to programatically configure shipping methods per zone, in order to provide shipping quotes during a shopper’s checkout on a BigCommerce Store.

Partners have a new option to submit Marketplace apps that are hidden. This can be useful for deploying a custom app to multiple stores, or for beta-testing before public launch. For details, please see our revised documentation on Building Apps with OAuth.

Version 1.8.1 of Stencil’s default Cornerstone theme is now available. This release adds a new “administrative bar” to Theme Editor, and to the store owner’s view of a pre-launched store. These administrative bars offer faster, more consistent navigation, along with less-obstructed views of the storefront.

April

Version 1.7.0 of Stencil’s default Cornerstone theme is now available. This release adds support for the webpack 2 JavaScript build system, whose more-efficient exclusion of unused JavaScript allows faster page loads. It also corrects several bugs that affected page display and customers’ submission of product reviews.

The Stencil themes framework has added support for more than 100 new Handlebars helpers. These new helpers offer more power in handling strings, arrays, and dates, and in performing calculations within page templates. All supported helpers are now listed on this newly combined documentation page.

We have added new documentation on External App Installation. This new article explains how you can enable merchants to install your application from Web locations other than the BigCommerce control panel, by using an Install button along with related confirmation modals and error-checking.

March

Stencil Cornerstone 1.6.3 Theme Released

Version 1.6.3 of Stencil’s default Cornerstone theme is now available. This release opens up the Order Confirmation page for certain editing options. It also corrects the escaping of HTML in product list views, and corrects several display/rendering details for Google AMP (beta) templates.

Stencil Cornerstone 1.6.2 Theme Released

Version 1.6.2 of Stencil’s default Cornerstone theme is now available. This release fixes a 1.6.1 bug that prevented price and weight values on product pages from updating when shoppers selected an option/variant.

v2 API: Shipping Zones Added, Shipping Methods Expanded

Our v2 API now provides a new Shipping Zones resource to handle shipping zones within countries. We have also expanded our v2 Shipping Methods resource to interoperate with these shipping zones.

v3 API: More-Flexible Product Option Values

Within our v3 API, we have updated several endpoints to allow more-flexible treatment of product option values:

Stencil Cornerstone 1.6.1 Theme Released

Version 1.6.1 of Stencil’s default Cornerstone theme is now available. This release adds support for Google reCAPTCHA v2, and for our Google AMP beta to accelerate mobile display. Other enhancements include category menus up to eight levels deep, switchable list versus grid display of multiple products, and faster loading of images within the active viewport. For details, please see the Cornerstone 1.6.x release notes.

Stencil Cornerstone Repo: Issues Enabled

Contributors can now open, and comment on, issues on the Cornerstone GitHub repo.

API Basics/Webhooks Documentation Reorganized

We have moved our Webhooks Reference documentation adjacent to the Webhooks Overview in our API Basics section. To make that section easier to navigate, we have also consolidated several previous top-level entries under a new API Environment heading.

Stencil Cornerstone Repo (and Local Directory) Renamed

As of March 1, 2017, BigCommerce has renamed the repository for Stencil’s base Cornerstone theme from
https://github.com/bigcommerce/stencil to https://github.com/bigcommerce/cornerstone. Earlier links referencing
https://github.com/bigcommerce/stencil (and its subdirectories) should now automatically redirect to
https://github.com/bigcommerce/cornerstone.

Also, the Cornerstone theme now installs, by default, to a local directory named /cornerstone/ rather than /stencil/. We have updated the Stencil developer documentation to reflect both changes.

Customizing Stencil Printable/Email Templates

Our documentation now includes new workarounds for customizing printable invoices, printable packing slips, and email templates for Stencil themes.

Stencil Cornerstone 1.5.3 Theme Released

Version 1.5.3 of Stencil’s default Cornerstone theme is now available. (Release notes updated here.) For stores that have enabled Optimized One-Page Checkout, this release adds options for customizing discount banners’ colors via Theme Editor. It also corrects several bugs affecting review links and other aspects of storefront display and behavior.

Stencil Marketplace Themes: Revised Setup Instructions

For Stencil themes, our documentation on Downloading/Customizing Marketplace Themes now covers required setup steps for BitBucket SSH keys. We also document a new, streamlined setup option for Marketplace themes versioned 1.10.0 and above. (These newer theme versions replace the jspm JavaScript build system with Webpack, allowing a leaner setup flow.)

February

Stencil Uninstall/Reinstall Instructions Expanded

For Stencil themes, our documentation on uninstalling/reinstalling Stencil and Node.js now includes both Mac OS–specific and Windows-specific instructions.

Blueprint Setup Instructions Updated

Our theme setup instructions for Blueprint and Developer Mode now clarify that these options are available only to stores that purchased or applied at least one Blueprint before November, 2016.

Stencil Cornerstone 1.5.2 Theme Released

Version 1.5.2 of Stencil’s default Cornerstone theme is now available. (Release notes updated here.) This release adds a Theme Editor check box to toggle the display of a GeoTrust SSL Seal in the footer. It also corrects carousel display/cropping on wide viewports, clarifies the usage of Theme Editor’s Social Media Icons controls, and corrects a bug that displayed Sign Up links even when store-account creation had been disabled in the control panel.

Postman Guide for BigCommerce APIs

For developers who want to exercise BigCommerce APIs without (or prior to) building an app, we have added a guide to using Postman with our APIs.

Stencil Repo Adds Onboard Changelog

2017-02-07: The Stencil public repository now maintains its own changelog, at:
https://github.com/bigcommerce/cornerstone/blob/master/CHANGELOG.md. (Stencil-3000; PR # 919)

Stencil Cornerstone 1.5.1 Theme Released

Version 1.5.1 of Stencil’s default Cornerstone theme is now available. (Release notes updated here.) This maintenance release corrects a duplicate Quick Search close box in mobile viewports, corrects a redundant Theme Editor horizontal scroll bar in smaller viewports, corrects carousel display/cropping on mobile viewports, and corrects a bug that displayed Gift Certificates options even when gift certificates had been disabled in the control panel.

Stencil Cornerstone 1.5.0 Theme Released

Version 1.5.0 of Stencil’s default Cornerstone theme is now available. This release adds several new options for store owners to customize their store’s appearance via Theme Editor. These options include displaying sale badges, displaying “as low as $x” pricing, and requiring customer logins for pricing and cart access. It also corrects the behavior of hashbang links (#!), and corrects the display of product options in Quick View modals. For the PR #’s/commit #’s to cherry-pick the hashbang fix, please see the Stencil framework release notes.

January

OAuth Tokens via Control Panel

The BigCommerce control panel’s new Advanced Settings > API Accounts option allows you to directly generate and revoke OAuth tokens and their associated user accounts. For details on using these new options with your apps, please see our new documentation on Obtaining OAuth Tokens.

Stencil: New template Property Replaces Deprecated template_file

BigCommerce has deprecated the Stencil themes platform’s global template_file property. Its replacement is a new template property, which returns correct page types for custom template files. To pick up this correction, you must update your Stencil CLI installation. For details and links, please see the Stencil framework release notes.

Stencil Cornerstone 1.4.2 Theme Released

Version 1.4.2 of Stencil’s default Cornerstone theme is now available. To deter spam submissions through the storefront Contact form, this update replaces the Contact template’s CAPTCHA challenge with a Google reCAPTCHA v1 challenge. For the PR #/commit # to apply this fix, please see the Stencil framework release notes.

Order Shipments > shipping_provider Usage Clarified

We have updated our documentation on the Order Shipment object, and Create a Shipment endpoint, to clarify that the shipping_provider property is effectively required in POST requests. (You should include the property, even as an empty string, to prevent the unexpected default behavior described in the documentation.)

Blog Posts > published_date Usage Clarified

We have updated our documentation on the Blog Posts object, and its POST and PUT endpoints, to clarify the usage of this API’s published_date property. Although published_date is returned as an object in responses, your POST and PUT requests should supply it as a flat date string in RFC 2822 or ISO 8601 format.

2016

December

Stencil Now Supports Optimized One-Page Checkout

2016-12-19: The Stencil framework now supports Optimized One-Page Checkout. To enable this option, you must first update your Stencil CLI installation, and then ensure that your config.json file includes the customized_checkout value. For details and links, please see the Stencil framework release notes.

Stencil Product > Ratings Count

Stencil themes’ Common Product Card Model now includes a ratings property, representing the number of customer reviews that contributed to a product’s rating value.

Stencil Documentation Additions

The Stencil themes documentation has been updated with:

Stencil Cornerstone 1.4.1 Theme Released

Version 1.4.1 of Stencil’s default Cornerstone theme is now available. This release corrects a bug that allowed JavaScript to execute in a Cornerstone storefront’s search box. For the PR #/commit # to apply this fix, please see the Stencil framework release notes.

November

Newsletter Subscriber API (v3) Added

Our v3 API now includes endpoints that your apps can use to manage store newsletters’ subscribers. For details, please see the readme on the v3 API’s repo.

Stencil Cornerstone 1.4.0 Theme Released

Version 1.4.0 of Stencil’s default Cornerstone theme is now available. This release adds support for Apple Pay, for BigCommerce Optimized One-Page Checkout, and for other new features. For details, please see the Cornerstone 1.4.x release notes. We have updated the Stencil config.json and schema.json documentation to cover new options exposed in this Cornerstone refresh. We have also added this new, Stencil-specific documentation on customizing the Optimized Checkout page.

Apple Pay Support and Styling

BigCommerce themes now support Apple Pay, on Apple-supported software/device combinations. For setup requirements and procedures, and options for styling the Apple Pay button, please see this support article.

Optimized Checkout Styling

To support Blueprint-based stores that enable BigCommerce’s Optimized One-Page Checkout feature, we have added new documentation on using custom CSS to style a Blueprint theme’s Optimized Checkout page. Linked to the same documentation is a template CSS file that you can customize for this purpose.

Web Pages API Updated

We have corrected the behavior of the Store Content > Pages API’s is_homepage property. Any API call that sets this writable property to true will now unset other instances of the property, ensuring that a store will have only one designated home page.

Currency API Added

BigCommerce has added a new Currency API. This allows your apps to manage alternate currency display options on a storefront. For details, please see the Currency API documentation.

October

Category Webhooks Added

We have added the following new webhooks, which your apps can use to create and manage product categories:

These additions are now listed in our webhooks documentation.

Web Pages API Added

BigCommerce has added a new Store Content > Pages API. This allows your apps to create, access, and delete Web [static] pages on a storefront. For details, please see the Pages API documentation.

Email Templates/Variables: New Documentation

For Blueprint Themes, a new Email Templates documentation section lists the variables available in each email template.

Store Information API Refreshed with New Fields

The Store Information API has four new fields, which handle information gathered during store signup:

For usage details, please see the Store Information API documentation.

Stencil Cornerstone 1.3.4 released

Version 1.3.4 of Stencil’s default Cornerstone theme is now available. This maintenance release standardizes the IE11 and Edge browsers’ display behavior with out-of-stock product options/SKUs.

For details, please see the Cornerstone 1.3.x release notes.

Once once you have pulled the latest code from the Stencil repo, you can access this version by checking out its tag, using: git checkout v1.3.4

September

Stencil Cornerstone 1.3.3 released

Version 1.3.3 of Stencil’s default Cornerstone theme is now available. This maintenance release standardizes the alignment of payment buttons, and provides a workaround for the IE11 and Edge browsers’ display behavior with out-of-stock product options/SKUs.

For details, please see the Cornerstone 1.3.x release notes.

Once once you have pulled the latest code from the Stencil repo, you can access this version by checking out its tag, using: git checkout v1.3.3

Shipment webhooks added

We have added the following new webhooks, which your apps can use to track when an order’s associated shipments are created, updated, or deleted:

These additions are now listed in our webhooks documentation.

Stencil Cornerstone 1.3.2 released

Version 1.3.2 of Stencil’s default Cornerstone theme is now available. This maintenance release corrects the display of YouTube videos under sitewide HTTPS, and corrects the Cornerstone Bold variation’s display of featured products.

For details, please see the Cornerstone 1.3.x release notes.

Once once you have pulled the latest code from the Stencil repo, you can access this version by checking out its tag, using: git checkout v1.3.2

August

Stencil custom templates now generally available

All Stencil stores now have the option of assigning custom layout templates to product, category, and brand pages, and to static storefront pages like the store’s home page.

To enable custom templates, theme developers must author the pages, and the merchant (or another authorized store user) must assign page mappings. For details, please see this developer documentation and this mechant-oriented article.

You can now reference Handlebars variables – and their corresponding Stencil objects and properties – in scripts injected into a store’s global footer. You access this feature through the control panel’s Storefront Design > Design Options > Scripts tab, as illustrated in this Knowledge Base article.

Blog Posts documentation updated

We have updated our Blog Posts documentation to cover several new fields, as well as the replacement of the single published_at field by a new published_date object and published_date_iso8601 field.

Store-owner changes: New support and best practices

BigCommerce now makes it possible to change store ownership without breaking any installed apps. A store’s new owner will no longer need to reinstall apps, and will not lose apps’ historical data associated with the store.

The downside of this benefit is a possibility of mismatched user information, if your app stores user data upon app installation. Therefore, your app should now associate each API token with the store hash, rather than storing it against a specific user.

We will now be sending information on the current store owner in the load callback, and you should use this as the source of truth about the store’s owner. This could be important where your app needs to determine what user is active in the app, or if your account information is based on the incoming data (such as the store owner’s email address).

“Create a Product” documentation updated

In the Create a Product endpoint’s documentation, the list of read-only properties now includes the id field.

GLOBAL “Customer Group ID” variable documented

We have added the %%GLOBAL_CustomerGroupId%% variable to the GLOBAL Variables documentation page.

Stencil theme downloads for customization

You can now download free and purchased Stencil themes from a BigCommerce store, to customize those themes.

For merchant-oriented instructions (with screenshots) on initially downloading themes via the BigCommerce control panel, please see this Knowledge Base Article.

For developer-oriented instructions on installing required dependencies and launching downloaded themes, please see this new documentation subsection.

For developers, we list different workflows for a downloaded Cornerstone theme refresh, versus downloads of other Theme Marketplace themes. To see the complete workflow for your scenario, please see our expanded Installing Stencil overview.

July

v3 catalog API in partner release

We’re excited to announce that BigCommerce’s v3 catalog API is now available to partners, for use on all production stores. This new API has been designed around two main goals:

New features include:

For key details, please see this announcement, which links to Swagger documentation on the new API.

Please also see this broader overview, which includes authentication instructions. It also provides links where we invite you to submit issues on GitHub – and use Trello to to nominate, vote on, and track future additions to our API.

Customer resource has new “accepts_marketing” field

The Customer API has a new accepts_marketing field, which records whether the customer would like to receive marketing content from this store. The new field is a boolean and is read-only, reflecting the customer’s selections on the storefront.

We have updated our Customer API documentation and example responses to include this new field.

Customer login via JWT token generation

A new Customer Login API facilitates single sign-on (SSO) by allowing your apps to programatically log customers into stores.

This API and its fields are described, with usage examples, on this documentation page. We also now list store_v2_customers_login, and link to its documentation, from the OAuth Scopes page.

Store ownership tokens – new best practices

As of July 28, 2016, BigCommerce store owners can transfer their stores’ ownership to a different user without breaking any installed apps. This change creates the potential for mismatched user information, if your app stores user data upon app installation. Therefore:

Order Shipment API refreshed with “shipping_provider”, “tracking_carrier” fields

The Order Shipment resource has been refreshed with two fields that can be used to track shipments:

We have added these fields to the Order Shipment documentation, where they now appear in sample requests/responses for endpoints that can handle these fields. You’ll also find usage guidelines, a list of allowable values for the shipping_provider field, and a linked, downloadable spreadsheet of allowable values for the tracking_carrier field.

June

bigcommerce-api-ruby gem now generally available

The bigcommerce-api-ruby 1.0.0 gem is now generally available on GitHub and rubygems.

For other client libraries/SDKs that facilitate client requests to BigCommerce’s RESTful API, please see our Client Libraries page.

June

Request for comment on proposed Cart API schema

BigCommerce requests our App Partners’ help in creating a public Cart API. We have posted an open request for comment (RFC) on our proposed Cart API schema. We invite your feedback, to ensure that this API will accommodate your needs and use cases.

So far, our draft anticipates use cases like these:

Links to the post are also available on the BigCommerce Developer forum, and on Twitter from @BigEng.

Order Shipment resource adds “shipping_provider” field

The Order Shipment resource has a new shipping_provider field, which contains the enum of the delivery service used to fulfill the shipment.

We have added this field to the Order Shipment documentation, including the sample responses for Order Shipment endpoints that can return this field.

Store Information endpoint now passes secure store URL

The Store Information endpoint now provides a secure_url field, containing the store’s secure (HTTPS) URL.

This new field facilitates the JWT (JSON Web Token) approach to login tokens. Apps and integrations will be able to generate tokens on the client side, containing a partial URL. By consuming the secure_url value, the app or integration will be able to complete the URL.

We have this new property to our documentation on the Store Information object and resource.

New variables separate raw price from currency

BigCommerce’s Blueprint themes framework now provides two new global price variables that separately handle raw price versus national currency:

The %%GLOBAL_RawProductPrice%% variable specifies a product’s raw numeric price, with no currency metadata. The %%GLOBAL_SelectedCurrencyCode%% variable specifies the currency as an ISO 4217–compliant alphanumeric code.

You can use these variables as alternatives to the %%GLOBAL_ProductPrice%% variable, which combines the numeric price with a currency token. If your theme uses microdata, these new variables facilitate two microdata best practices:

The two new variables are available in all snippets where products are available. (In general, this is anywhere that %%GLOBAL_ProductPrice%% appears). You can find them listed on this updated reference page.

May

Order Shipment resource adds “shipping_provider” field

The Order Shipment resource has a new shipping_provider field, which contains the enum of the delivery service used to fulfill the shipment.

We have added this field to the Order Shipment object’s documentation, and also to sample responses for Order Shipment endpoints that can return this field.

Stencil Cornerstone theme 1.2.1 released

Version 1.2.1 of the Stencil Cornerstone theme is now available. This maintenance release corrects a bug that allowed shoppers to add items to their cart without selecting those items’ required options. It also corrects an Internet Explorer 10–specific bug that blocked shoppers from editing cart contents and certain other functions.

For details, please see the Cornerstone 1.2.1 release notes.

Once once you have pulled the latest code from the Stencil repo, you can access this version by checking out its tag, using: git checkout v1.2.1

List Orders endpoint adds email filter

The List Orders endpoint now allows filtering by customer email address. We have added the email field to the list of filters on the List Orders reference page.

Apps can now request new auth scopes after publication

Apps for BigCommerce stores can now request new OAuth scopes after publication. To grant these new scopes, merchants no longer need to uninstall and reinstall the app.

For details (including how to make sure your apps are compatible with this new option), please see this earlier advisory.

We have updated our app registration instructions, and our app installation/update reference and diagram, to cover token exchanges that provide new scopes for installed apps.

Stencil Cornerstone 1.2 theme released; adds logo positioning

Version 1.2 of the Stencil Cornerstone theme is now available. This release allows merchants to use Theme Editor to globally align their store’s logo left, center, or right. There are also several minor bug fixes.

For details, please see the Cornerstone 1.2 release notes.

Once once you have pulled the latest code from the Stencil repo, you can access this version by checking out its tag, using: git checkout v1.2.0

Store Information endpoint adds “features” array

The Store Information endpoint now provides a features array, whose elements flag features that affect app compatibility or functionality. This array’s initial stencil_enabled (Boolean) element indicates whether a store is using a Stencil theme, as in this example:

“features”: { “stencil_enabled”: true }

BigCommerce will add other features to this array, as warranted. For details, please see our documentation on the Store Information object and resource.

Stencil custom/private theme uploads now available

Developers can now upload custom/private Stencil themes to storefronts, via the BigCommerce control panel.

For details, please see this Knowledge Base article and this troubleshooting page.

April

New API SKU Properties Available

We have updated the product SKU API to make several new properties available directly on the SKU resource. This update means that you no longer need to create a product rule in order to set these properties – you can now update them directly on the SKU:

Property Type Description
price decimal This SKU’s base price on the storefront. If this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.
adjusted_price decimal The SKU’s price on the storefront – after the product’s base price is inherited, and/or any option set or any product rules are applied. This property is READ-ONLY.
weight decimal This SKU’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
adjusted_weight decimal This SKU’s weight on the storefront – after the product’s base weight is inherited, and/or any option set or any product rules are applied. This property is READ-ONLY.
is_purchasing_disabled boolean If true, this prohibits purchasing of the SKU.
purchasing_disabled_message string The message to display if purchasing is disabled on this SKU.
image_file string The image that will be displayed when this SKU is selected on the storefront. When updating a SKU image, send the publicly accessible URL. Supported image formats are JPEG, PNG, and GIF.

You can see the new SKU schema, usage guidelines, and updated sample responses on our updated sku entry.

This update requires no immediate changes to your applications. Any existing SKU-only rules will still function as before, and will still be accessible via the API.

However, as we make SKU-only properties available directly on SKUs, BigCommerce plans to eventually deprecate the management of SKU-only properties via product rules.

Please prepare your apps for new auth-scopes options

Starting May 2, 2016, BigCommerce will enable you to change your application’s required scopes, after you have published the app. Merchants will be prompted to update the app, and to grant new scopes, the next time they load the app. You will then receive a new token with the updated scopes.

This change opens up new options for your apps. However, at a minimum, you might need to update your code, because the Auth Callback URI can now be called at times other than installation. Your app must be ready to properly interpret such calls to auth_callback_url for purposes other than initial installation.

Please read this entire advisory to ensure that your application will continue to function as expected, after we make this change.

Scopes background

When you registered your application in Developer Portal, you were required to specify an auth_callback_url, to specify a load_url, and to request some scopes. Scopes define permissions associated with a set of store resources. By granting your app access to scopes, a merchant allows you to use their store’s API.

For example, if you want to access the BigCommerce products API for your user’s store, you must request the products scope. Each merchant that installs your app must grant you access to that scope, so that you can consume their products.

The auth_callback_url is used to safely receive a token associated with the granted scopes. The load_url is used to redirect merchants to your application when they click on it from their store’s control panel.

The problem we solved

Prior to this change, you had no way to change the scopes requested by your published app. If you changed these scopes, existing installations would cease to function. This forced each merchant to uninstall, then reinstall, your app to grant you the new scopes.

What hasn’t changed?

What has changed?

Merchants will see changes only under certain conditions:

What hasn’t changed?

What has changed?

  1. Modify your handler for auth_callback_url, to account for the fact that it can now be called after your app has already been installed. If you have special, one-time initialization code that you execute during this callback, you must modify it to run that code only once per store. Note that you will get this call, with a new code, any time a merchant grants new scopes to your application.

  2. After you complete the token exchange, save the new access token. (You must save this token because the new token will be associated with the scopes that were granted.)

  3. Use the new access token to consume the store’s API.

You might have designed your application with the assumption that the auth_callback_url would be triggered only at install time. However, under the new flow, auth_callback_url will also be triggered when a merchant grants new scopes to an already-installed app.

If you rely on auth_callback_url to trigger one-time initialization workflows – like charging the customer, or sending a welcome email – be aware that requesting new scopes might unintentionally re-trigger these workflows.

Note that until the merchant reauthorizes your app, the old token will continue to work with the limited set of scopes that were granted when the merchant initially installed your app.

Below are some foreseeable problems and their solutions.

Problem 1: Your auth_callback_url endpoint accounts only for new installs, not reauthorizations

Steps leading to this problem:

If your app incorporates an assumption that calls to the auth_callback_url happen only at install time, it might treat this call as a new install, re-triggering initialization workflows that you did not intend.

Solution

You should save the store_hash associated with the token that your app received during the OAuth token exchange. Any time you receive a call on the auth_callback_url, you should first look in your database for the store_hash.

If the store_hash already exists, you will know that your app was already installed for that store, and that you have just been granted the new scopes.

If the store_hash does not exist, you will know that this is a first-time installation for the given store.

From our sample app, here is an example of appropriate handling of this logic.

Problem 2: Missing uninstall_callback_url endpoint

Steps leading to this problem:
Solution:

We highly recommend that you register an endpoint in Developer Portal as the uninstall_callback_url. This way, any time a merchant uninstalls your application, your uninstall_callback_url will be hit.

It is important that you keep track of uninstalls, so that the next time you receive a call on your auth_callback_url, you’ll be able to differentiate between a new installation versus a merchant granting new scopes for an already installed application.

One way to keep track of uninstalls is by managing your database entries: Remove the store_hash of the corresponding install. Another way is to use a boolean that is flagged/unflagged as a merchant installs/uninstalls your application.

March

SNI (Server Name Indication) required as of June 30, 2016

As of June 30, 2016, all requests to the BigCommerce API will be required to support Server Name Indication (SNI). After that date, requests will fail if they don’t support SNI.

Orders API provies opt-in email field

The Orders API provides a new is_email_opt_in field. This Boolean field will be true if the shopper has opted in (on the checkout page) to receive a store’s email newsletter. It is read-only.

We have updated the following documentation to cover this new field:

Stencil Framework now generally available

Developers can now install the Stencil themes framework without registering for access. Please follow the documentation link that’s relevant to your experience with Stencil:

February

Gift Certificate API

BigCommerce has published a new API for managing gift certificates. The API allows your applications to manage gift certificates’ amount/balance, purchaser, recipient, dates of purchase and expiration, and current status.

The new endpoint information is available here.

Customer/Address resource have new custom fields

Two Customers endpoints, and two Customer Addresses endpoints, now provide support for read-only custom fields:

        Customers
          List Customers
          Get a Customer

        Customer Addresses
          List Customer Addresses
          Get a Customer Address

You can access custom fields within the new form_fields element. For details and examples, please see our updated Customers and Customer Addresses reference pages.

New Store Updated & Order Webhooks

BigCommerce has made available two new webhooks. We encourage you to use these webhooks, as appropriate, in your applications:

We have updated the webhooks overview to include these new webhooks.

Expanded faceted-search display

Compatible Blueprint themes can now display up to 500 values in faceted-search results. This expands the previous 30-value limit on facets like brands, categories, product options, and custom fields.

To enable this expansion, you must retrofit your theme by either replacing or manually updating three files. Procedures and code snippets are in this new documentation section.

We have also updated merchant-oriented documentation that covers enabling faceted search and option-value limits.

Banners API

BigCommerce has published a new API for managing storefront banners. The API allows your applications to manage banners’ display location, timing, and content.

Information about this new endpoint is available here.

January

New global product variables: SKU, Brand Name, Custom Fields

BigCommerce’s Blueprint theme framework now provides three new global variables:

These variables are available in all snippets where products are available. (In general, this is anywhere that %%GLOBAL_ProductPrice%% appears). They are listed on this reference page.

New product and SKU webhooks added

BigCommerce has made available several new webhooks. In the list below, the new options are highlighted within the store/product/,
store/product/inventory/, store/sku/, and store/sku/inventory* categories. We encourage you to use these webhooks, as appropriate, in your applications:

  store/order/
    store/order/created
    store/order/updated
    store/order/archived
    store/order/statusUpdated
  store/product/
    store/product/created
    store/product/updated
    store/product/deleted
    store/product/inventory/updated
    store/product/inventory/order/updated
  store/product/inventory/
    store/product/inventory/updated
    store/product/inventory/order/updated
  store/sku/
    store/sku/created
    store/sku/updated
    store/sku/deleted
    store/sku/inventory/updated
    store/sku/inventory/order/updated
  store/sku/inventory/
    store/sku/inventory/updated
    store/sku/inventory/order/updated**
  store/customer/
    store/customer/created
    store/customer/updated
    store/customer/deleted
  store/app/uninstalled

We have updated the webhooks overview to include these new webhooks.

Status fields added to order/statusUpdated webhook

On January 22nd, 2016, BigCommerce will add status fields to the store/order/statusUpdated webhook event. These new fields will allow your applications to monitor order status more efficiently, with fewer API calls.

You are not required to incorporate these new fields, although we encourage you to take advantage of them. However, please use this advance notification to make sure that these new fields’ presence will not disrupt your code.

Currently, to find out an order’s status, an application must GET the order each time it receives the statusUpdated event. But often, the application needs to act on orders only in a single status. Because one order will generate multiple statusUpdated webhooks as the order goes from incomplete to completed, the GET requests add up to unnecessary traffic.

As of January 21ish, 2016, the webhook message will include details about the order’s new and previous status. Applications that monitor the added new_status_id and previous_status_id fields will no longer need to GET to the order, simply to determine whether the order needs to be processed.

The new_status_id and previous_status_id fields will be included in a newly added status element, formatted like this:

    "status": {
             "previous_status_id": "0",
             "new_status_id": "11"
    }

The previous_status_id field will allow your applications to troubleshoot orders by tracing the path these orders took through fulfillment. You could also build logic around this field, allowing your application to process only orders that pass from one certain status to another.

For example, you could prevent the double-processing of orders whose status accidentally changed, without having to store and check a list of already processed orders.

Here is an example of a webhook message in its currently supported format:

    {
      "scope": "store/order/statusUpdated",
      "store_id": "353242",
      "data": {
        "type": "order",
        "id": "817"
      },
      "hash": "24c6b87efc683de186387b12746455230e250fab",
      "created_at": 1449701096,
      "producer": "stores/z4zn3wo"
    }

Here is the same webhook message in the new format, with the added status fields set off with blank lines for visibility:

    {
      "scope": "store/order/statusUpdated",
      "store_id": "353242",
      "data": {
        "type": "order",
        "id": "817",

        "status": {
                 "previous_status_id": "0",
                 "new_status_id": "11"
        }

      },
      "hash": "24c6b87efc683de186387b12746455230e250fab",
      "created_at": 1449701096,
      "producer": "stores/z4zn3wo"
    }

(This second example shows an order moving from an “Incomplete” status [id: 0] to an “Awaiting Fulfillment” status [id: 11]. This change occurs whenever an order is paid for during storefront checkout.)

Include or exclude specific fields for Products resource

Your Get a Product or List Products requests can now include or exclude specific fields, by appending one of these options:

Certain fields are retrieved with all requests. For details and examples, please see this documentation.

2015

November

New block/retry schedule for unsuccessful webhook calls

To maximize the rapid delivery of successful webhooks, BigCommerce has imposed a new 60-second block on webhooks reporting unsuccessful callbacks. The new mechanism works like this:

For details, please see this updated Dev Portal article.

July

Manage users’ logout and session timeouts

A new callback function allows your Single-Click Apps to detect, and respond to, a user’s logout or timeout from the BigCommerce control panel.

To use this function, first include BigCommerce’s JavaScript SDK in your Single-Click App. You do so by adding this script tag:

http://www.google-analytics.com/ga.js"> src=“”>https://cdn.BigCommerce.com/jssdk/bc-sdk.js">

Next, when you initialize the SDK, include the logout callback function:

    BigCommerce.init({
          onLogout: callback
    });

The callback function will run when the user explicitly logs out of the BigCommerce control panel, or is automatically timed out. Your app can then respond to this logout. Read more.

April

Limits on categories, SKUs, option values, and brands

To maximize platform availability and system performance, BigCommerce has imposed the following limits.

Requests to the Stores API that exceed these limits will receive a 403 response.

Automatic sales tax document submissions for Avalara Premium stores

POST or PUT Orders on stores with Avalara Premium causes tax documents to be submitted

If a store has subscribed to Avalara Premium, BigCommerce automatically submits tax documents to Avalara when the order achieves a paid status. The following statuses are of the paid type:

BigCommerce considers all statuses other than the above to be of the unpaid type, except **Refunded**, which is considered neither paid or unpaid.

Orders created using the **POST** method that include a status of the paid type result in the submission of tax documents to Avalara. The behavior becomes more complex with order updates. The following table details the behavior for **PUT** operations.

Existing Status Status Passed Resultant Status Avalara tax document submission
Any None **Pending** None
Paid or **Refunded** Paid Paid None
Unpaid or **Refunded** Unpaid Unpaid None
Paid or **Refunded** Unpaid Unpaid Tax document voided
Unpaid or **Refunded** Paid Paid Tax document submitted

PRO TIP: Abbreviated state names in shipping and billing addresses will prevent tax documents from being submitted to Avalara. Spell state names out in full to ensure successful Avalara tax document submissions. For example, supplying **CA** as a state name results in no tax document submission. Supplying **California** as a state name results in a successful submission.

POST and PUT Orders now results in better order tax object values

When values for **price_inc_tax** and **price_ex_tax** are passed, a value of **API Tax Override** is written to the **name** field of the order tax object. In addition, the **base_price** value is no longer derived from the product object and any rulesets defined. Instead, BigCommerce writes either the **price_inc_tax** and **price_ex_tax** value to **base_price**, according to the store settings.

When the product already exists in the store and no values for **price_inc_tax** and **price_ex_tax** are passed, an order tax object will be created with a **base_price** value based on the product’s price.

DELETE Orders now fails if automatic tax enabled on the store

Attempts to **DELETE** an order on a store with automatic tax enabled now return a **405 Method not allowed**.

March

New fields to support deeper Avalara integrations

BigCommerce now allows merchants to further increase the automation and accuracy of their sales tax calculations by upgrading to AvaTax Pro. We have extended the Stores API to include these new features and maintain parity with the control-panel GUI. The extension consists of two new fields in the **customer** and **product** objects that accept AvaTax codes. We recommend using these codes to identify customers, products, and services that fall into special sales tax categories whenever possible.

Stores that do not have the AvaTax Pro subscription will store the codes but the codes will not impact their sales tax calculations. Please note that you should only pass one code per customer or product and the codes are case sensitive.

Identify customers exempt from sales tax

The customer object includes a new **tax_exempt_category** field, allowing you to identify customers that are either fully or partially exempt from paying sales tax. This includes employees of the federal government, Native Americans, foreign diplomats, and more. Review the Avalara documentation to find out more about these categories and for the list of codes.

Increase sales tax accuracy with product and service codes

The product object includes a new **avalara_product_tax_code** field that accepts a wide range of product and service codes. Refer to the “AvaTax System tax codes” section of the Avalara documentation for more information and the full list of codes.

February

New Test Payment Gateway

Developers using the **orders** resource may find the new Test Payment Gateway useful while developing and testing their apps. The Test Payment Gateway can be enabled from inside of your sandbox store. It allows a successful transaction to be processed from start to finish. To create or update an order to use the Test Payment Gateway, pass **Test Payment Gateway** as the value for **payment_method** in the **orders** object.

Further details can be reviewed in the orders object documentation.

2014

October

Values for tax_class ignored if automatic tax enabled

Stores located inside the United States no longer need to manually configure sales taxes. Enabled by default on new U.S. stores, the new automatic tax feature renders **tax_class** values irrelevant. The list of ignored **tax_class** values follows.

When enabled, automatic tax feature also affects the values inside the taxes object.

BigCommerce does not currently offer any programmatic means of determining if a store is using automatic or manual taxes.

April

Full CRUD support for Product Videos

Product videos in the Stores API can now be created, updated and deleted. This allows you to embed promotional videos from YouTube on storefront product pages.

Apps with write access to the products scope will automatically get access to this capability.

The reference for the Product Videos resource has all the details.

March

Product Image CDN URLs

We’ve released a small usability improvement for people working with products and images.

An object representing the primary product image is now embedded in the products resource for all list products and get product responses.

    {
    "primary_image": {
      "id": 247,
      "zoom_url": "https://cdn.url/et7xe3pz/products/32/images/247/123.0.1280.1280.jpg",
      "thumbnail_url": "https://cdn.url/et7xe3pz/products/32/images/247/123.0.220.290.jpg"
      "standard_url": "https://cdn.url/et7xe3pz/products/32/images/247/123.0.386.513.jpg",
      "tiny_url": "https://cdn.url/et7xe3pz/products/32/images/247/123.0.44.58.jpg"
      }
    }

The primary image is assigned to a product through the is_thumbnail property on the product images resource.

We’ve also added some additional CDN URL properties to all product images objects, supporting the following size formats:

This change is backwards compatible. Manually constructed image file paths on the store domain will work in exactly the same way as always, but they’re less performant and more brittle than just referencing an absolute link to the CDN.

For this reason, we recommend updating your apps to use the CDN URLs for referencing product images.

2013

December

Option Value Objects

The original design of our Stores API treated every entity in our entire domain model as an individually addressable resource with a unique URL ID.

This approach has worked well in terms of providing great coverage across the entire set of objects on our platform, but it requires clients to fire off a large volume of HTTP requests to work with aggregate objects.

Our platform team is on a mission to simplify, simplify, simplify, and these aggregate sub-resources are one of the main targets in our sights.

This week, we rolled out support for embedded value objects in the Option Set Options resource. Each option object now has a values property containing a list of all value objects assigned to that option.

Providing all the relevant data in one place avoids some of the complex traversals that were previously required to read the complete state of options and option values.

November

Orders Date Filters

We’ve just released a small update to the Orders Resource to improve the way that filtering by date works.

We now support filtering orders by date modified as well as date created. The full list of available date parameters is:

Filter Description
min_date_created Use this field to list orders created after a certain date
max_date_created Use this field to list orders created before a certain date
min_date_modified Use this field to list orders updated after a certain date
max_date_modified Use this field to list orders updated before a certain date

We’ve also added support for ISO 8601 format, which is better suited to use in querystring parameters than the original RFC 2822 header format.

Previous requests that looked like:

/api/v2/orders?max_date_modified=Thu%2C+28+Nov+2013+00%3A00%3A51+GMT

Can now be written in a much simpler way:

/api/v2/orders?max_date_modified=2013-11-28 /api/v2/orders?max_date_modified=2013-11-28T23:53:10Z

One of the most useful aspects of the ISO 8601 syntax is support for partial date values. For example, you can search for all orders by month or by year, simply by specifying the month and date parts:

/api/v2/orders?max_date_modified=2013 /api/v2/orders?max_date_modified=2013-12

We’ll be rolling out ISO 8601 support across the rest of the API over the next few weeks, which should make filtering collections by date much more user friendly.

Support for the existing RFC 2822 format hasn’t changed, so existing apps won’t require updates, though we do recommend you give this new date format a try!

July

Redirects Resource

Today, we’re pleased to announce the addition of Redirects to the Stores API.

Redirects are mappings that trigger an HTTP 301 response with a location header pointing from an incoming ‘virtual’ URL to an actual URL on a storefront. They’re extremely useful in situations where you’re migrating an existing website to BigCommerce and want to transition old page URLs seamlessly while preserving SEO rankings.

The redirects resource exposes very similar functionality to that of the BigCommerce control panel. The forward destination of a redirect can be generated automatically based on a pre-defined resource in BigCommerce (linking to a product, category or brand) or it can be any manually defined URL path.

Read the reference documentation and take it for a spin!