Facebook Business SDK for Node.js

24.0.1 verified Sat Apr 25 auth: no javascript

The Facebook Business SDK for Node.js (v24.0.1) is the official SDK from Meta for interacting with the Facebook Marketing API, Pages API, Business Manager API, Instagram API, and other Facebook APIs. Released monthly in sync with API version updates, it supports both server-side (Node.js) and client-side (browser) usage via UMD/AMD/CommonJS modules. Key differentiators: bundles multiple Facebook APIs into one SDK, includes request-level retry logic, and provides TypeScript definitions. Compared to raw HTTP requests or third-party wrappers, it handles authentication, rate limiting, and pagination automatically. Requires a Facebook App ID and access token; deprecated features are communicated via version bumps.

Common errors

error Error: Cannot read properties of undefined (reading 'access_token') ↓

cause FacebookAdsApi.init() not called, or access token not passed correctly.

fix

Ensure you call FacebookAdsApi.init(accessToken, appSecret) with valid strings.

error TypeError: FacebookAdsApi is not a constructor ↓

cause Using 'new FacebookAdsApi()' instead of the static factory method init().

fix

Use FacebookAdsApi.init(accessToken, appSecret) instead of new.

error Error: (#100) Invalid parameter ↓

cause Missing required fields in API call, or using invalid parameters for current API version.

fix

Check that all required fields are included and are correct per the Marketing API documentation for your SDK version.

Warnings

breaking Advantage+ Shopping Campaigns (ASC) and Advantage+ App Campaigns (AAC) cannot be created or updated via Marketing API starting v25.0, extending to all versions by May 19, 2026. ↓

fix Migrate to Advantage+ setup using the streamlined Automation Unification. Use 'adv campaign' parameter instead.

deprecated Legacy metrics (Page Reach, Impressions, 3-second Viewers) are planned for deprecation in June 2026. ↓

fix Replace with new metrics as per Facebook Ads Insights migration guide.

breaking Dynamic Media is enabled by default for Advantage+ Catalog ads starting v24.0. Must explicitly opt out if static media is required. ↓

fix Set 'dynamic_media' parameter to false in ad creative when creating ads.

breaking Daily budget flexibility increased from 25% to 75% starting v24.0. Campaigns may spend more on high-opportunity days. ↓

fix Review weekly spend limits; adjust campaign budget optimization settings to keep daily budget within bounds.

deprecated Deprecated 'use_jpg_2000' and 'use_wii' parameters as of v21.0. ↓

fix Remove them; they have no effect.

gotcha When using 'FacebookAdsApi.init()', you must call it before creating any API objects. Forgetting to call init() results in silent failures. ↓

fix Always call FacebookAdsApi.init(accessToken, appSecret) as the first step.

Install

npm install facebook-nodejs-business-sdk

yarn add facebook-nodejs-business-sdk

pnpm add facebook-nodejs-business-sdk

Imports

facebook-nodejs-business-sdk
wrong
```
const FacebookAdsApi = require('facebook-nodejs-business-sdk')
```
correct
```
import FacebookAdsApi from 'facebook-nodejs-business-sdk'
```
Default export provides the API client class. CJS require works but TypeScript prefers ESM imports.

AdAccount

wrong

const AdAccount = require('facebook-nodejs-business-sdk').AdAccount

correct

import { AdAccount } from 'facebook-nodejs-business-sdk'

Named exports for each API object (AdAccount, AdSet, Campaign, etc.) are available since v5+.

FacebookAdsApi.init
wrong
```
new FacebookAdsApi(accessToken, appSecret)
```
correct
```
FacebookAdsApi.init(accessToken, appSecret)
```
init() is a static factory method; constructing directly is deprecated since v16 and will break.

AccessToken

wrong

import AccessToken from 'facebook-nodejs-business-sdk'

correct

import { AccessToken } from 'facebook-nodejs-business-sdk'

AccessToken is a named export, not default. Use destructured import.

Quickstart

Initialize the SDK, create an AdAccount object, and fetch ad sets with specific fields.

import FacebookAdsApi, { AdAccount } from 'facebook-nodejs-business-sdk';

const accessToken = process.env.FACEBOOK_ACCESS_TOKEN ?? '';
const appSecret = process.env.FACEBOOK_APP_SECRET ?? '';
const adAccountId = 'act_<AD_ACCOUNT_ID>';

FacebookAdsApi.init(accessToken, appSecret);

const account = new AdAccount(adAccountId);

account.getAdSets(['name', 'status', 'daily_budget'])
  .then(adsets => {
    adsets.forEach(adset => {
      console.log(adset.name, adset.status, adset.daily_budget);
    });
  })
  .catch(err => console.error(err));