Create and Run Ad Campaigns

This page provides steps to create ad campaigns for the managed partners (sellers) you onboarded to managed partner ads.

Before You Begin

Before you create and run ad campaigns for your partners, make sure you have completed these steps:

Required Permissions

To call the Seller Ad Creation API, the user will need the following permissions:

Seller Business Admin

Targeting DSA Regulated Locations (European Union)

For ad campaigns targeting the European Union (EU) and/or associated territories, the dsa_payor and dsa_beneficiary fields are required. The information provided in these 2 fields will be shown to end users to indicate who is paying for the ad and who is the beneficiary of the ad.

The beneficiary and payer information will be required for all campaigns targeting the EU and associated territories. If the fields are not provided, the advertisers will not be able to create MPA campaigns and the API will return a failed response with error codes listed below.

Seller Ad Creation API Call

Request

curl \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'asyncbatch=[ 
       { 
         "method": "POST", 
         "relative_url": "act_<ACCOUNT_ID>/managed_partner_ads", 
         "name": "create1", 
         "body": "lifetime_budget=10000&start_time=1598286074&end_time=1598286074&override_targeting_countries=['US','UK']&use_marketplace_template=true&product_set_id=<PRODUCT_SET_ID>" 
       }, 
     ]' \
  "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
`conversion_domain` string	Required. Sets the conversion domain in ads creation flow. The `conversion_domain` field should match with a Meta Pixel configuration. This field should contain only the first and second level domains, and not the full URL. For example, facebook.com.
`custom_event_type` enum	Optional. An app event to optimize for in both prospecting and retargeting ads. Values: `CONTENT_VIEW`, `ADD_TO_CART`, `PURCHASE` Condition: You can only specify this field when `use_marketplace_template` is `true` and `use_seller_template` is `false`.
`dsa_payor` string (max 512 char)	Optional. The payor of the campaign. Note: This field is Required for campaigns targeting EU and/or associated territories.
`dsa_beneficiary` string (max 512 char)	Optional. The beneficiary of the campaign. Note: This field is Required for campaigns targeting EU and/or associated territories.
`end_time` datetime	Required. The end time for the ad campaign, in UTC UNIX timestamp.
`lifetime_budget` numeric string	Required. The campaign's budget in the ad account's currency. In the ads world, offset can come with either 1 or 100 (for the currencies with the concept of cents). For example, `lifetime_budget = 1` in USD (offset 100) means 1/100 (offset) = $0.01 (1 cent). `lifetime_budget = 1` in JPY (offset 1) means 1/1 (offset) = ¥1 (1 Yen).
`override_creative_text` string	Required. The body of the creative.
`override_targeting_countries` list<strings>	Optional. The country targeting in the campaign. This overrides the countries set during seller business creation for both prospecting and retargeting ads.
`product_set_id` numeric string	Optional. The ID of a product set within the seller's product catalog that this campaign will promote across all its ads.
`start_time` datetime	Required. The start time for the ad campaign, in UTC UNIX timestamp.
`use_marketplace_template` bool	Optional. Specify this field to create a campaign using a default template globally available to all sellers. Condition: `use_marketplace_template` or `use_seller_template` must be used, but not both.
`use_seller_template` bool	Optional. Specify this field to create a campaign using a custom template applied to the seller. Condition: `use_marketplace_template` or `use_seller_template` must be used, but not both.

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_CAMPAIGN_ID>\"}",
  "status": "COMPLETED",
  "id": "<ASYNC_SESSION_ID>"
}

Failure Response

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

Error Codes

Error Code	Error Subcode	Description
1800011	2310154	Ads creative post was created by an app that is in development mode. It must be in public to create this ad.
1800103	2310155	The Business Manager {seller_business_id} is missing a shared catalog segment. This may be due to partial onboarding. You can use Collaboration Center to share assets and add a catalog segment, or you can use the Seller Deletion API to delete the seller and re-onboard them with the asynchronous Seller Onboarding API. You can also contact your Meta partner for help.
1800104	2310156	The ID you entered {product_set_id} is not a product set ID. Enter a product set ID associated with catalog ID {catalog_id}.
1800105	2310157	The ID you entered {product_set_id} is not a product set ID for the business' catalog segment. Enter a product set ID associated with catalog ID {catalog_id}.
1800208	2310152	The ad account for this business is disabled for violating our Advertising Polices or other standards. To learn more, go to Partnerships in Collaboration Center, select Managed Partners and the Quality issues tab. You can also contact your Meta partner for help or to appeal.
1800209	2310153	The ad account entered {account_id} was not created with managed partner ads. Enter the account ID created for this business when it onboarded into managed partner ads.
1800308	2310137	The Business Manager {seller_business_id} for this business is missing a seller Page. This may be due to partial onboarding. You can use the Seller Deletion API to delete the seller and re-onboard them with the asynchronous Seller Onboarding API. You can also contact your Meta partner for help.
1800309	2310159	The seller Page for this business is disabled for possibly violating our Advertising Polices or other standards and can't be used to run ads. To learn more, go to Partnerships in Collaboration Center, select Managed Partners and the Quality issues tab. You can also contact your Meta partner for help or to appeal.
1800400	2310161	The campaign budget entered is too small. According to the template used, the budget must be at least {minimum_budget}.
1800402	2310160	The prospecting and retargeting budgets entered do not equal 100%. Enter a budget percentage for prospecting campaigns and a budget percentage for retargeting campaigns that add up to 100%. Additionally, ensure there is both a prospecting and targeting campaign identified in the template.
1800500	2310166	You're attempting to use a managed partner ads (MPA) API to update campaigns that are not MPA campaigns. Check the campaign you entered ({campaign_id}), or use a different API.
1800501	2310168	The campaign ID entered ({campaign_id}) does not belong to the ad account. Check the ID and try again.
1800700	2310172	Enter the person or organization paying for this ad set.
1800701	2310171	Enter the person or organization benefiting from this ad set.