{"id":13614,"library":"node-bigcommerce","title":"BigCommerce API Client for Node.js","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/getconversio/node-bigcommerce","tags":["javascript","bigcommerce","oauth2.0","oauth","conversio","api","ecommerce","node","npm"],"install":[{"cmd":"npm install node-bigcommerce","lang":"bash","label":"npm"},{"cmd":"yarn add node-bigcommerce","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-bigcommerce","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import BigCommerce from 'node-bigcommerce';","symbol":"BigCommerce","correct":"const BigCommerce = require('node-bigcommerce');"},{"note":"The BigCommerce class must be instantiated with the `new` keyword and requires a configuration object.","wrong":"const bigCommerce = BigCommerce();","symbol":"BigCommerce (Instantiation)","correct":"const bigCommerce = new BigCommerce({ clientId: '...', secret: '...', callback: '...' });"}],"quickstart":{"code":"const express = require('express');\nconst BigCommerce = require('node-bigcommerce');\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\n// Basic BigCommerce configuration for authorization\nconst bigCommerce = new BigCommerce({\n clientId: process.env.BIGCOMMERCE_CLIENT_ID ?? 'your_client_id_here',\n secret: process.env.BIGCOMMERCE_SECRET ?? 'your_secret_here',\n callback: process.env.BIGCOMMERCE_CALLBACK_URL ?? 'https://localhost:3000/auth',\n responseType: 'json',\n apiVersion: 'v3' // Specify API version, defaults to v2\n});\n\n// Example Authorization Route\napp.get('/auth', (req, res, next) => {\n bigCommerce.authorize(req.query)\n .then(data => {\n console.log('Authorization successful:', data);\n // Store access_token and context for future API calls\n res.send(`

Authorized!

Access Token: ${data.access_token}

`);\n })\n .catch(err => {\n console.error('Authorization failed:', err);\n next(err);\n });\n});\n\n// Example Load/Uninstall Verification Route\n// For load/uninstall, only secret is typically needed for verify method.\nconst bigCommerceVerify = new BigCommerce({\n secret: process.env.BIGCOMMERCE_SECRET ?? 'your_secret_here',\n responseType: 'json'\n});\n\napp.get('/load', (req, res, next) => {\n try {\n const data = bigCommerceVerify.verify(req.query['signed_payload']);\n console.log('Signed Payload Verified:', data);\n res.send(`

Welcome!

User: ${data.user.email}

Store: ${data.store_hash}

`);\n } catch (err) {\n console.error('Signed payload verification failed:', err);\n next(err);\n }\n});\n\napp.listen(PORT, () => {\n console.log(`Server running on http://localhost:${PORT}`);\n console.log('Set BIGCOMMERCE_CLIENT_ID, BIGCOMMERCE_SECRET, BIGCOMMERCE_CALLBACK_URL environment variables.');\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Refactor all API calls and authorization flows to use `.then()`/`.catch()` or `async/await` syntax instead of callbacks.","message":"Version 3.0.0 completely removed support for callbacks. All asynchronous operations now return Promises exclusively. Code relying on callback patterns will break.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update all instances of `bigCommerce.authorise(...)` to `bigCommerce.authorize(...)`.","message":"The `authorise` method was renamed to `authorize` in version 3.0.0. Calls to the old method name will result in a `TypeError`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Wrap `bigCommerce.verify(...)` calls in a `try...catch` block to handle verification errors.","message":"The `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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove any direct `logLevel` or logger configurations. To enable debug output, set the environment variable `DEBUG=node-bigcommerce:*` before running your application.","message":"The internal logger was removed in version 3.0.0. Debug messages are now controlled via the `DEBUG` environment variable, specifically `DEBUG=node-bigcommerce:*`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js runtime environment to version 10 or higher for full compatibility and support.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always provide a configuration object to the `BigCommerce` constructor, even if some properties are set to empty strings or obtained from environment variables.","message":"Instantiating the `BigCommerce` class without a configuration object will result in an immediate error, as essential credentials and settings are required for operation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to version 3.1.0 or newer to ensure protection against this timing attack vulnerability.","message":"A 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.","severity":"gotcha","affected_versions":"<3.1.0"}],"env_vars":null,"search_vec":"'2.0':25 '4.1.0':56 'api':2,21,45,104,130 'app':34 'applic':17 'approach':92 'authent':26,97 'author':28 'away':119 'base':123 'bigcommerc':1,8,20,95,126 'bigcommerce-specif':94 'break':66 'cadenc':60 'callback':122 'callback-bas':121 'chang':67 'class':114 'client':3 'comprehens':11 'conveni':39 'conversio':129 'current':52 'delet':50 'design':14 'differ':103 'differenti':88 'direct':100 'drop':81 'ecommerc':131 'es6':113 'event':36 'exclus':76 'execut':43 'facilit':23 'flow':29 'get':47 'handl':27 'helper':40 'integr':16 'introduc':65 'javascript':125 'key':87 'leverag':112 'load/uninstall':35 'major':63 'mechan':98 'method':41 'moder':62 'modul':13 'move':118 'node':7,132 'node-bigcommerc':6 'node.js':5,12,84 'npm':133 'oauth':24,128 'oauth2.0':127 'older':83 'pattern':124 'payload':32 'post':48 'promis':78,117 'provid':38 'put':49 'refactor':72 'releas':59 'request':46 'sign':31 'signific':71 'sinc':109 'specif':96 'stabl':53 'standard':116 'streamlin':91 'support':101 'use':77 'v2':106 'v3':108 'v3.0.0':74,110 'various':44 'verifi':30 'version':54,64,85,105","created_at":"2026-04-20T01:55:25.152570+00:00","updated_at":"2026-04-20T01:55:25.152570+00:00","problems":[{"fix":"Rename `bigCommerce.authorise` to `bigCommerce.authorize`.","cause":"Attempting to use the deprecated `authorise` method after version 3.0.0.","error":"TypeError: bigCommerce.authorise is not a function"},{"fix":"Pass a configuration object to the `BigCommerce` constructor, e.g., `new BigCommerce({...})`.","cause":"The `BigCommerce` class was instantiated without providing a configuration object.","error":"Error: Config object is required to instantiate BigCommerce"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'access_token') or similar for promise resolution"},{"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.","cause":"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.","error":"Error: Invalid signed_payload"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://www.bigcommerce.com","github":"https://github.com/getconversio/node-bigcommerce","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-bigcommerce","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","auth-security","crm-productivity","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}