Product Ads
A Bing Shopping campaign enables you to advertise the products from your Bing Merchant Center store product catalog. Product ads from a Bing Shopping campaign include details about the product, an image, and optional promotional text.

You can manage Bing Shopping settings with either the Bulk Service or Campaign Management Service. You should use the Bulk Service if you need to upload or download a high volume of entity settings. For example you can update all ad groups for your entire account in a single upload. In comparison, with the Campaign Management Service you can only update 100 ad groups per call and those ad groups must be in the same campaign.
To create a Bing Shopping campaign, follow these steps.
Set up the customer’s Bing Merchant Center store. In the Bing Ads web application, click Tools > Bing Merchant Center. Click on Create store and provide the requested store details. For information about setting up your store catalog, see Create a Bing Merchant Center store and How is the feed file organized.
Create a product catalog, and then submit the catalog feed via FTP or the Bing Ads Content API.
Get your Bing Merchant Center store unique system identifier. Call GetBMCStoresByCustomerId and get the StoreId from of one of the returned BMCStore objects, or in the Bing Ads web application, click Tools > Bing Merchant Center to access your store details.
After you complete these steps, you can follow the steps to Create a Bing Shopping Campaign with the Campaign Management Service.
The Bulk Service create, update, and delete operations can be completed using Bulk upload. You can use Bulk download to read back your data. For more information see Bulk File Schema and Bulk Download and Upload.
These are the Bing Shopping entities that can be accessed using the Bulk Service.
For code examples that show how to apply product conditions for Bing Shopping campaigns using the Bulk service, see C# | Java | Python.
To create a Bing Shopping campaign, follow these steps.
Create one or more Bing Shopping campaigns.
Tip You must create designated campaigns for Bing Shopping. You may not create text ads in your Bing Shopping campaigns.
Optionally, you can upload a Campaign Product Scope criterion that will be associated with your Bing Shopping campaign. Use the product scope criterion to include a subset of your product catalog, for example a specific brand, category, or product type. A campaign can only be associated with one Campaign Product Scope, which contains a list of up to 7 product conditions. You'll also be able to specify more specific product conditions for each ad group.
Note Product conditions may be returned by Bing Ads services in a different order from the order that you submitted.
Upload an Ad Group and set its Parent Id field to the Id of the campaign added above.
Upload one or more Ad Group Product Partition records which represent product partition nodes in a tree structure that will be used to further refine the product catalog offers. Duplicate or conflicting product conditions attempted within an ad group's product partition group will be rejected by the upload operation; however, the operation will not validate whether duplicate or conflicting conditions already exist within the campaign level Campaign Product Scope. For example given one ad group and one campaign, the Campaign Product Scope and Ad Group Product Partition may each have Product Condition 1 set to CategoryL1 and Product Value 1 set to Animals & Pet Supplies, and the service will not throw any error or warning for a duplicate condition.
Note There is a 1 to 1 relationship between ad groups and product groups. In other words, each ad group has one product group and vice versa. In the Bing Ads web application, for each ad group you would add one product group with multiple levels of division or multiple partitions. This is the equivalent of adding ad group level product partitions using the Bing Ads API.
Please also consider the following validation rules for uploading Ad Group Product Partition records.
At minimum you must specify at least the root node for the product partition group tree structure. The product partition group's root node must have its Product Condition 1 field set to "All" and Product Value 1 null or empty. If you are bidding on all products in the catalog equally, set the Sub Type field to Unit. If you are partitioning the bids based on more specific product conditions, then set the Sub Type field to Subdivision, the Parent Criterion Id to null or empty, and the Id to a negative value. You will use the negative value as Parent Criterion Id for any child nodes.
The root node is considered level 0, and a tree can have branches up to 7 levels deep.
Per upload request, you can include a maximum of 20,000 product partition tree nodes per ad group. The entire product partition tree node count for an ad group cannot exceed 20,000.
The product partition tree nodes for the same tree (same ad group) must be grouped together in the file.
The order of the product partition nodes is not guaranteed during download, and parent nodes might be provided after child nodes; however, all nodes for the same ad group will be grouped together in the file.
If you are creating or modifying the tree structure, parent product partition tree nodes must be ordered ahead of the child product partition tree nodes ; however, the order does not matter for non-structural changes such as updating the bid. For example if you want to update the bids without adding, deleting, or updating the tree structure, then you only need to upload the Id, Parent Id, and Bid fields.
To update the Product Condition 1, Product Value 1 or Is Excluded field, you must delete the existing product partition tree node and upload a new product partition tree node which will get a new identifier.
If any action fails, all remaining actions that might have otherwise succeeded will be rejected.
All product partition node addition and deletion actions must result in a complete tree structure.
Every path from the root node to the end of a branch must terminate with a leaf node (Sub Type=Unit). Every Unit must have a bid, unless the Is Excluded field is TRUE which means that the node is a negative ad group criterion.
Every subdivision must have at least one leaf node that bids on the remainder of the subdivision's conditions, i.e. use the same operand as its sibling unit(s) and set its Product Value 1 null or empty.
If you are adding partitions with multiple levels where neither the parent or child yet exist, use a negative int value as a reference to identify the parent. For example set the both the parent's Id, and the child's Parent Criterion Id field to the same negative value. The negative IDs are only valid for the duration of the call. Unique system identifiers for each successfully added ad group criterion are returned in the upload result file.
The Bid and Destination Url fields are only applicable if the Is Excluded field is FALSE which means that the node is a biddable ad group criterion. However, these fields are ignored for Subdivision partition nodes. Those elements are only relevant for Unit (leaf) partition nodes.
To pause any product partition you must pause the entire ad group by updating the Status field of the Ad Group to Paused. You can pause the entire campaign by updating the Status field of the Campaign to Paused.
For a Deleted action you only need to specify the Id and Parent Id.
If you delete a parent product partition, all of its children and descendants will also be deleted.
You may not specify duplicate product conditions in a branch. For more information, see Product Conditions.
Upload a product ad. You must add at least one Product Ad to the corresponding ad group. A Product Ad is not used directly for delivered ad copy. Instead, the delivery engine generates product ads from the product details that it finds in your Bing Merchant Center store's product catalog. The primary purpose of the Product Ad object is to provide promotional text that the delivery engine adds to the product ads that it generates. For example, if the promotional text is set to “Free shipping on $99 purchases”, the delivery engine will set the product ad’s description to “Free shipping on $99 purchases.”
After you complete these steps, the delivery engine can begin serving product ads for the products that it finds in the customer’s Bing Merchant Center store. If the user’s search query has product intent, the delivery engine searches the customer’s Bing Merchant Center store for products that matches the query. If it finds a product, and the product meets the conditions of the product filters specified in the product scope and product partitions, the delivery engine generates a product ad using the product details from the store.
These are the Bing Shopping entities that can be accessed using the Campaign Management Service. You can create, read, update, and delete these entities.
Partial success is supported for a subset of these operations. For example if you submit 10 ad groups and 2 fail, the remaining 8 will succeed. For more information, see Partial Success using the Campaign Management Service. |
| Entities | Service Operations |
|---|---|
| Campaign | AddCampaigns DeleteCampaigns GetCampaignsByAccountId GetCampaignsByIds UpdateCampaigns |
| ProductScope | AddCampaignCriterions DeleteCampaignCriterions GetCampaignCriterionsByIds UpdateCampaignCriterions |
| AdGroup | AddAdGroups DeleteAdGroups GetAdGroupsByCampaignId GetAdGroupsByIds UpdateAdGroups |
| ProductAd | AddAds GetAdsByAdGroupId DeleteAds GetAdsByEditorialStatus GetAdsByIds UpdateAds |
| BiddableAdGroupCriterion Note: Currently the only supported BiddableAdGroupCriterion is used for a Bing Shopping campaign ProductPartition. You cannot update or delete a product partition, so ApplyProductPartitionActions is used for all write operations. AddAdGroupCriterions, DeleteAdGroupCriterions, and UpdateAdGroupCriterions operations are not supported for managing Bing Shopping campaigns. | ApplyProductPartitionActions GetAdGroupCriterionsByIds |
For code examples that show how to apply product conditions for Bing Shopping campaigns using the Campaign Management service, see C# | Java | PHP | Python.
To create a Bing Shopping campaign, follow these steps.
Create one or more Bing Shopping campaigns.
Tip You must create designated campaigns for Bing Shopping. You may not create text ads in your Bing Shopping campaigns.
Set the CampaignType element of the Campaign to Shopping.
Create a ShoppingSetting instance and set its Priority (0, 1, or 2), SalesCountryCode, and StoreId elements. Add this shopping setting to the Settings list of the Campaign.
Optionally, you can create a ProductScope criterion that will be associated with your Bing Shopping campaign. Use the product scope criterion to include a subset of your product catalog, for example a specific brand, category, or product type. A campaign can only be associated with one ProductScope, which contains a list of up to 7 ProductCondition. You'll also be able to specify more specific product conditions for each ad group.
Call the AddCampaignCriterions operation to associate the Bing Shopping campaign with your product scope criterion.
Note Product conditions may be returned by Bing Ads services in a different order from the order that you submitted.
Create an AdGroup and add it to the campaign by calling AddAdGroups.
Create a list of AdGroupCriterionAction objects in a tree structure that will be used to further refine the product catalog offers. Apply the list of actions by calling ApplyProductPartitionActions. Duplicate or conflicting product conditions attempted within an ad group's product partition group will be rejected by the ApplyProductPartitionActions operation; however, the operation will not validate whether duplicate or conflicting conditions already exist within the campaign level ProductScope.
Note To retrieve product partitions after they have been applied, call GetAdGroupCriterionsByIds and set the AdGroupCriterionIds element to null to get all product partitions for the ad group. The product partition with ParentCriterionId set to null is the root node.
Please also consider the following validation rules for the ApplyProductPartitionActions operation.
At minimum you must specify at least the root node for the product partition group tree structure. The product partition group's root BiddableAdGroupCriterion must have its condition Operand set to "All" and Attribute to null. If you are bidding on all products in the catalog equally, set the PartitionType to Unit. If you are partitioning the bids based on more specific product conditions, then set the PartitionType to Subdivision, the ParentCriterionId to null, and the Id to a negative value. You will use the negative value as ParentCriterionId for any child nodes.
The root node is considered level 0, and a tree can have branches up to 7 levels deep.
You may specify up to 5,000 AdGroupCriterionAction objects per call. The entire tree created through multiple calls can have up to 20,000 nodes.
Each of the AdGroupCriterionAction objects must have the same AdGroupId, otherwise the call will fail.
To update the Condition or Attribute properties, you must delete the existing product partition tree node and add a new product partition tree node which will get a new identifier. Likewise to update from a BiddableAdGroupCriterion to a NegativeAdGroupCriterion or vice versa, you must delete the existing product partition tree node and add a new product partition tree node which will get a new identifier.
If any action fails, all remaining actions that might have otherwise succeeded will be rejected.
All actions in one call must result in a complete tree structure. If you need to apply more than 5,000 actions per ad group, you must make multiple calls. Get the parent ad group criterion identifiers from the first call, and then add more children as needed in subsequent calls.
Every path from the root node to the end of a branch must terminate with a leaf node (ProductPartitionType=Unit). Every Unit must have a bid, unless the node is a NegativeAdGroupCriterion.
Every subdivision must have at least one leaf node that bids on the remainder of the subdivision's conditions, i.e. use the same operand as its sibling unit(s) and set its Attribute to null.
You may only specify a child node after its parent.
If you are adding partitions with multiple levels where neither the parent or child yet exist, use a negative int value as a reference to identify the parent. For example set the both the parent's Id, and the child's ParentCriterionId element to the same negative value. The negative IDs are only valid for the duration of the call. Unique system identifiers for each successfully added ad group criterion are returned in the response message.
The CriterionBid and DestinationUrl elements of the BiddableAdGroupCriterion are ignored for Subdivision partition nodes. Those elements are only relevant for Unit (leaf) partition nodes.
The Status element of the AdGroupCriterion is always ignored for product partition criterion. To add, update, or delete a product partition, set the Action element of the corresponding AdGroupCriterionAction.
To pause any product partition you must pause the entire ad group by calling UpdateAdGroups. You can call UpdateCampaigns to pause the entire campaign.
The EditorialStatus element of the AdGroupCriterion has no significant meaning for product partition criterion. Editorial validation for the product catalog is completed in the Bing Merchant Center store.
For a Delete action you only need to specify the Id and AdGroupId in the AdGroupCriterion.
If you delete a parent product partition, all of its children and descendants will also be deleted.
You may not specify duplicate product conditions in a branch. For more information, see Product Conditions.
Create a product ad. You must add at least one ProductAd to the corresponding ad group. A ProductAd is not used directly for delivered ad copy. Instead, the delivery engine generates product ads from the product details that it finds in your Bing Merchant Center store's product catalog. The primary purpose of the ProductAd object is to provide promotional text that the delivery engine adds to the product ads that it generates. For example, if the promotional text is set to “Free shipping on $99 purchases”, the delivery engine will set the product ad’s description to “Free shipping on $99 purchases.”
To create a product ad, instantiate a ProductAd object and set the PromotionalText element as needed. If you do not want to add promotional text to your ads, set PromotionalText to null or an empty string. Next, call the AddAds operation to add the product ad to an ad group.
After you complete these steps, the delivery engine can begin serving product ads for the products that it finds in the customer’s Bing Merchant Center store. If the user’s search query has product intent, the delivery engine searches the customer’s Bing Merchant Center store for products that matches the query. If it finds a product, and the product meets the conditions of the product filters specified in the product scope and product partitions, the delivery engine generates a product ad using the product details from the store.
Multiple product conditions can be specified for each campaign and ad group. Each condition is met if the product’s attribute value equals the operand’s attribute value. For example, if Operand is set to Brand and Attribute is set to Contoso, the condition is met if the value of the product catalog's Brand attribute is equal to Contoso.
The following table maps the operand names to the corresponding attribute string restrictions for campaign product scope and ad group product partition.
| Operand Name | Attribute Description | ProductScope Rules | ProductPartition Rules |
|---|---|---|---|
| All | Must be null. | Not applicable. | For an ad group's product partitions, the root node must have Operand set to "All" and Attribute set to null. |
| Brand | The product's manufacturer, brand, or publisher. A maximum of 1,000 characters. | The Brand operand may only be specified once per campaign product scope filter. | The Brand operand may be used in multiple branches, but may only be specified once per branch. |
| Condition | The condition of the product. If Operand is set to Condition, the supported attribute values that you can specify are New, Used, and Refurbished. | The Condition operand may only be specified once per campaign product scope filter. | The Condition operand may be used in multiple branches, but may only be specified once per branch. |
| Id | The product identifier defined by the merchant. A maximum of 1,000 characters. | The Id operand may only be specified once per campaign product scope filter. | The Id operand may be used in multiple branches, but may only be specified once per branch. |
| CategoryL1-5 Note: Five category operand values are available i.e. CategoryL1, CategoryL2, CategoryL3, CategoryL4, and CategoryL5. | A product category defined by the Bing Merchant Center store. Please see Bing Category Taxonomy for valid category values and taxonomy. CategoryL0 is the highest level category, and CategoryL4 is the lowest level or most granular category. A maximum of 100 characters. | Each of the CategoryL operands may be used once per campaign product scope filter. If you specify a product condition with Operand set to a product category from 1 through 5, they must be specified in ascending order. For example you can specify Operand="CategoryL2", Attribute="Pet Supplies", if a preceding product condition has the Operand="CategoryL1", Attribute="Animals & Pet Supplies" condition. | Each of the CategoryL operands may be used in multiple branches, but may only be specified once per branch. For example one branch may contain CategoryL1 and CategoryL2, but may not contain another node with the CategoryL2 operand. If you specify a product condition with Operand set to a product category from 1 through 5, they must be specified in ascending order. For example you can specify Operand="CategoryL2", Attribute="Pet Supplies", if a higher level product partition has the Operand="CategoryL1", Attribute="Animals & Pet Supplies" condition. The prior level product category operand doesn't need to be specified in the immediate parent partition. For example a CategoryL2 condition could be specified for a product partition if the parent of its parent criterion specified a CategoryL1 condition. |
| ProductType1-5 Note: Five product type operand values are available i.e. ProductType1, ProductType2, ProductType3, ProductType4, and ProductType5. | A product type or category defined by the merchant. ProductType1 is the highest level product type, and ProductType5 is the lowest level or most granular product type. The maximum length for each product type is 750 characters. | Each of the product type operands may be used once per campaign product scope filter. If you specify a product condition with Operand set to a product type from 1 through 5, they must be specified in ascending order. For example you can specify Operand="ProductType2", Attribute="Pet Supplies", if a preceding product condition has the Operand="ProductType1", Attribute="Animals & Pet Supplies" condition. | Each of the ProductType operands may be used in multiple branches, but may only be specified once per branch. For example one branch may contain ProductType1 and ProductType2, but may not contain another node with the ProductType2 operand. If you specify a product condition with Operand set to a product type from 1 through 5, they must be specified in ascending order. For example you can specify Operand="ProductType2", Attribute="Pet Supplies", if a higher level product partition has the Operand="ProductType1", Attribute="Animals & Pet Supplies" condition. The prior level product type operand doesn't need to be specified in the immediate parent partition. For example a ProductType2 condition could be specified for a product partition if the parent of its parent criterion specified a ProductType1 condition. |
| CustomLabel0-4 Note: Five custom label operand values are available i.e. CustomLabel0, CustomLabel1, CustomLabel2, CustomLabel3, and CustomLabel4. | A custom label defined by the merchant. Custom labels e.g. CustomLabel0 and CustomLabel4 are not validated based on any hierarchy. A maximum of 100 characters. | Each of the CustomLabel operands may be used once per campaign product scope filter. | Each of the CustomLabel operands may be used in multiple branches, but may only be specified once per branch. For example one branch may contain CustomLabel0 and CustomLabel1, but may not contain another node with the CustomLabel1 operand. |
The following reports can be submitted and downloaded with the Reporting Service to get performance data for Bing Shopping campaigns.
| Report Name | Description | Reporting Service Programming Elements |
|---|---|---|
| Product Dimension | Defines a product dimension performance report request that aggregates the performance data by product category, custom label, title, and type for a specified time period. You can include details in the report such as impressions, clicks, and spend that you can use to identify whether or not the Bing Shopping products are performing well. | ProductDimensionPerformanceReportRequest ProductDimensionPerformanceReportFilter ProductDimensionPerformanceReportColumn |
| Product Partition | Defines a product partition performance report request that aggregates the performance data by product group and product partition type for a specified time period. You can include details in the report such as impressions, clicks, and spend that you can use to identify whether or not the Bing Shopping products are performing well. | ProductPartitionPerformanceReportRequest ProductPartitionPerformanceReportFilter ProductPartitionPerformanceReportColumn |
| Product Partition Unit | Defines a product partition unit performance report request that aggregates the performance data by product partition unit for a specified time period. You can include details in the report such as impressions, clicks, and spend that you can use to identify whether or not the product partitions are performing well. | ProductPartitionUnitPerformanceReportRequest ProductPartitionUnitPerformanceReportFilter ProductPartitionUnitPerformanceReportColumn |
If you request a report using account level scope, then the performance reports will include aggregated data for all campaigns, whether or not the campaign type is Bing Shopping. To only get data for Bing Shopping campaigns, use campaign scope or ad group scope. The following is an example SOAP request that specifies campaign level scope.
<Scope> <AccountIds i:nil="true" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" /> <AdGroups i:nil="true" /> <Campaigns> <CampaignReportScope> <AccountId>AccountIdGoesHere</AccountId> <CampaignId>CampaignIdGoesHere</CampaignId> </CampaignReportScope> </Campaigns> </Scope>
For more information about using the Reporting Service, see Reports and Request and Download a Report.
When you download entities with the Bulk Service, if the DataScope element of the download request includes EntityPerformanceData, the download file will also include performance statistics for most of the record types listed in Create a Bing Shopping Campaign with the Bulk Service. The tree root Ad Group Product Partition record contains performance statistics for the entire tree, the Ad Group Product Partition record corresponding to each subdivision contains the performance statistics of all leaf nodes under it, and the Ad Group Product Partition record corresponding to each unit contains performance statistics only for that specific node.
Performance statistics returned by the Bulk and Reporting services lags behind the performance statistics that you see in the Bing Ads web application by up to an hour. Please note the following differences between the Bulk Service and Reporting Service with respect to the freshness of the tree structure and performance statistics.
|