Facebook Business SDK

Warnings

• breaking Advantage+ Shopping Campaigns (ASC) and Advantage+ App Campaigns (AAC) can no longer be created or updated via the Marketing API starting v25.0. This change extends to all versions by May 19, 2026, as part of the Automation Unification toward Advantage+ setup.
  Fix: Migrate to the new Advantage+ campaign structure using Advantage+ audience, campaign budget, and placements. Refer to Meta's Advantage+ Campaigns documentation for migration guidance.
• breaking Dynamic Media is enabled by default for Advantage+ Catalog ads via the Marketing API starting v24.0.
  Fix: Developers must explicitly opt out of Dynamic Media if it is not desired for Advantage+ Catalog ads. Review your API integrations to adjust this setting before September 1, 2025, with full enforcement by October 20, 2025.
• breaking The Facebook video feeds ad placement is no longer available in Marketing API v24.0. Attempts to use it will result in errors.
  Fix: Update ad set configurations to remove the Facebook video feeds placement. The Facebook Reels placement is the recommended replacement.
• deprecated Several legacy metrics, including Page Reach, Impressions, and 3-second Viewers, are planned for deprecation in June 2026.
  Fix: Transition to using the new `Media Views` and `Media Viewers` metrics which will replace the deprecated legacy metrics.
• gotcha The SDK relies on specific API versions. If the API version used in your calls (or the default set by the SDK) becomes deprecated, your requests will fail with a 'deprecated version' error.
  Fix: Ensure your application explicitly targets or is compatible with a currently supported Marketing API version (e.g., v25.0). Meta typically supports older API versions for a 90-day grace period after a new version is released.
• gotcha Access tokens have a limited lifespan and require correct permissions. Expired tokens or insufficient permissions (e.g., `ads_read`, `ads_management`) are common causes of API call failures.
  Fix: Regularly refresh access tokens, particularly long-lived ones. Verify that your app and user access tokens have all necessary permissions/scopes for the API calls being made.

Install

• pip install facebook-business Install latest version

Imports

• FacebookAdsApi

  from facebook_business.api import FacebookAdsApi

  The 'facebookads' package is an older, deprecated SDK. The correct package is 'facebook_business'.
• AdAccount

  from facebook_business.adobjects.adaccount import AdAccount

Quickstart

Initializes the Facebook Business SDK and fetches a list of campaigns from a specified ad account. Requires an App ID, App Secret, Access Token, and Ad Account ID with appropriate permissions.

import os
from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount

# --- Configuration (replace with your actual values or environment variables) ---
# Get these from your Facebook Developer App settings
APP_ID = os.environ.get('FB_APP_ID', 'YOUR_APP_ID')
APP_SECRET = os.environ.get('FB_APP_SECRET', 'YOUR_APP_SECRET')
ACCESS_TOKEN = os.environ.get('FB_ACCESS_TOKEN', 'YOUR_ACCESS_TOKEN')

# Get this from your Facebook Ad Account
AD_ACCOUNT_ID = os.environ.get('FB_AD_ACCOUNT_ID', 'act_YOUR_AD_ACCOUNT_ID') # Prefix with 'act_'

# Initialize the API
FacebookAdsApi.init(app_id=APP_ID, app_secret=APP_SECRET, access_token=ACCESS_TOKEN)

try:
    # Create an AdAccount object
    account = AdAccount(AD_ACCOUNT_ID)

    # Fetch campaigns for the ad account
    campaigns = account.get_campaigns(fields=[AdAccount.Field.name, AdAccount.Field.status])

    print(f"Campaigns for Ad Account {AD_ACCOUNT_ID}:")
    for campaign in campaigns:
        print(f"  - ID: {campaign['id']}, Name: {campaign['name']}, Status: {campaign['status']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your APP_ID, APP_SECRET, ACCESS_TOKEN, and AD_ACCOUNT_ID are correct ")
    print("and that your access token has the necessary permissions (e.g., 'ads_read', 'ads_management').")