Business Onboarding

If you manage hundreds or thousands of small businesses and want to offer them ads buying within your website or platform, you can use Business Onboarding APIs. This enables you to create a business manager, ad account and other assets via the API on behalf of your clients.

You have access to the assets you create and get to maintain a billing relationship with your client for any Facebook Ads created on their behalf by sharing your line of credit with the new child Business Manager created for your clients.

When you use this two-tier Business Manager solution, you can create a child Business Manager on behalf of your client using their user access token and a Facebook page that is owned by them. They don't have access to the child Business Manager, by default, but you have complete access to the child Business Manager, and can chose to give your clients permission if they have a use case for it. Some additional notes about this setup:

  • This child Business Manager has a system user attached to it with ADVERTISER access to the page provided by your client during child Business Manager creation. Using the access token of the system user for the child Business Manager, an ad account can be created for the child Business Manager and any other assets such as Pixel, Custom Audience, Product Catalog, and so on can be associated with it.
  • When you create a child Business manager via POST {business_id}/owned_businesses, you need to have the permission business_management, see Permissions with Facebook Login, Granular Permissions.
  • You can also share the line of credit, known as LOC, attached to your parent Business Manager with its child Business Manager, and assign a spend limit to it to prevent accidental overspend.

Get Started - Prerequisites

  • Create a Business Manager if one doesn't already exist. This Business Manager is referred to below as a parent Business Manager.

  • Contact Facebook and open a LOC within that Business Manager if one doesn’t already exist. The LOC appears as a payment method in Business Manager. The LOC is useful if you want to pay for the users ads and directly charge them for ads created.

Once you set up a LOC in Business Manager, you need to mark that as **shareable* so that your child Business Managers have access to it:

  • In Business Manager, go to Line of Credit payment method.

  • Go to Credit Settings and click Manage Credit allocations with your app. Using the Credit Allocation API, you can allocate your extended credit to another business and adjust allocations directly from your own application. Required: You must read and accept the Legal Terms before you can use the API.


  • Create a Facebook Marketing App if one doesn’t already exist. Click Create an App.

Ensure that your app has extended manage_business permissions. These permissions enable your app to retrieve page access tokens to create a Business Manager on behalf of the person. You will need to request those permissions if they don't exist already.

  • Go to your App Dashboard | App Review tab.

  • Click Start a Submission and complete the flow to fetch Business_Management scopes for your app.

You may be required to configure the basic settings, such as App logo, to create a submission.

Create a system user under the parent Business Manager if one doesn't already exist. Generate the long-lived access token and store it for later use. See Business Manager API, System User. Assign the Finance Editor role to the system user.

  • Go to the People and Assets tab and select Admin System User.

  • Next to the system user's name, click Edit and change the Finance Role to Finance Editor.


You are now ready to create a child Business Manager on behalf of the user.

Onboard a New Client

Create a child Business Manager using the code snippet below. Store this child Business Manager ID for the user. There can only be one child Business Manager per user for a given Partner. To delete the child Business Manager, you need to pause all ads under the ad account, under the child Business Manager, and call the delete API.

curl \
  -F 'id=<Parent Business Manager Id>' \
  -F 'name=Advertisers child BM' \
  -F 'vertical=OTHER' \ // Specify the Business vertical
  -F 'shared_page_id=<PAGE_ID_FROM_USER>' \  //Optional parameter
  -F 'page_permitted_roles=["ADVERTISER"]' \
  -F 'timezone_id=1' \
  -F 'access_token=<CLIENTS_ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/<Parent_BM_Id>/owned_businesses

This returns a child business manager id.

Share the LOC from the parent Business Manager to the new child Business Manager. This adds a new funding source in the child Business Manager.

  • To fetch the LOC ID, go to your parent Business Manager then select Payments and click the credit line payment method. This populates the URL with a payment parameter payment-methods/PARENT_BM_Line_Of_Credit_ID?business_id=.

  • Use this ID in the API call below to share the LOC from the parent to the child Business Manager. Amount is an optional parameter.

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

curl \
  -F 'receiving_business_id=<CHILD_BUSSINESS_MANAGER_ID>' \
  -F 'amount=10<OPTIONAL PARAMETER>' \  
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/<PARENT_BM_Line_Of_Credit_ID>/owning_credit_allocation_configs

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=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/<CHILD_BUSINESS_MANAGER_ID>/access_token

Fetch the new funding source in the child Business Manager. For this example, use this funding source later when creating an ad account.

curl -G \
  -d 'fields=id,allocated_amount' \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/<CHILD_BUSINESS_MANAGER_ID>/extendedcredits

#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=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/CHILD_BM_ID/adaccount

Fetch the system user's ID:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/<CHILD_BM_ID>/system_users

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=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/<act_ACCOUNT_ID>/assigned_users

You have now just created a child Business Manager for a user under a partner's parent Business Manager.

Delete a Child Business Manager

As a partner, you can only create one child Business Manager per user. This child Business Manager doesn't count against their limit of how many Business Managers a user can create. You can delete an existing child Business Manager by using the following code snippets.

Fetch the child Business Manager's system user's 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/<VERSION>/<CHILD_BM_ID>/access_token

Fetch all ad accounts for the client Business Manager and mark all campaigns under them as PAUSED. Otherwise, any deleted 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/<VERSION>/<CHILD_BM_ID>/owned_ad_accounts
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'appsecret_proof=<APP_SECRET>' \ 
  https://graph.facebook.com/<VERSION>/<act_AD_ACCOUNT_ID>/campaigns
curl \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  https://graph.facebook.com/<VERSION>/<CAMPAIGN_ID>/

PHP SDK

/**
 * Step 2 Fetch all the ad accounts for the client bm and mark all
 * campaigns under them as paused. All campaigns are required to be
 * paused before the client business manager can be deleted.
 */
echo 'Fetch all ad accounts for business manager id:'
  .$child_business_id.PHP_EOL;
$api = setAccessToken($partner_access_token);
$ad_accounts = (new Business($child_business_id))
  ->getOwnedAdAccounts(array(), array());
foreach($ad_accounts as $ad_account) {
  $api = setAccessToken($child_bm_system_user_access_token);
  echo 'Fetch all Campagins for Ad account id:'.$ad_account->id.PHP_EOL;
  $campaigns = (new AdAccount($ad_account->id))
    ->getCampaigns(array(), array());
  foreach ($campaigns as $campaign) {
    echo 'Marking Campagin id:'.$campaign->id.' as paused.'.PHP_EOL;
    $updated_campaign = (new Campaign($campaign->id))
      ->updateSelf(array(), array('status' => 'PAUSED'));
  }
}

Delete the child Business Manager using this API call.

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

PHP SDK

/**
 * Step 3 Delete the client business manager.
 */
$api = setAccessToken($partner_access_token);
$params = array(
  'client_id'  => $child_business_id,
);
(new Business($child_business_id))->deleteOwnedBusinesses(array(), $params);

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

By default, only the system user is 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 you how you can add yourself to the Child Business Manager and log in to Business Manager UI to access the new child Business Manager created.

Fetch the access token of the system user of the child Business Manager.

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/<VERSION>/<CHILD_BM_ID>/access_token

PHP SDK

/**
 * Step 1 Create access token System user under child BM.
 * This uses the Aggregators access token.
 */
$api = setAccessToken($aggregator_access_token);
$child_business_token = (new Business($child_business_id))
 ->createAccessToken(
  array(),
  array(
    'id' => $child_business_id,
    'app_id' => $app_id,
    'scope' => 'manage_pages,ads_management,business_management',
  ));
$child_bm_system_user_access_token = $child_business_token->access_token;
echo $child_bm_system_user_access_token."\n";

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/<VERSION>/<CHILD_BM_ID>/business_users

PHP SDK

/**
  * Step 2 Send an invitation link to the user with the email below.
  * The user will get an email with a link clicking on which will take
  * them to the setting up a Business manager user UI flow.
  */
  $child_bm_system_user_access_token =
  $api = setAccessToken($child_bm_system_user_access_token);
  $params = array(
    'email' => '<EMAIL_ADDRESS_OF_USER>',
    'role' => 'ADMIN',
    'roles' => [],
  );
  (new Business($child_business_id))->createBusinessUser(array(), $params);

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 just go to it. Simply parse the invite_link field from the response below. 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/<VERSION>/<CHILD_BM_ID>/owned_businesses

PHP SDK

/**
 * Step 3 You can programmatically fetch the pending invitation link to
 * BM in order to complete the BM user sign up flow. This api call is
 * used for debugging.
 * An actual user would click on the link from their email.
 */
$response = (new Business($child_business_id))
  ->getPendingUsers(array(), array('fields' => 'invite_link',));
$invite_link = $response[0]->invite_link;
echo 'The user who was sent the invitation
  above was sent an invitation email.';
echo 'Copy the link below and paste it into the browser. Accepting this
  invite grants the user access to the Child Business Manager.';
echo 'Invite Link:  '.$invite_link.PHP_EOL;

Use an Invoice Group

By default, the Partner will receive 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 will be sent out. 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/<VERSION>/<EXTENDED_CREDIT_ID>/extended_credit_invoice_groups"

Delete an invoice group.

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

Update the invoice group; for example, 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/<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/<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/<VERSION>/<INVOICE_GROUP_ID>/ad_accounts"

Check the invoice group to that an ad account belongs.

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

FAQ

Q: Can I use this solution if I don't have a line of credit open?

A: Currently, we only support a line of credit payment method for this setup via the API. You can create a child BM and Ad Account, add the user to the BM or Ad Account as a finance editor or admin and send them to the UI for Ad Account / BM and have them enter the credit card manually.

Q: How can I get started with testing and development on these APIs?

A: You can start testing using test users on your App. Here's how you can do that,

  • Log in to your app dashboard and add a test user Create a test user (Replace BM ID and App_id with actual Ids)
  • Now click on the Edit button and generate and access token with the following permissions, business_management and ads_management
  • Now generate an access token for that test user by clicking on Edit > Get an access token for this test user.
  • Now create a Facebook page or use one that already exists for testing.
  • Add this newly created user as an admin to that test page. Go to this url, Add test user to page (Replace page_id with actual page id)
    • Click on ‘Assign a new Page role’
    • Select Page Admin
  • Now use the test user in the api calls.

Q: Can a user have more than one child Business Manager?

A: No. A user cannot be associated with more than one child Business Manager per Partner. The business managers created by the partner do not count against the limit for how many business managers a user can have.

Q: Can I add a user to the child Business Manager?

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

Q: How can I test creating Child BMs while my app is still pending approval for 'business_management' permissions?

A: While your app is waiting for manage_business permissions you can still test things end to end by doing the following, Go to the App dashboard, then go to roles, then go to test users sub menu. Now create a new test user by clicking Add. Mark Authorize Test Users for This App? as yes. In login permissions add ads_management and business_management to the list of permissions. Now click Create Test Users. You need your app to be approved first in order to be able to make the API calls.

Q: How to get real time notification on Ad Account being disabled through webhooks?

A: Meet these prerequisites:

  • Your app has Business Management permissions.
  • Your app is standard tier App.
  • The Ad Accounts should be owned by Child BMs that roll up into the parent BM.
  • Any Ad Account directly under the Parent Business will also send out Webhook notifications.

Set up a Heroku server that listens for notifcations on webhooks:

  • Create an Account on Heroku. Any other server should work as well.
  • Deploy the following code to the heroku server: webhooks_test.
  • For Heroku, set up the 'Config Variables' in the Setting session. 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.
  • Add the webhooks to your app by visiting https://developers.facebook.com/apps/{app_id}/webhooks/
  • Select the Application from the selector, and click Subscribe to the topic
  • Use the webhook address and input the VERIFY_TOKEN that you set.
  • Find the ad_account and subscribe to it. You can now make a test call through the webhook UI.

Q: How do I modify the extended credit amount limit set while sharing the Line of credit to child BM?

A: 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,

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

Each Child BM will have a unique Allocation config who 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/<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/<VERSION>/<allocation config id>?fields=access_token=<Access_token> "