Registry / http-networking / node-bigcommerce

node-bigcommerce

JSON →
library4.1.0jsnpmunverified

node-bigcommerce is a comprehensive Node.js module designed for integrating applications with the BigCommerce API. It facilitates OAuth 2.0 authentication, handles authorization flows, verifies signed payloads for app load/uninstall events, and provides convenient helper methods for executing various API requests (GET, POST, PUT, DELETE). The current stable version is 4.1.0. While the release cadence is moderate, major versions introduce breaking changes such as the significant refactor in v3.0.0 to exclusively use Promises and the dropping of older Node.js versions. A key differentiator is its streamlined approach to BigCommerce-specific authentication mechanisms and direct support for different API versions (v2 and v3). Since v3.0.0, it leverages ES6 classes and standard Promises, moving away from callback-based patterns.

http-networkingauth-securitycrm-productivityweb-framework
npm install node-bigcommerce
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · NODE-BIGCOMMERCE
N
node-bigcommerce
http-networkingjavascriptv4.1.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BigCommerce
✓ const BigCommerce = require('node-bigcommerce');
✗ import BigCommerce from 'node-bigcommerce';
The library primarily uses CommonJS `require` syntax as shown in official examples. While it uses ES6 classes internally, direct ESM `import` may not be officially supported or require specific bundler configurations without explicit ESM exports.
BigCommerce (Instantiation)
✓ const bigCommerce = new BigCommerce({ clientId: '...', secret: '...', callback: '...' });
✗ const bigCommerce = BigCommerce();
The BigCommerce class must be instantiated with the `new` keyword and requires a configuration object.

This quickstart demonstrates how to set up `node-bigcommerce` with Express.js to handle both OAuth authorization and verify signed payloads for app load/uninstall events, showcasing key authentication flows.

const express = require('express'); const BigCommerce = require('node-bigcommerce'); const app = express(); const PORT = process.env.PORT || 3000; // Basic BigCommerce configuration for authorization const bigCommerce = new BigCommerce({ clientId: process.env.BIGCOMMERCE_CLIENT_ID ?? 'your_client_id_here', secret: process.env.BIGCOMMERCE_SECRET ?? 'your_secret_here', callback: process.env.BIGCOMMERCE_CALLBACK_URL ?? 'https://localhost:3000/auth', responseType: 'json', apiVersion: 'v3' // Specify API version, defaults to v2 }); // Example Authorization Route app.get('/auth', (req, res, next) => { bigCommerce.authorize(req.query) .then(data => { console.log('Authorization successful:', data); // Store access_token and context for future API calls res.send(`<h1>Authorized!</h1><p>Access Token: ${data.access_token}</p>`); }) .catch(err => { console.error('Authorization failed:', err); next(err); }); }); // Example Load/Uninstall Verification Route // For load/uninstall, only secret is typically needed for verify method. const bigCommerceVerify = new BigCommerce({ secret: process.env.BIGCOMMERCE_SECRET ?? 'your_secret_here', responseType: 'json' }); app.get('/load', (req, res, next) => { try { const data = bigCommerceVerify.verify(req.query['signed_payload']); console.log('Signed Payload Verified:', data); res.send(`<h1>Welcome!</h1><p>User: ${data.user.email}</p><p>Store: ${data.store_hash}</p>`); } catch (err) { console.error('Signed payload verification failed:', err); next(err); } }); app.listen(PORT, () => { console.log(`Server running on http://localhost:${PORT}`); console.log('Set BIGCOMMERCE_CLIENT_ID, BIGCOMMERCE_SECRET, BIGCOMMERCE_CALLBACK_URL environment variables.'); });
Debug
Known issues
breakingVersion 3.0.0 completely removed support for callbacks. All asynchronous operations now return Promises exclusively. Code relying on callback patterns will break.
fix
Refactor all API calls and authorization flows to use `.then()`/`.catch()` or `async/await` syntax instead of callbacks.
affects: >=3.0.0
breakingThe `authorise` method was renamed to `authorize` in version 3.0.0. Calls to the old method name will result in a `TypeError`.
fix
Update all instances of `bigCommerce.authorise(...)` to `bigCommerce.authorize(...)`.
affects: >=3.0.0
breakingThe `callback` method was removed in version 3.0.0. The `verify` method will now directly throw an `Error` if the signed payload is invalid or verification fails, instead of invoking a callback.
fix
Wrap `bigCommerce.verify(...)` calls in a `try...catch` block to handle verification errors.
affects: >=3.0.0
breakingThe internal logger was removed in version 3.0.0. Debug messages are now controlled via the `DEBUG` environment variable, specifically `DEBUG=node-bigcommerce:*`.
fix
Remove any direct `logLevel` or logger configurations. To enable debug output, set the environment variable `DEBUG=node-bigcommerce:*` before running your application.
affects: >=3.0.0
breakingVersion 4.0.0 removed official support for Node.js 6. While the library might still function on Node 6 in some cases, it is no longer tested against it, and compatibility issues may arise.
fix
Upgrade your Node.js runtime environment to version 10 or higher for full compatibility and support.
affects: >=4.0.0
gotchaInstantiating the `BigCommerce` class without a configuration object will result in an immediate error, as essential credentials and settings are required for operation.
fix
Always provide a configuration object to the `BigCommerce` constructor, even if some properties are set to empty strings or obtained from environment variables.
affects: >=1.0.0
gotchaA security vulnerability related to a timing attack in the authentication process was fixed in version 3.1.0. Users on previous 3.x versions are advised to upgrade.
fix
Upgrade to version 3.1.0 or newer to ensure protection against this timing attack vulnerability.
affects: <3.1.0
Errors
Common errors & fixes
TypeError: bigCommerce.authorise is not a function
Attempting to use the deprecated `authorise` method after version 3.0.0.
fix
Rename `bigCommerce.authorise` to `bigCommerce.authorize`.
Error: Config object is required to instantiate BigCommerce
The `BigCommerce` class was instantiated without providing a configuration object.
fix
Pass a configuration object to the `BigCommerce` constructor, e.g., `new BigCommerce({...})`.
TypeError: Cannot read properties of undefined (reading 'access_token') or similar for promise resolution
The `authorize` method requires query parameters from the OAuth callback URL (`req.query` in Express) to complete the authorization flow. If these are missing or incorrect, the promise will reject, or the returned data object will be incomplete.
fix
Ensure `bigCommerce.authorize(req.query)` is called with the full query parameters from the BigCommerce redirect, and handle the promise rejection with a `.catch()` block.
Error: Invalid signed_payload
The `verify` method was called with an invalid, malformed, or missing `signed_payload` parameter, or the secret used for verification does not match the one used to sign the payload.
fix
Ensure `bigCommerce.verify(req.query['signed_payload'])` is called with the correct `signed_payload` string passed by BigCommerce, and that the `secret` configured for the `BigCommerce` instance matches your BigCommerce app secret.
Upgrade
Version history
4.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
31 hits · last 30 days
node
28
OpenAI (training)
1
Resources
githubhttps://github.com/getconversio/node-bigcommerce ↗
packagehttps://www.npmjs.com/package/node-bigcommerce ↗
homepagehttps://www.bigcommerce.com ↗