BigCommerce for Craft CMS

Build a content-driven storefront by BigCommerce BigCommerce products into Craft CMS.

Topics

• :package: Installation: Set up the plugin and get connected to BigCommerce.
• :card_file_box: Working with Products: Learn what kind of data is available and how to access it.
• :bookmark_tabs: Templating: Tips and tricks for using products in Twig.
• :telescope: Advanced Features: Go further with your integration.

Installation

The BigCommerce plugin requires Craft CMS 4.0.0 or later.

To install the plugin, visit the Plugin Store from your Craft project, or follow these instructions.

1. Navigate to your Craft project in a new terminal:

2. Require the package with Composer:

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for BigCommerce, or run:

Create a BigCommerce API Account

Note
You must be the owner of the store in order to generate API accounts.

Login to your BigCommerce admin panel and navigate to Settings → API Accounts → Create API Account. Proceed as follows:

1. Token type: V2/V3 API token
2. Name: A descriptive name. It's a good idea to use different credentials for different environments - e.g. "[Prod] Craft CMS"

3. OAuth scopes: The following scopes are required for the plugin to function correctly:

   • Content: read-only
   • Checkout content: None
   • Customers: modify
   • Customer login: login
   • Information & settings: modify
   • Marketing: modify
   • Orders: modify
   • Order transactions: read-only
   • Create payments: None
   • Get payment methods: None
   • Stored Payment Instruments: None
   • Products: modify
   • Themes: read-only
   • Carts: modify
   • Checkouts: modify
   • Sites & routes: modify
   • Channel settings: modify
   • Channel listings: modify
   • Storefront API tokens: manage
   • Storefront API customer impersonation tokens: manage
   • Store logs: read-only
   • Store Inventory: read-only

Click save.

1. Client ID: Reveal and copy this value into your .env file, as BC_CLIENT_ID.
2. Client secret: Reveal and copy this value into your .env file, as BC_CLIENT_SECRET.
3. Access token: Reveal and copy this value into your .env file, as BC_ACCESS_TOKEN.
4. Store Hash: This value is found in your store URL: https://store-**store hash**.mybigcommerce.com/ Copy this value into your .env file, as BC_STORE_HASH
5. Sales Channel: If you're using the default BigCommerce storefront, this value is 1; otherwise, find the ID of your Sales Channel in the Channel Manager of Big Commerce. Copy this value into your .env file, as BC_SALES_CHANNEL

Connect Plugin

Now that you have credentials for your custom app, it’s time to add them to Craft.

1. Visit the BigCommerce → Settings screen in your project’s control panel.
2. Assign the four environment variables to the corresponding settings, using the special config syntax:
   • API Client ID: $BC_CLIENT_ID
   • API Secret Key: $BC_CLIENT_SECRET
   • Access Token: $BC_ACCESS_TOKEN
   • Sales Channel: $BC_SALES_CHANNEL
3. Click Save.

Note
These settings are stored in Project Config, and will be automatically applied in other environments. Webhooks will still need to be configured for each environment!

Set up Webhooks

Once your credentials have been added to Craft, a new Webhooks tab will appear in the BigCommerce section of the control panel.

Click Create on the Webhooks screen to add the required webhooks to BigCommerce. The plugin will use the credentials you just configured to perform this operation—so this also serves as an initial communication test.

Warning
You will need to add webhooks for each environment you deploy the plugin to, because each webhook is tied to a specific URL.

Note
If you need to test live synchronization in development, we recommend using ngrok to create a tunnel to your local environment. DDEV makes this simple, with the ddev share command. Use the Base URL Override option on the webhook creation screen to provide this value. Remember to delete the test webhooks when you're done!

Product Element

Products from your BigCommerce store are represented in Craft as product elements, and can be found by going to BigCommerce → Products in the control panel.

Synchronization

Products will be automatically created, updated, and deleted via webhooks—but Craft doesn’t know about a product until a change happens.

Once the plugin has been configured, perform an initial synchronization via the command line:

php craft bigcommerce/sync/products

Note
Products can also be synchronized from the control panel using the BigCommerce Sync utility. Keep in mind that large stores (over a hundred products) may take some time to synchronize, and can quickly run through PHP’s max_execution_time.

Native Attributes

In addition to the standard element attributes like id, title, and status, each BigCommerce product element contains the following mappings to its canonical BigCommerce Product resource:

All of these properties are available when working with a product element in your templates.

Note
See the BigCommerce documentation on the product resource for more information about what kinds of values to expect from these properties.

Methods

The product element has a few methods you might find useful in your templates.

Product::getVariants()

Returns the variants belonging to the product.

Product::getDefaultVariant()

Shortcut for getting the first/default variant belonging to the product.

Product::getCheapestVariant()

Shortcut for getting the lowest-priced variant belonging to the product.

Product::getBigCommerceUrl()

Product::getBigCommerceEditUrl()

For your administrators, you can even link directly to the BigCommerce admin:

Custom Fields

Products synchronized from BigCommerce have a dedicated field layout, which means they support Craft’s full array of content tools.

The product field layout can be edited by going to BigCommerce → Settings → Products, and scrolling down to Field Layout.

Routing

You can give synchronized products their own on-site URLs. To set up the URI format (and the template that will be loaded when a product URL is requested), go to BigCommerce → Settings → Products.

If you would prefer your customers to view individual products on BigCommerce, clear out the Product URI Format field on the settings page, and use product.bigcommerceUrl instead of product.url in your templates.

Note
Statuses in Craft are often a synthesis of multiple properties. For example, an entry with the Pending status just means it is enabled and has a postDate in the future.

Querying Products

Products can be queried like any other element in the system.

A new query begins with the craft.bigcommerceProducts factory function:

Query Parameters

The following element query parameters are supported, in addition to Craft’s standard set.

Note Fields stored as JSON (like options and metadata) are only queryable as plain text. If you need to do advanced organization or filtering, we recommend using custom Category or Tag fields in your Product field layout.

bigcommerceId

Filter by BigCommerce product IDs.

handle

Query by the product’s handle, in BigCommerce.

:rotating_light: This is not a reliable means to fetch a specific product, as the value may change during a synchronization. If you want a permanent reference to a product, consider using the BigCommerce product field.

productType

Find products by their “type” in BigCommerce.

publishedScope

Show only products that are published to a matching sales channel.

tags

Tags are stored as a comma-separated list. You may see better results using the .search() param.

vendor

Filter by the vendor information from BigCommerce.

images

Images are stored as a blob of JSON, and only intended for use in a template in conjunction with a loaded product. Filtering directly by image resource values can be difficult and unpredictable—you may see better results using the .search() param.

options

the .search() param.

The above includes quote (") literals, because it’s attempting to locate a specific key in a JSON array, which will always be surrounded by double-quotes.

Templating

Product Data

Products behave just like any other element, in Twig. Once you’ve loaded a product via a custom field data.

Note
Some attributes are stored as JSON, which limits nested properties’s types. As a result, dates may be slightly more difficult to work with.

Variants and Pricing

Products don’t have a price, despite what the BigCommerce UI might imply—instead, every product has at least one Variant.

You can get an array of variant objects for a product by calling collect() Twig function.

Unlike products, variants in Craft…

• …are represented exactly as the API returns them;
• …use BigCommerce’s convention of underscores in property names instead of exposing camel-cased equivalents;
• …are plain associative arrays;
• …have no methods of their own;

Once you have a reference to a variant, you can output its properties:

Note
The built-in currency Twig filter is a great way to format money values.

Using Options

Options are BigCommerce’s way of distinguishing variants on multiple axes.

If you want to let customers pick from options instead of directly select variants, you will need to resolve which variant a given combination points to.

Cart

Your customers can add products to their cart directly from your Craft site:

JS Buy SDK

Cart management and checkout are not currently supported in a native way.

However, BigCommerce maintains the Javascript Buy SDK as a means of interacting with their Storefront API to create completely custom shopping experiences.

Note
Use of the Storefront API requires a different access key, and assumes that you have published your products into the Storefront app’s sales channel.

Your public Storefront API token can be stored with your other credentials in .env and output in your front-end with the {{ getenv('...') }} Twig helper—or just baked into a Javascript bundle. Keep your other secrets safe! This is the only one that can be disclosed.

The plugin makes no assumptions about how you use your product data in the front-end, but provides the tools necessary to connect it with the SDK. As an example, let’s look at how you might render a list of products in Twig, and hook up a custom client-side cart…

Shop Template: templates/shop.twig

Custom Script: assets/js/shop.js

Buy Button JS

The above example can be simplified with the Buy Button JS, which provides some ready-made UI components, like a fully-featured cart. The principles are the same:

1. Make products available via the appropriate sales channels in BigCommerce;
2. Output synchronized product data in your front-end;
3. Initialize, attach, or trigger SDK functionality in response to events, using BigCommerce-specific identifiers from step #2;

Checkout

While solutions exist for creating a customized shopping experience, checkout will always happen on BigCommerce’s platform. This is not a technical limitation so much as it is a policy—BigCommerce’s checkout flow is fast, reliable, secure, and familiar to many shoppers.

If you want your customers’ entire journey to be kept on-site, we encourage you to try out our powerful ecommerce plugin, Commerce.

Helpers

In addition to product element methods, the plugin exposes its API to Twig via craft.bigcommerce.

API Service

Warning
Use of API calls in Twig blocks rendering and—depending on traffic—may cause timeouts and/or failures due to rate limits. Consider using the {% cache %} tag with a key and specific expiry time to avoid making a request every time a template is rendered:

Issue requests to the BigCommerce Admin API via craft.bigcommerce.api:

The schema for each API resource will differ. Consult the BigCommerce API documentation for more information.

Store Service

A simple URL generator is available via craft.bigcommerce.store. You may have noticed it in the cart example, above—but it is a little more versatile than that!

The same params argument can be passed to a product element’s getBigCommerceUrl() method:

Product Field

The plugin provides a BigCommerce Products field, which uses the familiar relational field UI to allow authors to select Product elements.

Relationships defined with the BigCommerce Products field use stable element IDs under the hood. When BigCommerce products are archived or deleted, the corresponding elements will also be updated in Craft, and naturally filtered out of your query results—including those explicitly attached via a BigCommerce Products field.

Note
Upgrading? Check out the migration notes for more info.

Migrating from v2.x

If you are upgrading a Craft 3 project to Craft 4 and have existing “BigCommerce Product” fields, you’ll need show the plugin how to translate plain BigCommerce IDs (stored as a JSON array) into element IDs, within Craft’s relations system.

Warning
Before getting started with the field data migration, make sure you have synchronized your product catalog.

It’s safe to remove the old plugin package (nmaier95/bigcommerce-product-fetcher) from your composer.json—but do not use the control panel to uninstall it. We want the field’s data to stick around, but don’t need the old field class to work with it.

Note
You may see a “missing field” in your field layouts during this process—that’s OK! Your data is still there.

For each legacy BigCommerce Product field in your project, do the following:

1. Create a new BigCommerce Products field, giving it a a new handle and name;
2. Add the field to any layouts where the legacy field appeared;

Re-saving Data

Run the following command (substituting appropriate values) for each place you added the field in step #2, above:

• resave/entries → The re-save command for the element type the field layout is attached to;
• mySectionHandle → A stand-in for any criteria that need to be applied to the element type you’re re-saving;
• oldBigCommerceField → Field handle from the old version of the plugin (used inside the --to argument closure);
• newBigCommerceField → New field handle created in step #1, above;

Updating Templates

After your content is re-saved, update your templates:

Before

In v2.x, you were responsible for looking up product details in the template:

After

There is no need to query the BigCommerce API to render product details in your templates—all of the data is available on the returned elements!

Going Further

Events

venveo\bigcommerce\services\Products::EVENT_BEFORE_SYNCHRONIZE_PRODUCT

Emitted just prior to a product element being saved with new BigCommerce data. The venveo\bigcommerce\events\BigCommerceProductSyncEvent extends craft\events\CancelableEvent, so setting $event->isValid allows you to prevent the new data from being saved.

The event object has three properties:

• element: The product element being updated.
• source: The BigCommerce product object that was applied.
• metafields: Additional metafields from BigCommerce that the plugin discovered while performing the synchronization.

Warning Do not manually save changes made in this event handler. The plugin will take care of this for you!

Element API

Your synchronized products can be published into an Element API endpoint, just like any other element type. This allows you to set up a local JSON feed of products, decorated with any content you’ve added in Craft:

Acknowledgements

• Very helpful reference repository: https://github.com/labbydev/fingerprint