Common Scenarios

The following code example shows how to:

  • (1) Create a Child BM
  • (2) Share a line of credit between a Parent and Child BM
  • (3) Create a Child BM access token
  • (4) Get the funding source
  • (5) Create an Ad Account under the new Child BM
  • (6) Get the System User for the Client Business
  • (7) Add a System User as an Ad Account Admin
  • (Clean Up) Delete the Child BM we just created
// Step 1. Use an Advertiser’s access token to generate a Child Business Manager.
// This can be fetched by integrating the Facebook Login button on
// your webpage and fetching the Advertiser’s access token after
// the login. The Advertiser does not have access to the BM by default.
// The Partner has root access to Child BM.
$fields = array(
);
$params = array(
  'name' => 'Advertisers child BM',
  'vertical' => 'OTHER',
  'page_permitted_roles' => array('ADVERTISER'),
  'timezone_id' => '1',
);
$child_business = (new Business(<PARTNER_BM_ID>))->createOwnedBusiness(
  $fields,
  $params
);
$child_business_id = $child_business->id;

// Step 2. Share a Line of Credit from a Partner’s Parent BM to Child
// BM (Advertiser’s BM). This uses the Partner’s System User
// access token.
$api = Api::init($app_id, null, <PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>);
$fields = array(
);
$params = array(
  'receiving_business_id' => $child_business_id,
  'amount' => '10',
);
$extended_credit = (new ExtendedCredit(<EXTENDED_CREDIT_LINE_ID>))->createOwningCreditAllocationConfig(
  $fields,
  $params
);

// Step 3. Create an access token of the System User under the Child BM.
// This uses the Partner’s access token.
$api = Api::init($app_id, null, <PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>);
$fields = array(
);
$params = array(
  'app_id' => <APP_ID_FOR_ONBOARDING>,
  'scope' => 'manage_pages,ads_management,business_management',
);
$raw_child_business_token = (new Business($child_business_id))->createAccessToken(
  $fields,
  $params
);
$child_business_token = $raw_child_business_token->access_token;

// Step 4. Fetch the funding source shared with the [Child or Parent] BM. This funding source is used to
// create the Ad account below.
// This uses the Child BM’s access token.
$api = Api::init($app_id, null, $child_business_token);
$fields = array(
  'id',
  'allocated_amount',
);
$params = array(
);
$responses = (new Business($child_business_id))->getExtendedCredits(
  $fields,
  $params
);
$response_id = $responses[0]->id;

// Step 5. Create an Ad Account under the new Child BM.
// This uses the Child BM’s System User access token.
// The System User for their Child BM is the owner of the Ad Account.
$fields = array(
);
$params = array(
  'name' => 'Advertisers Ad Account',
  'currency' => 'USD',
  'timezone_id' => '1',
  'end_advertiser' => <PAGE_ID>,
  'media_agency' => 'NONE',
  'partner' => 'NONE',
  'funding_id' => $response_id,
);
$account = (new Business($child_business_id))->createAdAccount(
  $fields,
  $params
);
$account_id = $account->id;

// Step 6. Fetch the System User for the Client business. This uses the Child
// BM’s access token. This System User ID is used in the Api calls below.
$api = Api::init($app_id, null, $child_business_token);
$fields = array(
);
$params = array(
);
$system_users = (new Business($child_business_id))->getSystemUsers(
  $fields,
  $params
);
$system_user_id = $system_users[0]->id;

// Step 7. Add a System User as an Admin to the Ad Account.
// This uses the Child BM’s access token.
$api = Api::init($app_id, null, $child_business_token);
$fields = array(
);
$params = array(
  'user' => $system_user_id,
  'role' => 'ADMIN',
  'business' => $child_business_id,
);
$assigned_user = (new AdAccount($account_id))->createAssignedUser(
  $fields,
  $params
);

// [CLEAN UP] Delete the Child Business Manager we just created.
// One Client can only have one Child BM under your Parent Business Manager.
// This step uses the Partner's access token.
$api = Api::init($app_id, null, <PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>);
$fields = array(
);
$params = array(
  'client_id' => $child_business_id,
);
(new Business(<PARTNER_BM_ID>))->deleteOwnedBusinesses(
  $fields,
  $params
);
# Step 1. Use an Advertiser’s access token to generate a Child Business Manager.
# This can be fetched by integrating the Facebook Login button on
# your webpage and fetching the Advertiser’s access token after
# the login. The Advertiser does not have access to the BM by default.
# The Partner has root access to Child BM.
fields = [
]
params = {
    'name': 'Advertisers child BM',
    'vertical': 'OTHER',
    'page_permitted_roles': ['ADVERTISER'],
    'timezone_id': '1',
}
child_business = Business(<PARTNER_BM_ID>).create_owned_business(
    fields=fields,
    params=params,
)
child_business_id = child_business.get_id()

# Step 2. Share a Line of Credit from a Partner’s Parent BM to Child
# BM (Advertiser’s BM). This uses the Partner’s System User
# access token.
FacebookAdsApi.init(<ACCESS_TOKEN>=<PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>)
fields = [
]
params = {
    'receiving_business_id': child_business_id,
    'amount': '10',
}
extended_credit = ExtendedCredit(<EXTENDED_CREDIT_LINE_ID>).create_owning_credit_allocation_config(
    fields=fields,
    params=params,
)

# Step 3. Create an access token of the System User under the Child BM.
# This uses the Partner’s access token.
FacebookAdsApi.init(<ACCESS_TOKEN>=<PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>)
fields = [
]
params = {
    'app_id': <APP_ID_FOR_ONBOARDING>,
    'scope': 'manage_pages,ads_management,business_management',
}
raw_child_business_token = Business(child_business_id).create_access_token(
    fields=fields,
    params=params,
)
child_business_token = raw_child_business_token["access_token"];

# Step 4. Fetch the funding source shared with the [Child or Parent] BM. This funding source is used to
# create the Ad account below.
# This uses the Child BM’s access token.
FacebookAdsApi.init(<ACCESS_TOKEN>=child_business_token)
fields = [
    'id',
    'allocated_amount',
]
params = {
}
responses = Business(child_business_id).get_extended_credits(
    fields=fields,
    params=params,
)
response_id = responses[0].get_id()

# Step 5. Create an Ad Account under the new Child BM.
# This uses the Child BM’s System User access token.
# The System User for their Child BM is the owner of the Ad Account.
fields = [
]
params = {
    'name': 'Advertisers Ad Account',
    'currency': 'USD',
    'timezone_id': '1',
    'end_advertiser': <PAGE_ID>,
    'media_agency': 'NONE',
    'partner': 'NONE',
    'funding_id': response_id,
}
account = Business(child_business_id).create_ad_account(
    fields=fields,
    params=params,
)
account_id = account.get_id()

# Step 6. Fetch the System User for the Client business. This uses the Child
# BM’s access token. This System User ID is used in the Api calls below.
FacebookAdsApi.init(<ACCESS_TOKEN>=child_business_token)
fields = [
]
params = {
}
system_users = Business(child_business_id).get_system_users(
    fields=fields,
    params=params,
)
system_user_id = system_users[0].get_id()

# Step 7. Add a System User as an Admin to the Ad Account.
# This uses the Child BM’s access token.
FacebookAdsApi.init(<ACCESS_TOKEN>=child_business_token)
fields = [
]
params = {
    'user': system_user_id,
    'role': 'ADMIN',
    'business': child_business_id,
}
assigned_user = AdAccount(account_id).create_assigned_user(
    fields=fields,
    params=params,
)

# [CLEAN UP] Delete the Child Business Manager we just created.
# One Client can only have one Child BM under your Parent Business Manager.
# This step uses the Partner's access token.
FacebookAdsApi.init(<ACCESS_TOKEN>=<PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>)
fields = [
]
params = {
    'client_id': child_business_id,
}
Business(<PARTNER_BM_ID>).delete_owned_businesses(
    fields=fields,
    params=params,
)
// Step 1. Use an Advertiser’s access token to generate a Child Business Manager.
// This can be fetched by integrating the Facebook Login button on
// your webpage and fetching the Advertiser’s access token after
// the login. The Advertiser does not have access to the BM by default.
// The Partner has root access to Child BM.
Business childBusiness = new Business(<PARTNER_BM_ID>, context).createOwnedBusiness()
  .setName("Advertisers child BM")
  .setVertical(Business.EnumVertical.VALUE_OTHER)
  .setPagePermittedRoles(Arrays.asList(Business.EnumPagePermittedRoles.VALUE_ADVERTISER))
  .setTimezoneId(1L)
  .execute();
String child_business_id = childBusiness.getId();
// Step 2. Share a Line of Credit from a Partner’s Parent BM to Child
// BM (Advertiser’s BM). This uses the Partner’s System User
// access token.
context = new APIContext(<PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>).enableDebug(false);
ExtendedCreditAllocationConfig extendedCredit = new ExtendedCredit(<EXTENDED_CREDIT_LINE_ID>, context).createOwningCreditAllocationConfig()
  .setReceivingBusinessId(child_business_id)
  .setAmount("10")
  .execute();
// Step 3. Create an access token of the System User under the Child BM.
// This uses the Partner’s access token.
context = new APIContext(<PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>).enableDebug(false);
APINode rawChildBusinessToken = new Business(child_business_id, context).createAccessToken()
  .setAppId(<APP_ID_FOR_ONBOARDING>)
  .setScope("manage_pages,ads_management,business_management")
  .execute();
String childBusinessToken = "";
childBusinessToken = rawChildBusinessToken.getRawResponseAsJsonObject().get("access_token").getAsString();
// Step 4. Fetch the funding source shared with the [Child or Parent] BM. This funding source is used to
// create the Ad account below.
// This uses the Child BM’s access token.
context = new APIContext(childBusinessToken).enableDebug(false);
APINodeList<ExtendedCredit> responses = new Business(child_business_id, context).getExtendedCredits()
  .requestIdField()
  .requestAllocatedAmountField()
  .execute();
String response_id = responses.get(0).getId();
// Step 5. Create an Ad Account under the new Child BM.
// This uses the Child BM’s System User access token.
// The System User for their Child BM is the owner of the Ad Account.
AdAccount account = new Business(child_business_id, context).createAdAccount()
  .setName("Advertisers Ad Account")
  .setCurrency("USD")
  .setTimezoneId(1L)
  .setEndAdvertiser(<PAGE_ID>)
  .setMediaAgency("NONE")
  .setPartner("NONE")
  .setFundingId(response_id)
  .execute();
String account_id = account.getId();
// Step 6. Fetch the System User for the Client business. This uses the Child
// BM’s access token. This System User ID is used in the Api calls below.
context = new APIContext(childBusinessToken).enableDebug(false);
APINodeList<SystemUser> systemUsers = new Business(child_business_id, context).getSystemUsers()
  .execute();
String system_user_id = systemUsers.get(0).getId();
// Step 7. Add a System User as an Admin to the Ad Account.
// This uses the Child BM’s access token.
context = new APIContext(childBusinessToken).enableDebug(false);
AdAccount assignedUser = new AdAccount(account_id, context).createAssignedUser()
  .setUser(system_user_id)
  .setRole(AdAccount.EnumRole.VALUE_ADMIN)
  .setParam("business", child_business_id)
  .execute();
// [CLEAN UP] Delete the Child Business Manager we just created.
// One Client can only have one Child BM under your Parent Business Manager.
// This step uses the Partner's access token.
context = new APIContext(<PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>).enableDebug(false);
new Business(<PARTNER_BM_ID>, context).deleteOwnedBusinesses()
  .setClientId(child_business_id)
  .execute();
# Step 1. Use an Advertiser’s access token to generate a Child Business Manager.
# This can be fetched by integrating the Facebook Login button on
# your webpage and fetching the Advertiser’s access token after
# the login. The Advertiser does not have access to the BM by default.
# The Partner has root access to Child BM.
business = FacebookAds::Business.get(<PARTNER_BM_ID>)
child_business = business.owned_businesses.create({
name: 'Advertisers child BM',
vertical: 'OTHER',
page_permitted_roles: ['ADVERTISER'],
timezone_id: '1',
})
child_business_id = child_business.id
print 'child_business_id:', child_business_id
# Step 2. Share a Line of Credit from a Partner’s Parent BM to Child
# BM (Advertiser’s BM). This uses the Partner’s System User
# access token.
FacebookAds::Session.default_session.access_token = <PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>
extended_credit = FacebookAds::ExtendedCredit.get(<EXTENDED_CREDIT_LINE_ID>)
extended_credit = extended_credit.owning_credit_allocation_configs.create({
receiving_business_id: child_business_id,
amount: '10',
})
# Step 3. Create an access token of the System User under the Child BM.
# This uses the Partner’s access token.
FacebookAds::Session.default_session.access_token = <PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>
business_1 = FacebookAds::Business.get(child_business_id)
raw_child_business_token = business_1.access_token.create({
app_id: <APP_ID_FOR_ONBOARDING>,
scope: 'manage_pages,ads_management,business_management',
})
child_business_token = raw_child_business_token.access_token;
# Step 4. Fetch the funding source shared with the [Child or Parent] BM. This funding source is used to
# create the Ad account below.
# This uses the Child BM’s access token.
FacebookAds::Session.default_session.access_token = child_business_token
responses = business_1.extendedcredits({
})
response_id = responses[0].id
print 'response_id:', response_id
# Step 5. Create an Ad Account under the new Child BM.
# This uses the Child BM’s System User access token.
# The System User for their Child BM is the owner of the Ad Account.
account = business_1.adaccount.create({
name: 'Advertisers Ad Account',
currency: 'USD',
timezone_id: '1',
end_advertiser: <PAGE_ID>,
media_agency: 'NONE',
partner: 'NONE',
funding_id: response_id,
})
account_id = account.id
print 'account_id:', account_id
# Step 6. Fetch the System User for the Client business. This uses the Child
# BM’s access token. This System User ID is used in the Api calls below.
FacebookAds::Session.default_session.access_token = child_business_token
system_users = business_1.system_users({
})
system_user_id = system_users[0].id
print 'system_user_id:', system_user_id
# Step 7. Add a System User as an Admin to the Ad Account.
# This uses the Child BM’s access token.
FacebookAds::Session.default_session.access_token = child_business_token
ad_account = FacebookAds::AdAccount.get(account_id)
assigned_user = ad_account.assigned_users.create({
user: system_user_id,
role: 'ADMIN',
business: child_business_id,
})
# [CLEAN UP] Delete the Child Business Manager we just created.
# One Client can only have one Child BM under your Parent Business Manager.
# This step uses the Partner's access token.
FacebookAds::Session.default_session.access_token = <PARTNER_ACCESS_TOKEN_FOR_SMB_ONBOARDING>
business.owned_businesses.destroy({
client_id: child_business_id,
})
// Step 1. Use an Advertiser’s access token to generate a Child Business Manager.
// This can be fetched by integrating the Facebook Login button on
// your webpage and fetching the Advertiser’s access token after
// the login. The Advertiser does not have access to the BM by default.
// The Partner has root access to Child BM.
fields = [
];
params = {
  'name' : 'Advertisers child BM',
  'vertical' : 'OTHER',
  'page_permitted_roles' : ['ADVERTISER'],
  'timezone_id' : '1',
};
let child_business = await (new Business(<PARTNER_BM_ID>)).createOwnedBusiness(
  fields,
  params
);
let child_business_id = child_business.id;

// Step 2. Share a Line of Credit from a Partner’s Parent BM to Child
// BM (Advertiser’s BM). This uses the Partner’s System User
// access token.
bizSdk.FacebookAdsApi.init(partner_<ACCESS_TOKEN>_for_smb_onboarding);
fields = [
];
params = {
  'receiving_business_id' : child_business_id,
  'amount' : '10',
};
let extended_credit = await (new ExtendedCredit(<EXTENDED_CREDIT_LINE_ID>)).createOwningCreditAllocationConfig(
  fields,
  params
);


// Step 3. Create an access token of the System User under the Child BM.
// This uses the Partner’s access token.
bizSdk.FacebookAdsApi.init(partner_<ACCESS_TOKEN>_for_smb_onboarding);
fields = [
];
params = {
  'app_id' : <APP_ID_FOR_ONBOARDING>,
  'scope' : 'manage_pages,ads_management,business_management',
};
let raw_child_business_token = await (new Business(child_business_id)).createAccessToken(
  fields,
  params
);

let child_business_token = raw_child_business_token.<ACCESS_TOKEN>;


// Step 4. Fetch the funding source shared with the [Child or Parent] BM. This funding source is used to
// create the Ad account below.
// This uses the Child BM’s access token.
bizSdk.FacebookAdsApi.init(child_business_token);
fields = [
  'id',
  'allocated_amount',
];
params = {
};
let responses = await (new Business(child_business_id)).getExtendedCredits(
  fields,
  params
);
let response_id = responses[0].id;

// Step 5. Create an Ad Account under the new Child BM.
// This uses the Child BM’s System User access token.
// The System User for their Child BM is the owner of the Ad Account.
fields = [
];
params = {
  'name' : 'Advertisers Ad Account',
  'currency' : 'USD',
  'timezone_id' : '1',
  'end_advertiser' : <PAGE_ID>,
  'media_agency' : 'NONE',
  'partner' : 'NONE',
  'funding_id' : response_id,
};
let account = await (new Business(child_business_id)).createAdAccount(
  fields,
  params
);
let account_id = account.id;

// Step 6. Fetch the System User for the Client business. This uses the Child
// BM’s access token. This System User ID is used in the Api calls below.
bizSdk.FacebookAdsApi.init(child_business_token);
fields = [
];
params = {
};
let system_users = await (new Business(child_business_id)).getSystemUsers(
  fields,
  params
);
let system_user_id = system_users[0].id;

// Step 7. Add a System User as an Admin to the Ad Account.
// This uses the Child BM’s access token.
bizSdk.FacebookAdsApi.init(child_business_token);
fields = [
];
params = {
  'user' : system_user_id,
  'role' : 'ADMIN',
  'business' : child_business_id,
};
let assigned_user = await (new AdAccount(account_id)).createAssignedUser(
  fields,
  params
);


// [CLEAN UP] Delete the Child Business Manager we just created.
// One Client can only have one Child BM under your Parent Business Manager.
// This step uses the Partner's access token.
bizSdk.FacebookAdsApi.init(partner_<ACCESS_TOKEN>_for_smb_onboarding);
fields = [
];
params = {
  'client_id' : child_business_id,
};
await (new Business(<PARTNER_BM_ID>)).deleteOwnedBusinesses(
  params
);

Options & Limitations

  • There can only be one Child BM per User for a given Partner.
  • If you want to delete a Child BM then you will need to pause all ads under the Ad Account under the Child BM and call the delete API.
  • If you don't want to check your email to accept the invitation to join the Child BM you can query for it via the API and just go to it. Just parse the invite_link field from the response below. In a browser, go to the url returned in this API call. You will be asked to log in using your Facebook account after which you will get access to the Child BM.

Solutions to Onboarding Clients at Scale is in beta. Apply Now to request access to this tool.

Apply Now