2-Tier Business Manager Solution

Overview

Business Managers are a way for Facebook to associate assets that include ad accounts, the Facebook pixel, business users, ad activity, and more to a business. Facebook expects to use Business Managers as a container to represent a business.

The 2-tier Business Manager solution is a scalable solution for a Business Manager to create and manage child businesses, and allows you to:

  • Create and delete hundreds or thousands of small Business Managers (child Business Managers) underneath a parent Business Manager
  • Create a small business presence
  • Create assets for the user
  • Offer Facebook ads to your end user on your website or platform

How it Works

The 2-tier Business Manager solution provides the ability to own the full workflow of creating, managing, and deleting Business Managers via a single parent Business Manager. (Newly created Business Managers are referred to as child Business Managers).

To use the 2-tier Business Manager solution, your Business Manager (referred to as parent Business Manager) creates a child Business Manager on behalf of your client using a user access token and Facebook page. By default, the client does not have access to the child Business Manager, but you have complete access to the child Business Manager, and can choose to give permission to the client based on their use case.

In this framework, the parent Business Manager pays for the child Business Managers’ ad activity and bills their clients separately. This is meant to allow full control over ad activity and reduce friction of asking clients to approve of every modification. This means you must pay for the ads and then choose one of these options:

  • Bill clients before serving ads
  • Bill clients after serving ads

The purpose of using this framework is to manage the newly created/managed child Business Managers in a scalable, maintainable way.

Use Cases

  • A commerce platform who helps small merchants sell Facebook ads
  • A software as a service (SaaS) provider for agencies who need help onboarding their small-to-medium sized business (SMB) clients (where each agency would represent a parent Business Manager)
  • You are a national brand managing your local brand’s ad activity. This includes
    • Targeting
    • Ad creatives
    • Branding
    • Budgeting

When Not To Use

  • If you don’t want the liability of paying for all ad activity, then consider using the Business On Behalf Of API.
  • If you don’t want to pay for the clients’ ad activity, but only manage their assets, then consider using the Business On Behalf Of API.
  • If you only want to manage a few set of clients, consider using agency access instead. This allows the access to assets, such as ad accounts, pixels, product catalogs, and so on, without having to build on top of the 2-tier Business Manager solution.

Get Started

Requirements

  1. You must have a Facebook Marketing App. If one doesn’t already exist, in your App dashboard, click Create App. See Create a Facebook Marketing App.

  2. Contact your Facebook representative to whitelist the app, granting it permission to access the API endpoints used in the 2-tier Business Manager solution.

  3. From App Review and Features, assign the following required permissions:

    • business_management—Allows the creation of Business Managers
    • ads_management—Allows the ability to read and manage ad activity for admins and developers of the app
    • Ads Management Standard Access—Optional. Gives higher rate limits and allows users (who are not admins or developers of the app) to manage and create ad accounts

These permissions enable your app to create Business Managers on behalf of the end user.

App Review requires your App to be public, no longer in development mode. We recommend to add basic settings, such as an App icon or logo, in your App dashboard. Learn more about App Development.

Set Up Your Parent Business Manager

Before you set up your parent Business Manager, determine which Business Manager will be your designated parent Business Manager.

This parent Business Manager:

  • Creates children Business Managers
  • Must own the application making the API calls

Open a Line of Credit with Facebook

The child Business Managers are created and managed by the parent Business Manager. The parent Business Manager is responsible for paying for any child Business Manager activity.

Contact your Facebook representative and open a line of credit (LOC) within that Business Manager if one doesn’t already exist. The LOC will display as a payment method in Business Manager.

If your parent Business Manager doesn’t have a LOC, we won’t have a way to pay for your child Business Managers ad activity.

Fetch the LOC ID

  1. Go to your parent Business Manager and select Payments > click Credit Line Payment method.

    This populates the URL with a payment parameter payment-methods/PARENT_BM_Line_Of_Credit_ID?business_id=.

  2. Use this ID in the API call below to share the LOC ID from the parent to the child Business Manager. The amount is optional.

curl \
  -F 'receiving_business_id=<CHILD_BUSINESS_MANAGER_ID>' \
  -F 'amount=10<OPTIONAL_PARAMETER>' \  
  -F 'access_token=<Parent_BM_Admin_System_User_Access_Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \ 
  https://graph.facebook.com/<API_VERSION>/<PARENT_BM_Line_Of_Credit_ID>/owning_credit_allocation_configs

Important: If you don't specify an amount, your LOC is equally divided among your child Business Managers. If you specify an amount only, that portion of your LOC is assigned to the child Business Manager.

Create an Admin System User

System users represent servers or software making API calls to assets owned or managed by a Business Manager.

  1. If an Admin system user does not already exist, create one on the parent Business Manager to programmatically manage assets and ads.
  2. Once you have an Admin system user, generate a long-lived access token and store it for later use.

See About Your Business Settings in Business Manager, Ads Help Center to create a system user in the Business Manager tool.

Grant a Finance Editor Role to the System User

  1. From your Business Manager, go to People > Assets (tab).
  2. Click Edit next to the Admin system user's name.
  3. Assign the Finance Role to Finance Editor.
  4. Click Update System User.

Learn more about Business Manager System User.

Set Up a New Child Business Manager

The 2-tier Business Manager solution was originally designed so that each user access token could only create one child Business Manager. However, the user can now create multiple child Business Managers as long as a primary page is set on each child Business Manager.

Create a Child Business Manager

  1. Using the user access token, create one or more child Business Managers.
  2. A user can have only 1 child Business Manager, unless the user assigns a primary page to the child Business Manager.

  3. Assign a shared_page_id field with the client’s page ID.

Example — Returns a child Business Manager ID

curl \
  -F 'id=<Parent_Business_Manager_ID>' \
  -F 'name=Advertisers child BM (recommend naming similar to page)' \
  -F 'vertical=OTHER' \ // Specify the Business vertical
  -F 'shared_page_id=<PAGE_ID_FROM_USER>' \  //Optional parameter but needed if you want to publish ads promoting this page
  -F 'page_permitted_tasks=["ADVERTISE", "ANALYZE"]' \
  -F 'timezone_id=1' \
  -F 'access_token=<USER_Personal_Access_Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<PARENT_BM_Id>/owned_businesses

Response:

{
“ID” : “12312812123132”  //store this child business manager ID and associate to user
}

Set a Primary Page on the Child Business Manager (Optional)

A page can only be the primary page for one Business Manager. If the page has already been assigned to a Business Manager and if the user wants to create multiple child Business Managers, then you must ask the user to unassign their page from the existing Business Manager. This design is usually intended for agencies who are managing multiple clients.

If the page is set as a primary page on an existing Business Manager, then you cannot assign the primary page to another Business Manager.

To set a primary page on the child Business Manager:

curl \
  -F 'primary_page=<PAGE_ID_FROM_USER>' \
  -F 'access_token=<CLIENTS_ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
 https://graph.facebook.com/<API_VERSION>/<CHILD_BM_ID> 

Learn more about Business Manager.

Share the LOC

Required: You must read and accept the Legal Terms before you can use the API.

Use the parent Admin system user token to share the LOC from the parent Business Manager to the new child Business Manager.

  1. Open Business Manager > Business Settings > Payment Methods.
  2. Click Credit Settings and select Manage Credit allocations with your app.
  3. You can allocate your extended credit to another business and adjust allocations directly from your own application.

This adds a new funding source in the child Business Manager.

Create and Get the Child System User Token

Under the child Business Manager, fetch the system user's access token. This token is used for all subsequent calls to the child Business Manager for creating or managing ads for this user.

curl \
  -F 'id=<CHILD_BUSINESS_MANAGER>' \
  -F 'app_id=<App_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<Parent BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<CHILD_BUSINESS_MANAGER_ID>/access_token

Get the Funding Source ID

  1. Fetch the new funding source in the child Business Manager. For this example, use this funding source later when creating an ad account.
  2. curl -G \
      -d 'fields=id,allocated_amount' \
      -d 'access_token=<Child BM Admin System User Access Token>' \
      -d 'appsecret_proof=<APP_SECRET>' \
      https://graph.facebook.com/<API_VERSION>/<CHILD_BUSINESS_MANAGER_ID>/extendedcredits
  3. Store this payment method ID for later use.

Create a New Ad Account with the Default Funding Source

Use this default funding source as in the child Business Manager backed by the shared LOC from the parent Business Manager.

curl \
  -F 'name=Advertisers Ad Account' \
  -F 'currency=USD' \
  -F 'timezone_id=1' \
  -F 'end_advertiser=<PAGE_ID>' \
  -F 'media_agency=NONE' \
  -F 'partner=NONE' \
  -F 'funding_id=<PAYMENT_METHOD_ID(from above)>' \
  -F 'access_token=<Child BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/CHILD_BM_ID/adaccount

Fetch the System User's ID

curl -G \
  -d 'access_token=<Child BM System User Access Token>' \
  -d 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<CHILD_BM_ID>/system_users

Add the System User as an Admin to the New Ad Account

Add the system user as an admin to the new ad account under the child Business Manager:

curl \
  -F 'user=<SYSTEM_USER_ID(from above)>' \
  -F 'tasks=MANAGE,ADVERTISE,ANALYZE' \
  -F 'business=<CHILD_BM_ID>' \
  -F 'access_token=<Child BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<act_ACCOUNT_ID>/assigned_users

Congratulations! This is the final step in setting up a Business Manager to create and manage child businesses.

Find Child Business Managers

To find all child Business Manager IDs, run the following command to filter by client’s app scoped user ID:

curl \
curl -i -X GET \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
"https://graph.facebook.com/<API_VERSION>/<parent_bm_id>/owned_businesses?client_user_id=<Client’s app scoped user ID>

Find the App scoped user ID with /me?fields=ids_for_apps (client user access token).

Add a User to the Child Business Manager, Optional or Debugging

By default, only the system user is created and added to the child Business Manager. You can add an advertiser to the child Business Manager if there is a business case to add it. Adding a developer to a child Business Manager is quite useful for debugging purposes. The script below shows how you can add yourself to the child Business Manager and log in to the Business Manager UI to access the newly created child Business Manager.

Fetch the Access Token of the Child Business Manager's System User

curl \
  -F 'id=<CHILD_BM_ID>' \
  -F 'app_id=<APP_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<CHILD_BM_ID>/access_token

Add a User to the Child Business Manager

curl \
  -F 'email=<EMAIL_ADDRESS_OF_USER>' \
  -F 'role=ADMIN' \
  -F 'roles=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<CHILD_BM_ID>/business_users

Join the Business Manager (Optional)

If you don't want to check your email to accept the invitation to join the Business Manager, you can query for it via the API and directly go to it:

  1. Parse the `invite_link` field from the response below.
  2. Go to a browser to the URL returned in this API call.

You will be prompted to log in using your Facebook account; after which you'll get access to the child Business Manager.

curl -X DELETE \
  -d 'client_id=<CHILD_BM_ID>' \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<PARENT_BM_ID>/owned_businesses

Delete a Child Business Manager

To delete an existing child Business Manager:

Fetch the Child Business Manager's System User Access Token

curl \
  -F 'id=<CHILD_BM_ID>' \
  -F 'app_id=<APP_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<CHILD_BM_ID>/access_token

Fetch All Ad Accounts for the Client Business Manager

Once you fetch the ad account, mark all campaigns under them as PAUSED. Otherwise, any delete call to a child Business Manager with active campaigns under it won't succeed.

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<CHILD_BM_ID>/owned_ad_accounts
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'appsecret_proof=<APP_SECRET>' \ 
  https://graph.facebook.com/<API_VERSION>/<act_AD_ACCOUNT_ID>/campaigns
curl \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<CAMPAIGN_ID>/

Delete the Child Business Manager

curl -X DELETE \
  -d 'client_id=<CHILD_BM_ID>' \
  -d 'access_token=<Parent BM Admin Token (System User)ACCESS_TOKEN>' \
  -d 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<API_VERSION>/<PARENT_BM_ID>/owned_businesses

Use an Invoice Group

By default, the partner receives an invoice for every ad account at the end of the month. To consolidate invoices, you can create an invoice group and add ad accounts into the group up to 3 days before the invoice is sent.

Create an Invoice Group

curl -i -X POST \
  -d "emails=[<EMAIL_ADDRESSES>]" \
  -d "name=<GROUP_NAME>" \
  -d "access_token=<access token sanitized>" \
  "https://graph.facebook.com/<API_VERSION>/<EXTENDED_CREDIT_ID>/extended_credit_invoice_groups"

Update the Invoice Group

Change the name or email associated with an invoice group.

curl -i -X POST \
  -d "emails=[<EMAIL_ADDRESSES>]" \
  -d "name=<GROUP_NAME>" \
  -d "access_token=<access token sanitized>" \
  "https://graph.facebook.com/<API_VERSION>/<INVOICE_GROUP_ID>"

Add an Ad Account in an Invoice Group

curl -i -X POST \
  -d "ad_account_id=<AD_ACCOUNT_ID>" \
  -d "access_token=<access token sanitized>" \
  "https://graph.facebook.com/<API_VERSION>/<INVOICE_GROUP_ID>/ad_accounts"

Remove an Ad Account in an Invoice Group

curl -i -X DELETE \
  -d "ad_account_id=<AD_ACCOUNT_ID>" \
  -d "access_token=<access token sanitized>" \
   "https://graph.facebook.com/<API_VERSION>/<INVOICE_GROUP_ID>/ad_accounts"

Check the Invoice Group

curl -i -X GET \
"https://graph.facebook.com/<API_VERSION>/<AD_ACCOUNT_ID>?fields=extended_credit_invoice_group&access_token=<access token sanitized>"

Delete an Invoice Group

curl -i -X DELETE \
-d "access_token=<access token sanitized>" \
 "https://graph.facebook.com/<API_VERSION>/<INVOICE_GROUP_ID

Support

Use this support for troubleshooting and FAQs.

This error usually means you need to:

  1. Get business_management, ads_management, and standard tier access for your app.
  2. Mark your app as a non-development app.
  3. Apply for App Review for the app to use the APIs.

Without standard-tier access, you can't use certain features of the Marketing APIs.

curl -i -X GET \
 "https://graph.facebook.com/<API_VERSION>/<extended credit line id>?fields=receiving_business&access_token=<access_token>"

Each child Business Manager will have a unique allocation config whose ID you can extract from the API call above. Now use the allocation config ID in the API call below:

curl -i -X POST \
  -d “amount=<amount>” \ 
  "https://graph.facebook.com/<API_VERSION>/<allocation config id>?fields=access_token=<access token> "

Alternatively, you can just delete the config and create a new one:

curl -i -X DELETE \
 "https://graph.facebook.com/<API_VERSION>/<allocation config id>?fields=access_token=<Access_token> "
GET  <graph>/<API_VERSION>/<BUSINESS_ID>/owned_businesses?client_user_id=<app_scoped_user_id>
{
  "error": {
    "message": "(#10) You do not have permission to perform this action. This action requires that you can MANAGE_PERMISSIONS for this business account.",
    "type": "OAuthException",
    "code": 10,
    "fbtrace_id": "alphanumeric string"
  }
}

Most likely the access token you used is not an admin of the parent Business Manager. You should not use the client’s user access token or the child Business Manager admin system user token.

{
  "error": {
    "message": "The Facebook Page you've tried to add is already owned by another Business Manager. You can still request access to this Page, but your request will need to be approved by the Business Manager that owns it.",
    "type": "OAuthException",
    "code": 3918,
    "error_subcode": 1690024,
    "is_transient": false,
    "error_user_title": "Facebook Page Already Belongs to a Business",
    "error_user_msg": "The Facebook Page you've tried to add is already owned by another business. You can still request access to this Page, but your request will need to be approved by the business that owns it.",
    "fbtrace_id": "alphanumeric string"
  }
  }

The primary page has already been set on another Business Manager. It could be that the page has been set on a user’s Business Manager or is connected to an Instagram profile. To solve this, you can use the shared_page_id field when creating the business or updating the business.

Currently, we only support a line of credit payment method for this setup via the API.

  1. Create a child Business Manager and ad account.
  2. Add the user to the Business Manager or ad account as a Finance Editor or admin.
  3. Send the user to the UI for the ad account or Business Manager.
  4. Ask the user to manually enter the credit card.

We recommend storing information associated with the user, including:

  • Child Business Manager ID, created with the `/business_id/owned_businesses` endpoint
  • Child Business Manager Admin system user token, created with the `child_bm/access_token` endpoint

This recommendation makes it easier to manage and reduces overhead.

  1. Log in to your app dashboard.
  2. Add a test user with http://developers.facebook.com/apps/app_id/roles/test-users/?business_id=bmid (Replace `bmid` and `app_id` with actual IDs)
  3. Click Edit and generate and access token with the 'business_management' and 'ads_management' permissions.
  4. Generate an access token for that test user by clicking Edit > Get an access token for this test user.
  5. Create a Facebook page or use one that already exists for testing.
  6. Add this newly created user as an admin to that test page:
    • Go to https://www.facebook.com/page_id/settings/?tab=admin_roles (Replace `page_id` with an actual page ID)
    • Click Assign a new Page role
    • Select Page Admin.
  7. Now use the test user in the API calls.

Yes. A user can be associated with more than one child Business Manager per partner. Each existing child under the partner must have an assigned primary page.

Yes, the parent Business Manager can grant access to a user if they choose to do so.

While your app is waiting for business_management, ads_management, and Ads Management Standard Access permissions, you can still test end-to-end:

  1. Go to the App dashboard.
  2. Go to Roles > Test Users.
  3. Click Add to create a new test user.
  4. Mark Authorize Test Users for This App? as yes.
  5. In Login Permissions, add `ads_management` and `business_management` to the list of permissions.
  6. Click Create Test User.
  7. Once created, click Edit next to the user and select Get an access token for this test user. You can use this test user to replicate a client.
  8. You need your app to be approved first to make the API calls.

You must meet these prerequisites:

  • Your app is a standard tier App.
  • The child Business Managers should own the ad accounts that roll up into the parent Business Manager.
  • Any ad account directly under the parent Business will also send out Webhook notifications.

To set up a Heroku server that listens for notifications on Webhooks:

  1. Create an account on Heroku. Any other server should also work.
  2. Deploy the `webhooks_test` code to the Heroku server.
  3. For Heroku, in the Setting session, set up the Config Variables. You can get `APP_SECRET` from your Facebook App dashboard. You need this to verify that an update came from a Facebook server. `VERIFY_TOKEN` is your password to set up a Webhooks subscription.
  4. Add the Webhooks to your app by visiting **https://developers.facebook.com/apps/{app_id}/webhooks/**.
  5. From the selector, select Application, and click Subscribe to the topic.
  6. Use the Webhook address and input the `VERIFY_TOKEN` that you set.
  7. Find the `ad_account` and subscribe to it.
  8. You can now make a test call through the Webhook UI.

You can either delete the allocation config of the shared extended credit and create a new one or modify the existing one. The allocation config ID is the ID returned at the time of sharing the LOC. You alternatively can fetch it via the API later with this API call that returns allocation config IDs for the extended credit.