Onboard a Seller

This page has guidance on how to onboard a seller into managed partner ads (MPA) using the Seller Business Creation API.

Once you verify a seller is eligible for MPA using the Seller Eligibility API, you will use the Seller Business Creation API to onboard the seller.

Calling the Seller Business Creation API using an eligible seller’s vendor_id automatically performs the following actions:

Creates a child Business Manager, a Facebook Page, and an ad account for the seller
Shares a line of credit
Sets up the seller’s catalog segment with vendor_id=<child_business_external_id> as the filter

Once you onboard a seller into MPA, they are considered a managed partner.

Before You Begin

Before you onboard a seller, make sure you have completed these steps:

Required Permissions

To call the Seller Business Creation API, you will need the following permissions:

Business Admin
Catalog Admin
Manage Credit
App Developer

Seller Business Creation API Call

Request

curl \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'asyncbatch=[ 
      { 
        "method": "POST", 
        "relative_url": "<MARKETPLACE_BM_ID>/managed_partner_businesses", 
        "name": "<ASYNC_SESSION_NAME>", 
        "body": "child_business_external_id=<VENDOR_ID>&line_of_credit_id=<LINE_OF_CREDIT_ID>&credit_limit=<CREDIT_LIMIT>&partition_type=<PARTITION_TYPE>&catalog_id=<PARENT_CATALOG_ID>&ad_account_currency=<AD_ACCOUNT_CURRENCY>&seller_targeting_countries=['COUNTRY_CODE1','COUNTRY_CODE2']&timezone_id=<TIMEZONE_ID>&name=<BUSINESS_MANAGER_NAME>&seller_external_website_url=<SELLER_EXTERNAL_WEBSITE_URL>&partner_facebook_page_url=<PARTNER_FACEBOOK_PAGE_&page_profile_image_url=<PROFILE_PIC_URL>&vertical=<VERTICAL>&partner_registration_countries=<PARTNER_REGISTRATION_COUNTRY>"
      } 
  ]' \
  "https://graph.facebook.com/v21.0"

The response to the API call is returned immediately with an ASYNC_SESSION_ID. While the request continues to be processed, the ASYNC_SESSION_ID should be polled until a terminal state [COMPLETED|FAILED] is reached.

Parameters

Name	Description
`ad_account_currency` string	Required. The currency of the ad account to be created for the seller. The string input should be currency abbreviation. See Accepted currencies for monthly invoicing.
`catalog_id` numeric string	Required. The ID of the marketplace's catalog, referred to as a parent catalog. During onboarding, this catalog may be filtered using `vendor_id=<child_business_external_id>` to create a catalog segment for a seller.
`child_business_external_id` string	Required. Each marketplace should pass a unique ID for each seller. The name of the field on the marketplace side is `vendor_id`. This field is used to create the catalog segment with filter `vendor_id = <child_business_external_id>`.
`credit_limit` numeric string	Required. The maximum amount of credit to be shared with a seller from the main line_of_credit_id. You should only set it if the `partition_type` value is set to `FIXED` Condition: Available credit in `line_of_credit_id` >= requested `credit_limit`.
`partition_type` enum string	Required. Set to one of the following values: `FIXED` `AUTH` Default value: `FIXED` Fixed partition or unrestricted credit partition. The value set for `credit_limit` param is ignored if `partition_type` value is set to `AUTH`
`line_of_credit_id` numeric string	Required. The ID of the main line of credit from which you may share credit with a seller. Conditions: Pass params `credit_limit` and `ad_account_currency`. Cannot pass `no_ad_account`
`marketplace_bm_id` string	Required. The marketplace's Business Manager ID. See Find your Business ID in Meta Business Manager for more information.
`name` string	Required. The unique Business Manager name created for the seller.
`skip_partner_page_creation` bool	Optional. Set to `true` to skip page creation for the seller. Default value: `false`
`page_name` string	Optional. The name to assign to the page created for the seller. Skip setting this parameter when `skip_partner_page_creation` is set to `true`. Condition: Page name must meet Facebook's page name requirements. Default value: Partner's Facebook page name configured during Managed Partner Ads API onboarding in the Collaboration Center.
`page_profile_image_url` string	Optional The URL from which to fetch the image for the seller’s page profile picture. Skip setting this parameter when `skip_partner_page_creation` is set to `true`. Conditions: Image dimension >= 180 * 180 pixel Image size < 1MB Default value: Partner's Facebook page profile picture configured during Managed Partner Ads API onboarding in the Collaboration Center.
`seller_external_website_url` string	Required. The seller’s website URL.
`seller_targeting_countries` list<string>	Required. The array of strings containing seller's targeting countries. The value is the country code instead of the country name. During ad creation, this is used as the default targeting country in the ad sets. Refer to Country Codes.
`partner_facebook_page_url` string	Optional. The seller's Facebook Page URL.
`partner_registration_countries` string	Required. The seller's business registration country. The value is the country code instead of the country name. Refer to Country Codes.
`timezone_id` numeric string	Required. Timezone ID of the business/ad account. Refer to Timezone IDs.
`vertical` enum string	Required. Set to one of the following values: `ADVERTISING` `AUTOMOTIVE` `CONSUMER_PACKAGED_GOODS` `ECOMMERCE` `EDUCATION` `ENERGY_AND_UTILITIES` `ENTERTAINMENT_AND_MEDIA` `FINANCIAL_SERVICES` `GAMING` `GOVERNMENT_AND_POLITICS` `MARKETING` `ORGANIZATIONS_AND_ASSOCIATIONS` `PROFESSIONAL_SERVICES` `RETAIL` `TECHNOLOGY` `TELECOM` `TRAVEL` `OTHER`

Response

{
  "async_sessions": [
    {
      "id": "<ASYNC_SESSION_ID>",
      "name": "<ASYNC_SESSION_NAME>"
    }
  ]
}

Use the ASYNC_SESSION_ID to get the corresponding ID of a seller onboarded to managed partner ads.

See How to Poll Async Session for Response for more information.

Success Response

If the status is COMPLETED, the resulting data of polling async session will look like:

{
  "result": "{\"id\":\"<NEWLY_CREATED_MANAGED_PARTNER_BM_ID>\"}",
  "status": "COMPLETED",
  "id": "<ASYNC_SESSION_ID>"
}

Failed Response

If the status is FAILED, the resulting data of polling async session will look like:

Error Codes

Requests made to seller onboarding API can result in several different error responses. See How to handle an error for more information.

Error Code	Error Subcode	Error Message
1800000	2310114	Complete the managed partner ads onboarding process in Collaboration Center
1800001	2310118	The vendor ID {vendor_id} is already in use. Enter a unique vendor ID that is not used anywhere else.
1800002	2310138	The business name {invalid_business_name} is not a valid name. Consider using {suggested_business_name} instead. Business names must meet Facebook's business name requirements.
1800002	2310139	The business name {invalid_business_name} is not a valid name. Business names must meet Facebook's business name requirements.
1800003	2310133	Enter a valid registration country code for this partner's business
1800004	2310127	Remove or update the following invalid country codes listed for the partner's registration countries: [{invalid_registration_country_codes}]
1800006	2310141	Remove or update the following invalid country codes you entered: [{invalid_targeting_country_codes}]
1800100	2310117	The catalog ID you entered {catalog_id} cannot be used to create a catalog segment. You can go to the Commerce Manager to find the correct catalog ID number that contains this partner's items. Retry onboarding the partner with the correct catalog ID.
1800101	2310116	Your business {business_id} does not manage the catalog ID you entered {catalog_id}. Enter a catalog ID that your business manages.
1800102	2310115	Check the catalog ID you entered {catalog_id}. If it's the correct ID and you need access to this catalog, ask someone with full control to go to Business settings in Business Manager to give you access. Once assigned, retry onboarding the partner.
1800200	2310119	Enter a line of credit ID you will use to share credit with partners
1800201	2310144	The line of credit ID you entered {line_of_credit_id} is not an invoicing account or credit line ID. Enter the line of credit ID associated with Business ID {marketplace_business_id}. This should be the line of credit your business uses to share credit with partners.
1800202	2310122	Check the line of credit ID you entered {line_of_credit_id}. If it's the correct ID and you need access, ask someone with full control to go to Business settings in Business Manger to give you access to manage finance. Retry onboarding the partner once you have access to manage finance.
1800203	2310123	Your business {business_id} does not manage the line of credit entered {line_of_credit_id}. Provide an invoicing account or line of credit ID managed by your business.
1800204	2310120	Enter the currency for the ad account. This cannot be changed later.
1800205	2310145	The line of credit ID {line_of_credit_id} does not support the currency entered {ad_account_currency}. Update the partner's ad account currency to one the credit line supports.
1800206	2310121	Enter a credit limit amount greater than 0
1800207	2310143	The credit limit you entered ${credit_limit} is more than the available credit balance of ${available_credit}. Either decrease the assigned credit limit or use a different line of credit ID with a higher balance.
1800305	2310149	Enter an image URL for the partner's profile picture. The image should be 180 x 180 pixels or larger and less than 1 MB.
1800306	2310150	Images should be 180 x 180 pixels or larger and less than 1 MB. Check the image size and the URL {page_profile_image_url} and try again or enter a new image URL.
1800306	2310151	Check the link {page_profile_image_url} or enter a new one
1800307	2310148	The system timed out trying to process the image URL {page_profile_image_url}. Check the image URL, retry the request or enter a new image URL.
1800311	2310181	The page name {invalid_page_name} is not a valid name. Consider using {suggested_page_name} instead. Page names must meet Facebook's page name requirements.
1800311	2310182	The page name {invalid_page_name} is not a valid name. Page names must meet Facebook's page name requirements.