Responsive Search Ad (RSA) customization

  • Ad customizers enable dynamic text customization in responsive search ads using placeholders in titles and description lines.

  • Creating an ad customizer involves two main steps: defining a broad customizer attribute and linking it with specific values at various hierarchical levels (customer, campaign, ad group, or keyword criterion).

  • Ad customizer attributes have a unique name, a defined type (text, number, price, or percent), and there is a limit of 40 enabled customizer attributes per account.

  • Linking customizer attributes at different levels allows for specificity, with more specific links overriding general ones.

  • To use an ad customizer in responsive search ads, you include the customizer attribute name and a default value in a specific format within the ad's text assets.

Ad customizers are a powerful tool that lets you customize the text content of your responsive search ads using dynamic text placeholders.

You can create and use an ad customizer or use a built-in ad customizer.

Create and use an ad customizer

Follow these steps to create an ad customizer for RSAs:

  1. Create the customizer attribute.

    The customizer attribute is a broad category that describes the kind of change you intend to link to this customizer—for example, "product price" or "discount percent".

  2. Link the customizer attribute with a customer, campaign, ad group, or keyword ad group criterion.

    Set the specific values you want to use for the specific resource.

Create a customizer attribute

First, you need to create a new customizer attribute, represented by CustomizerAttribute using CustomizerAttributeService with two required fields:

name
The name of the customizer, which must be unique (case insensitive). Since there is a limit of 40 customizers, you might need to reuse customizers across different resources, so be sure to choose a name that represents a broad category of what kind of customizations this will be used for.
type
The type of the customizer—text, number, price or percent—defined by CustomizerAttributeType.

When you create a new customizer attribute, you get its resource name back, which is required in the next step.

You can link the previously created customizer attribute at many levels using the following services:

Regardless of which level you want and which corresponding service you use, the same pieces of information are required:

customizer_attribute
The resource name of the customizer attribute that you created in the previous step.
value

The value that you want to insert into your ads when you reference this customizer attribute. This field is defined by CustomizerValue.

You need to specify type and string_value to create CustomizerValue. The type value should be the same as the customizer attribute you're linking, and string_value is the value that you want the Google Ads API to use.

Resource name of the resource you want to link the customizer attribute to

The name varies based on the resource type. For instance, to create CampaignCustomizer, specify the campaign.

Once you finish this step, you're ready to use the ad customizer in responsive search ads that are included in the resource hierarchy you linked the customizer attribute to. For instance, if you link the customizer attribute to the campaign with an ID A, you can use that ad customizer in an ad created under any ad groups inside campaign A. You cannot use the ad customizer in an ad under ad groups inside campaign B.

Ad customizers in responsive search ads

To use the ad customizer in headlines and description of the responsive search ads, you need to create an AdTextAsset object with text including the following syntax:

{CUSTOMIZER.CUSTOMIZER_ATTRIBUTE_NAME:DEFAULT_VALUE}

  • CUSTOMIZER_ATTRIBUTE_NAME is the name of the customizer attribute that you set when you created it, not the resource name of the customizer attribute nor its ID.

  • DEFAULT_VALUE is the default value for the ad customizer.

Refer to the responsive search ads guide for more information about setting up the ads.

Rules and limitations

  • There can only be one link per level—customer, campaign, ad group, or ad group criterion—and the most specific one will override the more general one. For example, if you have this customizer attribute defined at the campaign level and the ad group level, then ads within the linked ad group will use the ad group one, but ads from other ad groups in that campaign will use the campaign one.

  • You can have up to 40 enabled CustomizerAttribute objects in your account. If you reach this limit, you need to remove the unused ones before creating a new one.

  • There are rules for customizer attributes with type PRICE:

    • Currency codes and symbols can appear before or after the number. For example, $100, 100$, USD100, 100USD are all valid values.
    • There should be no spaces between the number and the currency codes or symbols. For example, $ 100 is invalid.
    • See the currency codes and symbols that can be used as part of the specified value.

Use built-in ad customizers

You can use built-in customizer tags directly within your Responsive Search Ad (RSA) headlines and descriptions. These tags allow you to dynamically insert keywords, locations, and countdowns into your ad text.

Keyword insertion

Keyword insertion dynamically updates your ad text to include the keyword that caused your ad to show. This can make your ads more relevant to users' searches.

See Set up keyword insertion for your ad text.

Syntax: {Keyword:Default text}

Include this tag in your headline or description fields when you create or update an AdGroupAd with a ResponsiveSearchAd type using the API.

Example

Suppose you have a headline like "Buy {Keyword:Chocolate} Online". If the user searches for "dark chocolate", the headline could appear as: "Buy Dark Chocolate Online". If the keyword cannot be inserted, the "Default text" ("Chocolate" in this case) will be used instead.

See About keyword insertion.

Location insertion

Tailor your ad text based on where your customers are located or the locations they show interest in.

Syntax: {LOCATION(Level):Default text}

  • Level: Specify the geographic level, such as City, State, or Country. If omitted, it defaults to the most specific level available.

Example

Headline: "Pizza Delivery in {LOCATION(City):Your Area}"

If a user is in New York City, they might see: "Pizza Delivery in New York City" Users outside a specific area would see: "Pizza Delivery in Your Area"

See About location insertion for responsive search ads.

Countdown functions

Create a sense of urgency by showing a real-time countdown to a specific event or sale.

Syntax

  • {COUNTDOWN(yyyy-MM-dd HH:mm:ss,daysBefore)} - Counts down to a specific time in the advertiser's account timezone.
  • {GLOBAL_COUNTDOWN(yyyy-MM-dd HH:mm:ss,daysBefore)} - Counts down to a specific time in the user's timezone.
  • daysBefore: How many days before the end date the countdown should start appearing.

Example

Headline: "Sale Ends in {COUNTDOWN(2026-01-31 23:59:59,5)}"

This ad will show a countdown starting 5 days before January 31st, 2026, 23:59:59 in the advertiser's timezone.

See Highlight upcoming events with countdowns.

Implementation using the API

To use these built-in customizers, include the tag syntax within the text fields of the AdTextAsset objects for your RSA's headlines and descriptions when mutating an AdGroupAd resource.

Example snippet (conceptual JSON)

{
  "ad": {
    "responsiveSearchAd": {
      "headlines": [
        { "text": "Great Deals on {Keyword:Shoes}" },
        { "text": "Free Shipping in {LOCATION(City):Your City}" },
        { "text": "Offer Ends: {COUNTDOWN(2026-01-31 23:59:59,5)}" }
      ],
      "descriptions": [
        { "text": "Find the best {Keyword:footwear} for your needs." },
        { "text": "Limited time offer, don't miss out!" }
      ]
    },
    "finalUrls": ["https://www.example.com"]
  }
}
Previous
Mutate ads
Next
Retrieve ads