Managed Partner Ads: API Reference

Other managed partner ads APIs include:

• Seller Management APIs
• Partner Ads Management APIs
• Async API User Guide

Lookup Seller Business API

Use this API to lookup the Business ID for a given seller or vendor_id.

Access Token Type

To call this API, use the access token created by an admin system user that belongs to the parent Business Manager (the marketplace's Business Manager).

Sample GET Request

curl -X GET \
  -F "child_business_external_id=<VENDOR_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/owned_businesses?access_token=<ACCESS_TOKEN>"

Sample Response

{
    "child_business_id": 3213232
}

Access Seller Business Metadata API

Use this API to retrieve seller metadata of a Managed Partner Ads seller child business. The metadata from the API response includes:

• Managed Partner Ads assets: page, ad account, payment method
• Seller’s custom template info
• Seller business info: name

Access Token Type

To call this API, use the access token created by an admin system user that belongs to the parent Business Manager (the marketplace's Business Manager).

Business ID Type

Use the child Business Manager ID for the API call.

Sample GET Request

curl -X GET \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/?fields=collaborative_ads_managed_partner_business_info&access_token=<ACCESS_TOKEN>"

Sample Response

{
  "collaborative_ads_managed_partner_business_info": {
    "seller_business_status": "ready",
    "seller_business_info": {
      "seller_external_website_url": "https://www.website.com",
      "partner_facebook_page": {
        "id":"9999999"
      }
    },
    "ad_account": {
      "id": "act_11111111",
      "currency": "USD"
    },
    "page": {
      "id": "3333333"
    },
    "catalog_segment": {
      "id": "2222222"
    },
    "extended_credit": {
      "receiving_credit_allocation_config": {
        "partition_type": "FIXED",
        "id":"66666666"
      },
      "max_balance": {
        "amount":"5,000.00",
        "amount_in_hundredths":"500000",
        "currency":"USD",
        "offsetted_amount":"500000"
      },
      "id":"888888888"
    },
    "active_seller_campaign": {
      "status": "ACTIVE",
      "id": "1111111"
    },
    "template": [
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "4444444",
        "adgroup_template_ids": [
          "5555555"
        ],
        "targeting_type": "retargeting"      
      },
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "6666666",
        "adgroup_template_ids": [
          "7777777"
        ],
        "targeting_type": "prospecting"
      } 
    ]
  },
  "id": "<child_business_manager_id>"
}
    

Get the Child System User Token

For an onboarded child Business Manager, use this API call to share application and get its access token. This token can be used for all subsequent calls to create or manage ads.

Sample POST Request

curl \
  -F 'id=<CHILD_BUSINESS_MANAGER>' \
  -F 'app_id=<App_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<Parent BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  "https://graph.facebook.com/<API_VERSION>/<CHILD_BUSINESS_MANAGER_ID>/access_token"

Sample Response

{ 
  "access_token": "<CHILD_BM_ACCESS_TOKEN>"
}

Update Seller Business Configuration API

Use this API to update a seller business information. You can update a seller's business information, like external website URL or email address, and/or their Managed Partner Ads assets, like active ad account or an ad creation custom campaign template. See Available Parameters for more information.

To create and get a Seller's Business, see Seller Business Creation API. To find the Business ID of existing seller, see Lookup Seller Business API.

Access Token Type

To call this API, use the access token that belongs to each individual child Business Manager (the seller's Business Manager).

Available Parameters

Sample POST Request

curl \
  -F "seller_external_website_url='http://shop.com'" \
  -F "ad_account=<SELLER_ACTIVE_AD_ACCOUNT_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Child_Business_id>/managed_partner_business_setup?access_token=<ACCESS_TOKEN>"

Sample Response

{
    "id": 3213232, // id of child business
    "meta_data": {
        "seller_business_info": {
            "seller_email_address": "goodseller@fb.com"
            "seller_external_website_url": "www.website.com"
        },
        "ad_account": {
            "id": "434343",
            "spend_limit": "500",
        },
        "page": {
            "id": "123412341",
        },
        "template": [
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "4444444",
            "adgroup_template_ids": [
              "5555555"
            ],
            "targeting_type": "retargeting"      
          },
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "6666666",
            "adgroup_template_ids": [
              "7777777"
            ],
            "targeting_type": "prospecting"
          } 
        ]     
    }
}

Error Codes

Using Templates

A template is an asset configured and used by the marketplace in the Managed Partner Ads service. Templates contain details and settings, or “components”, that drive the seller campaigns run by the marketplace on the seller’s behalf.

Template's components include ad sets and ads, which include information like targeting, ad creative, formats, and more. There are four components required for each campaign template:

• Ad set component for prospecting
• Ad component
• Ad set component for retargeting
• Ad component

Types of Template

There are two types of templates, default and custom:

Requirements for Custom Templates

Before creating a custom template, the marketplace must create a Producer Business Manager first —this ensures that campaigns used to create templates conform to Collaborative Ads customizations and requirements for seller campaigns. As a producer, the Business Manager can be used to create source ads for template creation.

Retargeting ad set, prospecting ad set and ad components must be available to add and/or configure a custom campaign template for a seller.

The campaigns used for template creation must be associated with a Collaborative Ads ad account, and have the following settings:

• Campaign objective must be Catalog Sales.
• In Ads Manager, budget Optimization must be toggled on at the campaign level, with ‘Lowest Cost’ bid strategy.
• Ad format must be carousel with no static overlays, images or videos.

Custom Template Flow

Step 1: Create a Custom Campaign Template

1. Go to the Assets tab in Collaboration Center. Inside that tab, the Template Inventory section displays a collection of templates and template components that can be used for seller campaigns.
2. Click on Create Template to open up a stepper card.
3. Search for an existing valid source campaign by providing either the ad set or ad ID.
4. To create your template component, select either ad set and/or ad extracted from source ID. You need to create all four components (2 ads and 2 ad sets) for a custom template.
5. Save the template by providing name and description.

The seller-specific details such as Catalog Segment, Product Set, Facebook page and destination URL are dropped from the source campaign during template creation. The final campaign created using the template has seller specific information for these fields with a lifetime campaign budget and lowest cost bid strategy.

Step 2: Apply the Custom Template to a Seller

The custom templates could be used as below:

• Use at the time of seller onboarding to assign specific templates for new seller campaigns.
• Change the template for a seller to kickstart a holiday or other special campaign.

If you want to change the campaign template for sellers, be sure to have the template components you want to use for replacing those in the existing campaign template—you can replace 1 or all. If you are creating a new template for sellers that have no custom template, you need to have all four components (2 ads and 2 ad sets) ready to use.

A template can be applied to sellers using one of the following ways:

Single Seller Template Application UI Flow

1. Go to the Sellers tab in Collaboration Center and select a seller that you wish to apply the custom template.
2. Open the Shared Assets tab for that seller. At first, sellers do not have a custom campaign template configured.
3. Click on Add Custom. A modal pops up where you can select template components created during template creation step to apply for the selected seller.
4. You can specify the maximum spend limits for the prospecting ad set and the retargeting ad set, which are expressed as a percentage of your total campaign budget. The budget will continuously distribute in real time across the two ad sets based on performance. This means that the percentage of the budget spent on each ad set at the end of the campaign may be less than the maximum spend you set. By default, the maximum spend limit is split equally between the two ad sets, but you can change it.
5. Click on Save and the selected template components will be applied to the seller.

Bulk Template application UI flow

This feature aims to provide scalability by enabling marketplaces to apply template components to multiple sellers at the same time.

1. Go to the Sellers tab in Collaboration Center and select a set of sellers that you wish to apply templates to using the checkbox column.
2. Click on Apply Templates to proceed with template application flow.
3. A modal will be displayed based on the seller selection

• If the selected sellers have no existing custom templates, select the four template components, and specify the spend limit percentage for Prospecting and Retargeting. By default, the spend limit is split equally between the two ad sets.
• If the selected sellers have had custom templates previously applied, select all, one, or some of the template components to replace for selected sellers. The spend limit percentage for Ad Sets can be overridden for sellers by switching on the toggle.
• If the selected sellers are a mix of sellers with and without custom templates, a modal is displayed to select either ‘Sellers with no custom templates’ or ‘Sellers with custom template’ for the next step. Based on the selection, a modal from the two previous options is displayed.

Finalize by clicking on Save. The selected template components will be applied to selected sellers.

Update Seller Business Configuration API

Use the Update Seller Business Configuration API to apply a custom template to a seller with the following input parameter: template.

"template":[
  {
    "budget_percentage":0.5,
    "campaign_template_id":"160235235998069",
    "adgroup_template_ids":[
      "447963739637509"
    ],
    "targeting_type":"retargeting"
  },
  {
    "budget_percentage":0.5,
    "campaign_template_id":"278452090413983",
    "adgroup_template_ids":[
      "458654975391261"
    ],
    "targeting_type":"prospecting"
  }
]

Step 3: Create Your Campaign

Use the main campaign creation instructions to create and run seller’s ads with the specified parameters and previously applied custom template. To use the custom campaign template applied to that seller, set use_seller_template to true.