facebook-nodejs-business-sdk wraps Meta's Marketing API in entity classes

One package instead of one SDK per Meta API

The problem the Business SDK is meant to solve is described plainly in the readme. Partners are using multiple Facebook APIs to serve their needs, and adopting all of them and keeping them up to date across platforms is described as time consuming and ultimately prohibitive. The response is a single SDK that bundles many of the APIs into one.

It is an upgrade of the earlier Marketing API SDK, and it includes the Marketing API along with APIs from other platforms such as Pages, Business Manager and Instagram. The homepage points at the Business SDK documentation on developers.facebook.com.

For a team that genuinely touches several of those surfaces, that consolidation is the whole value proposition. The code is one dependency, the request layer is one, and the API version you are coded against is one decision rather than several. The trade is that you take the bundle's cadence, and the releases here follow Meta's own versioning, moving to v26.0.0 in August 2026 with patch releases since.

The package is published as facebook-nodejs-business-sdk, with the maintainer listed in the package metadata, and it is described in the metadata as an SDK for the Facebook Marketing API in Javascript and Node.js. The keyword list is telling about the intended environment, with isomorphic, nodejs, amd, requirejs, umd and promises all named.

FacebookAdsApi.init takes the token and becomes your client

The API object is the foundation of the SDK, and the readme says it encapsulates the logic to execute requests against the Graph API. Once instantiated, it lets you start making requests.

The whole setup is three lines.

const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '<VALID_ACCESS_TOKEN>';
const api = adsSdk.FacebookAdsApi.init(accessToken);

There is no configuration object, no base URL to set and no client to build. The access token is the only input, which makes sense for an SDK that talks to one API on one host, and it also means the token has to be somewhere you control, since it is embedded in your source unless you inject it.

The readme describes an access token as an opaque string that identifies a User, an app or a Page, obtained when someone connects with an app using Facebook Login and approves a permissions request, and it describes the token as providing temporary, secure access to the Facebook APIs.

Which permissions you request decides which APIs you can call. For the Marketing API you generate a User access token and ask for the ads_management permission, and for the Pages API you generate a Page access token and ask for manage_page. Those two sentences are the entire permission model the readme describes, and both are worth getting right before writing any campaign code.

Entity classes and Fields maps are generated from the API shape

Ads entities are defined as classes under the src/objects directory, and the way you use them is by instantiating them with an identifier and calling methods on the instance.

// instantiating an object
const adsSdk = require('facebook-nodejs-business-sdk');
const AdAccount = adsSdk.AdAccount;
const account = new AdAccount('act_<AD_ACCOUNT_ID>');
console.log(account.id) // fields can be accessed as properties

The identifier format is the one the API expects, with the act_ prefix on an ad account id.

The fields system is the piece that makes a large API usable without hardcoding long field-name strings. The readme states that because of the high number of field names in the existing API objects, enum-like field objects are provided within each node class, and the fields are stored in node object classes under src/objects. You do not write the string name of a field, you reference the enum entry, so a misspelled field is a runtime undefined rather than a silent server error.

The pattern shows up in every call, since each object exposes a Fields map with a list of the fields supported on that object, plus enum-like values for things like campaign status and objective.

const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '<VALID_ACCESS_TOKEN>';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const AdAccount = adsSdk.AdAccount;
const Campaign = adsSdk.Campaign;
const account = new AdAccount('act_<AD_ACCOUNT_ID>');

Calls return promises, and asking for fewer fields is faster

Every operation on an entity returns a promise, so the read and create flows are the same shape.

const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '<VALID_ACCESS_TOKEN>';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const AdAccount = adsSdk.AdAccount;
const account = new AdAccount('act_<AD_ACCOUNT_ID>');
account
  .read([AdAccount.Fields.name, AdAccount.Fields.age])
  .then((account) => {
    console.log(account);
  })
  .catch((error) => {
  });

The read method takes the list of fields you want and resolves with the object. The create methods take a field list and a values object, keyed by the same Fields enum entries, with values such as Campaign.Status.paused and Campaign.Objective.page_likes coming from the enum-like maps rather than from raw strings.

The readme gives one performance note and it is a practical one: requesting a high number of fields may cause the response time to visibly increase, so you should always request only the fields you really need. That is an easy habit to skip once an object has dozens of fields, and it is the kind of thing that shows up as a slow reporting job rather than as an error.

The dependency list explains how the requests are assembled. axios handles the HTTP, capi-param-builder-nodejs builds the request parameters, and js-sha256 provides hashing, which is what the app secret proof check needs. currency-codes, email-validator and iso-3166-1 are there to support the validation the API expects on certain object types.

The same package runs in Node and in a browser

The SDK is described as usable for both server side and client side use, and the distribution formats are listed explicitly. It comes with an ECMAScript 5 bundled minified distribution with source maps, in AMD, CommonJS, IIFE, UMD and browser globals formats.

That list is the practical consequence of one package serving two very different environments. CommonJS is what the examples use, require('facebook-nodejs-business-sdk'), and it is what a Node service wants. UMD and the browser globals are what a page wants when the campaign creation happens in the browser.

The tradeoff is on the packaging side rather than the API side. The toolchain that produces those bundles is visible in the repository: gulpfile.js at the root, with Gulp, Babel and Rollup plugins in the dev dependencies, and the readme tells contributors to check gulpfile.js for the available tasks. The development install is a Gulp and Bower setup, both expected to be installed globally, followed by a dependency install.

npm install
bower install

The presence of Bower, a package manager that has largely been retired, is the clearest signal of the project's age. It does not stop the package from working, since the npm path is the supported one for new projects, but the build tooling around it is from an era when npm and Bower were both current, and that shows in the pinned dev dependencies.

Registering the app and turning on the secret proof

Two setup steps sit between installing the package and making a working call, and neither is optional.

The first is the app itself. To get started you must have an app registered on developers.facebook.com, and to manage the Marketing API you visit the app dashboard and add the Marketing API product to your app. Without that product, the calls in the examples return permission errors regardless of the token.

The second is the secret proof. The readme marks this as important: for security it is recommended that you turn on App Secret Proof for Server API calls in the app's Settings and Advanced page. The SDK ships js-sha256 in its dependencies, which is consistent with that setting being enforced from the client side by hashing the request with the app secret rather than only with the token.

For getting a token in the first place, the readme points at the Graph Explorer as the tool to use for now, with the full Access Token Guide as the reference for the permission model. That is a reasonable starting workflow, and it is also a reminder that this SDK is a client for an access controlled API rather than something you can point at a sandbox.

A related risk to keep in mind is that the token lives in your code. The examples pass it as a literal string, which is fine for a first request and wrong for a deployed service, where it belongs in configuration and in the server side only.

Where the SDK stops, and what to check before adopting it

The boundary of this package is the Meta platform itself. It covers the Marketing API and a set of related APIs, and it will not cover anything outside them. If your integration also needs, say, a messaging API or a commerce API that is not in the bundle, you are back to a second client, which is the fragmentation the Business SDK was created to remove.

The second boundary is version coupling. The releases here are v26.0.2, v26.0.1 and v26.0.0, and they track Meta's API versions. When Meta versions an API and the SDK follows, your dependency moves, and the readme in the copy available here does not document a compatibility matrix between SDK releases and Graph API versions, so that mapping has to come from Meta's own documentation.

The third is the licence. The repository's licence is a custom one that GitHub cannot classify, and the readme links to the LICENSE file rather than summarising the terms. The badge in the readme names it as the Facebook Platform licence. For a package you install into a product, that file is what governs what you may do with it, and it is a short read before you adopt it rather than a question to answer later.

On maintenance, the repository is not archived and the last push was on 2026-09-21, with v26.0.2 published the same day, so the package is being kept in step with the platform. The examples directory is the best guide to what the SDK actually supports in practice, with files covering ad sets, ad creatives, labels, bidding and batch operations, including BatchExample.js and BasicExample.js.

Editorial conclusion

facebook-nodejs-business-sdk fits Node.js teams that manage Meta advertising accounts, campaigns and Pages through more than one Meta API and want one dependency and one access model instead of several. It is a poor fit if you only need the Graph API, if you cannot live with a package whose releases follow Meta's API versioning, or if your build refuses to take a dependency that still ships a Bower path and a Gulp based toolchain. Check first that the API version your app is registered against matches the SDK release you install, that your token carries the permissions the calls require, and that the custom licence in the LICENSE file fits how you redistribute the SDK.

Frequently asked questions

Official sources

1. facebook/facebook-nodejs-business-sdk on GitHub
2. Issues
3. Project website
4. README
5. Releases