CSS label management

We would like to introduce the beta version of the Merchant API. It is the new version of the Content API for Shopping and the future.

For information about how Merchant API can improve your integration and how you can help shape the future, see Announcing the Merchant API Beta.

Comparison Shopping Services (CSSs) can place shopping ads on Google on behalf of merchants in countries where the CSS program is available. The Content API allows CSS domains and CSS groups to organize their associated accounts using labels. CSS domains can list, label, and filter the Merchant Center accounts associated with the domain. CSS groups can label and list the CSS domains affiliated with the group. These Content API services provide programmatic equivalents to some of the features available in the Comparison Shopping Service Center.

For more information about CSSs, see Comparison Shopping Services. For information on working with labels in CSS Center, see Use account labels in Comparison Shopping Service Center.

CSS account types

CSSs use the following three types of accounts:

• CSS groups are the top-level accounts that can contain one or multiple CSS domains.
• CSS domains are the accounts for the CSSs themselves, which place Shopping ads on behalf of merchants. Each CSS domain can only belong to one CSS group.
• Merchant Center accounts are the merchants for which CSS domains place Shopping ads. CSSs can be associated with several different types of Merchant Center accounts, including multi-client accounts (MCAs) and individual merchant accounts. Each Merchant Center account can only be associated with one CSS domain. For more information about different types of Merchant Center accounts, see Account types in Comparison Shopping Service Center.

CSS label types

CSSs use two types of labels:

• Manual labels are created and assigned to Merchant Center accounts by CSS domains, and to CSS domains by CSS groups.
• Automatic labels are automatically created and assigned to Merchant Center accounts by CSS Center. Automatic labels are available for different types of account metrics and can help you identify important accounts and significant account activity.

For more information about label types, including the available automatic labels, see Use account labels in Comparison Shopping Service Center.

Content API functionality and endpoints for CSSs

The Content API offers the following endpoints for CSSs:

• accounts.labels: Allows you to create, retrieve, and modify labels to apply to CSS domain and Merchant Center accounts. For an example, see Creating a label.
• accounts.updatelabels: Allows you to apply labels to a single Merchant Center account. For an example, see Applying a label to a Merchant Center account.
• accounts.list: Allows you to retrieve all the Merchant Center accounts associated with a CSS domain, including the labels applied to each account. You can also filter by label id to retrieve a subset of associated accounts. For an example, see Using labels to filter Merchant Center accounts.
• accounts.get: Allows you to retrieve the labels applied to a single Merchant Center account.
• csses: Allows you to view and manage the associations between labels and CSS domains. For an example, see Applying a label to a CSS domain.

When calling accounts endpoints as a CSS domain, be aware of the following requirements:

• CSS domains must provide their cssId instead of a merchantId.
• CSS domains must provide a query parameter of view=CSS.
• CSS domains must provide their associated Merchant Center account id as the accountId.

Note: Only CSS domain and CSS group accounts can use labels. Merchant Center accounts themselves do not have access to the label functionality.

Example: Create a label

You can use the accounts.labels.create method to create a new label. Labels can be applied to CSS domains and Merchant Center accounts. However, labels for the different account types are separate and cannot be used interchangeably. To create a domain-level label, which can be applied to Merchant Center accounts associated with the domain, use the CSS domain ID as the accountId when creating the label. To create a group-level label, which can be applied to CSS domains affiliated with the group, use the CSS group ID as the accountId when creating the label.

The following example demonstrates how to create a domain-level key-accounts label, which can then be applied to Merchant Center accounts associated with the domain. To create the label, make a POST request using the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/accounts/accountId/labels

{
 "name": "key-accounts",
 "description": "All accounts with over a million products"
}

Example: Apply a label to a Merchant Center account

You can use the accounts.updatelabels method to assign labels to a Merchant Center account associated with a CSS domain. The following example demonstrates how to apply the key-accounts label created in the previous example to one of your most important Merchant Center accounts.

Note: You must use the id of the label, not the name, when applying a label to a Merchant Center account. The id is automatically assigned to the label and returned in the response when the label is created. You can also retrieve the label id by calling accounts.labels.list.

To apply the label, make a POST request using the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/cssId/accounts/subaccountId/updatelabels/

{
 "labelIds": [‘123’] // ‘key-accounts’
}

Example: Use labels to filter Merchant Center accounts

After creating and applying labels to the Merchant Center accounts associated with a CSS domain, you can use the accounts.list method and pass the label query parameter in your request to return only the accounts with that label. The following example demonstrates how to filter the Merchant Center accounts associated with a CSS domain, using the id (123) of the key-accounts label created in the Creating a label example. To retrieve the accoungs, make a GET request using the following URL:

https://shoppingcontent.googleapis.com/content/v2.1/cssId/accounts?view=CSS&label=123

No request body is needed.

Example: Apply a label to a CSS domain

You can also use the csses.updatelabels method to assign labels to a CSS domain affiliated with a CSS group. The following example demonstrates how to apply a key-domains group-level label created using the accounts.labels.create method to one of your most important CSS domain accounts. Keep in mind that labels for CSS domains and Merchant Center accounts are separate. Group-level labels must be created using a CSS group ID as its accountId.

Note: You must use the id of the label, not the name, when applying a label to a CSS domain. The id is automatically assigned to the label and returned in the response when the label is created. You can also retrieve the label id by calling accounts.labels.list.

To apply the label, make a POST request using the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/cssGroupId/csses/cssDomainId/updatelabels/

{
 "labelIds": [‘456’] // ‘key-domains’
}