Asset Group Listing Group Record - Bulk
Defines an asset group listing group that can be uploaded and downloaded in a bulk file.
You can upload Asset Group Listing Group records for multiple ad groups in the same bulk file, as long as the validation rules are satisfied as described below.
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 and Parent Id 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 also fail.
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.
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.
You can download all Asset Group Listing Group records in the account by including the DownloadEntity value of AssetGroupListingGroups in the DownloadCampaignsByAccountIds or DownloadCampaignsByCampaignIds service request. Additionally the download request must include the EntityData scope. For more details about the Bulk service including best practices, see Bulk Download and Upload.
If you are using the Bing Ads SDKs for .NET, Java, or Python, you can save time using the BulkServiceManager to upload and download the BulkAssetGroupListingGroup object, instead of calling the service operations directly and writing custom code to parse each field in the bulk file.
For an Asset Group Listing Group record, the following attribute fields are available in the Bulk File Schema.
- Asset Group
- Campaign
- Client Id
- Id
- Is Excluded
- Modified Time
- Parent Id
- Parent Listing Group Id
- Product Condition 1
- Product Value 1
- Status
- Sub Type
Asset Group
The name of the asset group that the asset group listing group belongs to.
For add, update, and delete, you must specify either the Parent Id, or Asset Group and Campaign field.
Add: Read-only and Required
Update: Read-only and Required
Delete: Read-only and Required
Campaign
The name of the campaign that contains the asset group and listing group.
For add, update, and delete, you must specify either the Parent Id, or Asset Group and Campaign field.
Add: Read-only and Required
Update: Read-only and Required
Delete: Read-only and Required
Client Id
Used to associate records in the bulk upload file with records in the results file. The value of this field is not used or stored by the server; it is simply copied from the uploaded record to the corresponding result record. It may be any valid string to up 100 in length.
Add: Optional
Update: Optional
Delete: Read-only
Id
The system-generated identifier of the asset group listing group.
Add: Optional. You must either leave this field empty, or specify a negative identifier. A negative identifier set for the asset group listing group can then be referenced in the Parent Id field of dependent record types such as ads, keywords, or criterion. This is recommended if you are adding new asset group listing groups and new dependent records in the same Bulk file. For more information, see Bulk File Schema Reference Keys.
Update: Read-only and Required
Delete: Read-only and Required
Is Excluded
Determines whether products belongs to the list group should be excluded when serving.
If set to true it is a negative criterion, and otherwise if false it is a positive criterion.
Add: Required
Update: Read-only
Delete: Read-only
Modified Time
The date and time that the entity was last updated. The value is in Coordinated Universal Time (UTC).
Note
The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
Add: Read-only
Update: Read-only
Delete: Read-only
Parent Id
The ID of the asset group that contains the listing group.
For add, update, and delete, you must specify either the Parent Id or Asset Group and Campaign field.
Add: Read-only and Required
Update: Read-only and Required
Delete: Read-only and Required
Parent Listing Group Id
At minimum you must specify at least the root node for the tree structure.
The listing 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 products based on more specific product conditions, then set the Sub Type field to Subdivision, the Parent Listing Group Id to null or empty, and the Id to a negative value. You will use the negative value as Parent Listing Group Id for any child nodes.
Add: Required
Update: Read-only and Required
Delete: Read-only and Required
Product Condition 1
The condition's operand. The operands implicitly include the equal operator. For example, you can read Brand as Brand=.
Use the Product Condition 1 as the operand for the Product Value 1.
Multiple product conditions can be specified for each Microsoft Performance Max asset 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.
In Performance Max campaigns the product conditions can be set only at asset group level. The following table describes Product Condition (operand) and Product Value (attribute) business rules for asset group AssetGroupListingGroup objects.
| Product Condition (Operand) | Product Value (Attribute) Description | Asset Group Product Partition Rules |
|---|---|---|
| All | Must be null. | For an asset group's product partitions, the root node must have operand set to All and attribute set to null or empty. |
| Brand | The product's manufacturer, brand, or publisher. A maximum of 1,000 characters. |
For an asset group's product partitions, the root node must have operand set to All and attribute set to null or empty. |
| CategoryL1-5 Five category operand values are available i.e. CategoryL1, CategoryL2, CategoryL3, CategoryL4, and CategoryL5. |
A product category defined by the Microsoft Merchant Center store. 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 in multiple branches. 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 set the operand to a product category from 1 through 5, they must be specified in ascending order. For example, the operand can be set to CategoryL2 with the attribute Pet Supplies, if a higher-level product partition has operand CategoryL1 with attribute Animals & Pet Supplies. 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 specified a CategoryL1 condition. |
| Channel | The Local Inventory Ads (LIA) channel. Possible values include "Local Stores" and "Online". If the campaign has not opted into Local Inventory Ads, all offers are by default Online only (Channel=Online) and Single-channel (ChannelExclusivity=Single-channel). For more information, see the Local Inventory Ads help page. |
The Channel operand may be used in multiple branches, but may only be specified once per branch. |
| ChannelExclusivity | The Local Inventory Ads (LIA) channel exclusivity. Possible values include "Single-channel" and "Multi-channel". If the campaign has not opted into Local Inventory Ads, all offers are by default Online only (Channel=Online) and Single-channel (ChannelExclusivity=Single-channel). For more information, see the Local Inventory Ads help page. |
The ChannelExclusivity 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 be used in multiple branches, but may only be specified once per branch. |
| CustomLabel0-4 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 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. |
| Id | The product identifier defined by the merchant. A maximum of 1,000 characters. |
The Id operand may be used in multiple branches, but may only be specified once per branch. |
| ProductType1-5 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. A maximum of 100 characters. |
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 set the operand to a product type from 1 through 5, they must be specified in ascending order. For example, the operand can be set to ProductType2 with attribute Pet Supplies, if a higher-level product partition has operand ProductType1 with attribute Animals & Pet Supplies. 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 specified a ProductType1 condition. |
Add: Required
Update: Read-only. You cannot update the condition or value fields. To update the conditions you must delete the product partition and add a new one.
Delete: Read-only
Product Value 1
The condition's attribute value.
An attribute's value must exactly match the value specified in the customer's Microsoft Merchant Center catalog file.
Add: Required
Update: Read-only. You cannot update the condition or value fields. To update the conditions you must delete the product partition and add a new one.
Delete: Read-only
Status
The status of the asset group listing group.
Possible values are Active, Deleted.
Add: Optional.
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Required. The Status must be set to Deleted.
Sub Type
The type of asset group listing group.
Possible values are Subdivision and Unit.
Add: Required
Update: Read-only
Delete: Read-only