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 that enable you to create a business manager, ad account and other assets programmatically 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 (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

To request this App capability to be added to your application, fill out the form. Once approved, you can use the APIs below. Apply Now

  1. Create a Business Manager if one doesn't already exist. (This Business Manager is referred to below as a parent Business Manager.)
  2. 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.
  3. 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.

  4. Create a Facebook Marketing App if one doesn’t already exist.
    • Click Create an App.
    • Ask Facebook to whitelist the app granting it permissions to access the API endpoints used in the two-tier Business Manager solution.
  5. 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.

  6. 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. Learn more
  7. Assign the Finance Editor role to the system user.
    • Go to the People and Assets tab > 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

  1. Create a child Business Manager using the code snippet below. Store this child Business Manager ID for the user.

  2. Note: 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.
  3. 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 > 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
  4. 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.
  5. 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
  6. Fetch the new funding source in the child Business Manager. For this example, use this funding source later when creating an ad account.
  7. 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.
  8. 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.
  9. 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
  10. Fetch the system user's ID.
  11. curl -G \
      -d 'access_token=<ACCESS_TOKEN>' \
      -d 'appsecret_proof=<APP_SECRET>' \
      https://graph.facebook.com/<VERSION>/<CHILD_BM_ID>/system_users
  12. Add the system user as an admin to the new ad account under the child Business Manager.
  13. curl \
      -F 'user=<SYSTEM_USER_ID(from above)>' \
      -F 'role=ADMIN' \
      -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.

  1. Fetch the child Business Manager's system user's 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/<VERSION>/<CHILD_BM_ID>/access_token
  3. 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.
  4. 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'));
      }
    }
  5. Delete the child Business Manager using this API call.
  6. 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.

  1. Fetch the access token of the system user of the child Business Manager.
  2. curl -X DELETE \
      -d 'id=<CHILD_BM_ID>' \
      -d 'app_id=<App_ID>' \
      -d 'access_token=<ACCESS_TOKEN>' \
      -d 'appsecret_proof=<APP_SECRET>' \
      https://graph.facebook.com/<VERSION>/<CHILD_BM_ID>/owned_businesses
    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";
  3. Add a user to the child Business Manager.
  4. 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);
  5. 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.
  6. 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.

  1. Create an invoice group.
  2. 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"
  3. Delete an invoice group.
  4. curl -i -X DELETE \
    -d "access_token=<access token sanitized>" \
     "https://graph.facebook.com/<VERSION>/<INVOICE_GROUP_ID>"
  5. Update the invoice group; for example, change the name or email associated with an invoice group.
  6. 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>"
  7. Add an ad account in an invoice group.
  8. 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"
  9. Remove an ad account in an invoice group.
  10. 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"
  11. Check the invoice group to that an ad account belongs.
  12. curl -i -X GET \
     "https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>?fields=extended_credit_invoice_group&access_token=<access token sanitized>"

FAQ

Can I use this solution if I don't have a line of credit open? 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.

Can a user have more than one child Business Manager? 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.

Can I add a user to the child Business Manager? Yes, the Parent Business Manager can grant access to a user if they choose to do so.

How can I test creating Child BMs while my app is still pending approval for 'business_management' permissions? 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 on the 'Add' button. 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 on "Create Test Users" button. (You will need your app to be approved first in order to be able to make the api calls)

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

Prerequisites

  • Your app has the capability to be able to create Child BMs.
  • The App is owned by the Business that is whitelisted.
  • 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.

Below are the steps on how to setup a heroku server that listens for notifcations on webhooks.

Steps

  • Create an Account on Heroku.com (http://heroku.com/) (Any other server should work as well.)
  • Deploy the following code to the heroku server. (https://github.com/mduppes/webhooks_test/tree/master).
  • For Heroku.com, set up the 'Config Variables' in the 'Setting' session: APP_SECRET is obtained from the Facebook developer dashboard (https://developers.facebook.com/apps/) for your app. This is needed to verify that an update came from a Facebook server. VERIFY_TOKEN is your "password" for setting up a webhooks subscription.
  • Add the Webhooks in the Facebook 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 you set.
  • Find the 'ad_account' and subscribe it, you can make a test call if you want through the webhook UI.

How do I modify the extended credit amount limit set while sharing the Line of credit to child BM? 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> "