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 this 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. 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

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.

To open a line of credit:

  1. Open Parent 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.

Once you have a credit line set up in Business Manager, you need to mark that as shareable so that your child Business Managers can access it.

Create an Admin System User

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

If an Admin system user does not already exist, create one on the parent Business Manager to programmatically manage assets and ads:

  1. Go to Business Settings > System Users > +Add.
  2. Once you have an Admin system user, generate a long-lived access token with ads_management and business_management permissions. Store it for later use.
  3. Click the user > Generate New Token .

Grant "Finance Editor" Role to the System User

Granting the Finance Editor role to the system user allows the system user to share the proper payment method to the child BM:

  1. From your Business Manager, go to Settings > System Users > select your user.
  2. Next to the Admin system usern's name, click Edit.
  3. Under Finance Role, select Finance Editor.
  4. Click Update System User.

Learn more about Business Manager System User and About Your Business Settings in Business Manager, Ads Help Center to create a system user in the Business Manager tool.

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 Up Payment Method

The parent Business Managers create and manage child Business Managers. The parent Business Manager is responsible for paying for any activity of the children Business Managers.

To pay for the child Business Manager advertisements, we recommend to use a line of credit.

Line of Credit


Step 1. Open a line of credit

Contact your Facebook representative and open a LOC within that Business Manager if does not already exist. The line of credit will display as a payment method in Business Manager.

Step 2. Make the line of credit shareable

Once you have a credit line set up in Business Manager, you need to make that as shareable so that your child Business Managers can access it. This setup adds a new funding source in the child Business Manager.

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

  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.

Step 3. Fetch the line of credit ID and share with child Business Manager

  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 parent Business Manager line of credit ID in the API call below to share the line of credit 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

If you don't specify an amount, your line of credit is equally divided among your child Business Managers.

If you specify an amount only, that portion of your line of credit is assigned to the child Business Manager.


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 (LOC)

  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
    Alternatively, you can fetch the funding source by going to your child Business Manager and selecting Payments > click Credit Line Payment method. This populates the URL with a payment parameter as follows:
    payment-methods/<CHILD_PAYMENT_METHOD_ID>?business_id=
  3. Store this payment method ID for later use.

Create a New Ad Account with the Default Funding Source

Use the payment method ID from the child Business Manager as the funding_id parameter.

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

Create an Admin System User

  1. If one does not already exist, create an Admin system user on the parent Business Manager. System users represent servers or software making API calls to assets owned or managed by a Business Manager.

  2. Once you have an Admin system user, generate a long-lived access token and store it for later use.

Learn more about Business Manager System User and About Your Business Settings in Business Manager, Ads Help Center to create a system user in the Business Manager tool.

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.

Next topics include additional features/actions you can use to augment your Business Manager experience.

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. Thereafter, 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:

  1. Fetch the child Business Manager's system user access token.
  2. 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
  3. Fetch all ad accounts for the child Business Manager.
  4. 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.
  5. 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>/
  6. Delete the child Business Manager.
  7. 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.