BCF SDK

bcf-sdk helps your MerchantHooks functions read saved settings and work with your BigCommerce store. Import the helpers you need and use them inside your function.

SDK version: This guide covers 1.1.0. If getBigCommerce() is unavailable in your function, contact support for help with SDK availability.

Quick start

This example reads a setting and retrieves a product from your connected store.

1. Open your function’s Integrations page and add BigCommerce API. This creates the store connection used by the SDK.
2. In Parameters, choose JSON data, name it settings, and enter the JSON below.
3. Save the handler below in your function’s code and deploy it.
4. Invoke the function with a JSON request body, such as {}. An enabled function retrieves one product and returns OK.

{
  "enabled": true
}

const { getParameter, getBigCommerce } = require("bcf-sdk");

exports.handler = async (payload) => {
  const settings = await getParameter("settings");
  if (settings.enabled === false) {
    return { statusCode: 200, body: "Disabled" };
  }

  const store = await getBigCommerce();
  const products = await store.get("/catalog/products?limit=1");
  // Use products and payload in your automation.

  return { statusCode: 200, body: "OK" };
};

The SDK is included in hosted functions. Import the helpers directly with require("bcf-sdk"); no additional installation is needed.

Function handler

Export an asynchronous handler(payload) function. The payload argument contains the incoming JSON request body, already parsed and ready to use.

For an order webhook, for example, read the order ID from payload.data.id. Request headers are not included in this argument, and you do not need to call JSON.parse() on it.

Return an HTTP response with a numeric statusCode and a string body. For a JSON response:

exports.handler = async (payload) => {
  return {
    statusCode: 200,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ received: true }),
  };
};

Await the work your function needs to complete before returning a success response. If an error prevents that work from completing, let the error propagate or handle it explicitly.

Read parameters

getParameter(name)

Returns a promise for the named parameter’s saved JSON value. Create the parameter on your function’s Parameters page before reading it.

Argument	Type	Description
name	string	Required, nonblank parameter name belonging to the function.

Objects, arrays, strings, numbers, booleans, and null are all valid results. Use a JSON string such as "hello" to store plain text; unquoted hello is invalid JSON. The SDK parses the value but does not validate your application’s settings schema.

const { getParameter } = require("bcf-sdk");

exports.handler = async () => {
  const settings = await getParameter("settings");
  if (!settings || typeof settings.enabled !== "boolean") {
    throw new Error("settings.enabled must be a boolean");
  }
  return {
    statusCode: 200,
    body: settings.enabled ? "Enabled" : "Disabled",
  };
};

Call the helper inside your handler to retrieve settings on each invocation. Missing parameters reject with ParameterNotFound; there is no automatic default. See Handle errors for an optional-parameter example.

Connect to BigCommerce

getBigCommerce(options = {})

Returns a promise for a configured node-bigcommerce client. Requires BCF SDK 1.1.0.

Add BigCommerce API on your function’s Integrations page before calling this helper. It connects to that integration’s store, so you do not need to put API credentials in your code. If access has been revoked, restore the connection before making requests.

Choose the matching helper: Use getBigCommerce() with a connection added under Integrations. For API credentials you added as a named entry under Parameters, follow Use a named API parameter below.

The client defaults to API v3 and JSON responses. Pass an options object to change the client configuration. If you supply headers, they replace the default headers rather than being merged with them.

const store = await getBigCommerce();
const products = await store.get("/catalog/products?limit=10");

const ordersApi = await getBigCommerce({ apiVersion: "v2" });
const order = await ordersApi.get("/orders/123");

Use paths relative to the selected API version. Choose the version required by the endpoint; the order retrieval example uses v2.

Client method	Purpose
get(path)	Read a resource.
post(path, data)	Send data to an endpoint.
put(path, data)	Update a resource.
delete(path)	Delete a resource.

Responses and API errors follow node-bigcommerce. Use the client’s HTTP methods directly, for example store.get("/orders/123").

Use a named API parameter

If you created a BigCommerce API parameter named order-api on the Parameters page, read its configuration and instantiate the client yourself:

const BigCommerce = require("node-bigcommerce");
const { getParameter } = require("bcf-sdk");

exports.handler = async (payload) => {
  const config = await getParameter("order-api");
  const store = new BigCommerce({
    ...config,
    apiVersion: "v2",
    responseType: "json",
  });
  const order = await store.get(`/orders/${payload.data.id}`);
  console.log("Processed order", { orderId: order.id });
  return { statusCode: 200, body: "OK" };
};

This example expects an order webhook payload containing data.id.

Order webhook example

Configure a store/order/created trigger, add the BigCommerce API integration, and create the JSON parameter settings with { "enabled": true }.

const { getParameter, getBigCommerce } = require("bcf-sdk");

exports.handler = async (payload) => {
  const settings = await getParameter("settings");
  if (settings.enabled === false) {
    return { statusCode: 200, body: "Disabled" };
  }

  const store = await getBigCommerce({ apiVersion: "v2" });
  const order = await store.get(`/orders/${payload.data.id}`);

  // Add your order automation here.
  console.log("Processed order", { orderId: order.id });
  return { statusCode: 200, body: "OK" };
};

To exercise the handler, use a JSON body such as { "data": { "id": 123 } }, replacing 123 with an existing order ID from your development store. This is the minimal input the example reads, not a complete webhook payload. The example fetches the order and logs its ID; add the business action your automation needs.

Handle errors

Errors created by SDK 1.1.0 have name: "BcfError" and a stable code. Handle errors by code rather than matching message text.

Code	Meaning and next step
BCF_INVALID_PARAMETER_NAME	Supply a nonblank string as the parameter name.
BCF_MISSING_CONTEXT	The SDK could not identify the function’s store. If this happens in a hosted function, contact support.
BCF_INVALID_PARAMETER_RESPONSE	The parameter could not be read in the expected format. Contact support if the problem persists.
BCF_INVALID_JSON	The parameter value is invalid JSON. Correct the value, including quotes around plain strings.
BCF_INVALID_INTEGRATION	The BigCommerce connection is incomplete or invalid. Check the function’s integration.
ParameterNotFound	No parameter exists with that name. Create it under Parameters or check the spelling.
AccessDeniedException	The function could not access a required setting. Contact support for help.

Some errors, including ParameterNotFound and AccessDeniedException, do not have the name BcfError; check their code directly. For BigCommerce request failures, check the endpoint, API version, and the connection’s permissions.

For an optional parameter, explicitly handle only the missing-value case:

const { getParameter } = require("bcf-sdk");

async function readOptionalSettings() {
  try {
    return await getParameter("settings");
  } catch (error) {
    if (error.code === "ParameterNotFound") {
      return { enabled: false };
    }
    throw error;
  }
}

The SDK does not log errors or secret values. In your own code, avoid logging or returning parameter values, credentials, or complete error objects that may contain request details.

Compatibility

getIntegration(type, options = {})

The compatibility helper returns a promise for client configuration, rather than a client instance. Existing code can continue to construct its own client:

const BigCommerce = require("node-bigcommerce");
const { getIntegration } = require("bcf-sdk");

exports.handler = async (payload) => {
  const config = await getIntegration("bigcommerceapi", {
    apiVersion: "v2",
  });
  const store = new BigCommerce(config);
  const order = await store.get(`/orders/${payload.data.id}`);
  return { statusCode: 200, body: "OK" };
};

Only "bigcommerceapi" is supported. Unknown types resolve to undefined. Options override the returned client configuration; supplying headers replaces the default headers. For new functions running SDK 1.1.0, getBigCommerce(options) combines the configuration and client construction steps.

If getBigCommerce is undefined or produces a “not a function” error, contact support to check SDK availability for your function. Existing code using getIntegration() can continue to use that helper.