Skip to main content

Google Ads

Google Ads is Google's online advertising platform that enables businesses to create and manage advertising campaigns across Google Search, Display Network, YouTube, and other Google properties. With Google Ads, you can reach potential customers at the moment they're searching for products or services like yours, display visual ads across millions of websites, and track campaign performance with detailed analytics.

This connector provides comprehensive access to the Google Ads API v23, enabling you to programmatically manage campaigns, ad groups, keywords, ads, budgets, and access detailed performance reports.

Authentication Types​

Google Ads supports 1 authentication method:

  • OAuth 2.0 - Standard OAuth authentication with Google Ads API scope
    • Pros: Secure, user-authorized access to Google Ads accounts
    • Cons: The Google Cloud project that owns the OAuth client needs Google Ads API access approved before it can reach real (non-test) accounts
    • Best for: Programmatic campaign management, automated reporting, and integration with other systems

Configuration​

SettingRequiredDescription
Customer IDYesThe 10-digit ID of the Google Ads account that tools query by default
Manager Account IDNoOnly when you reach the account through a manager account (MCC)
Developer TokenNoLegacy. Google no longer requires it; leave empty

Google Ads API access is granted to the Google Cloud project that owns your OAuth client, not to a developer token. Google ignores the developer-token header, and it will be rejected in a future API version, so you don't need one.

Access levels for the Cloud project:

  • Test (default): test accounts only. Calls to a real account fail with CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION.
  • Explorer: real accounts, up to 2,880 operations/day. Usually approved instantly. Enough for most reporting and assistant use.
  • Basic: higher limits. Requires Google brand verification of the project's OAuth consent screen.
  • Standard: unlimited operations for approved applications.

You apply in the Google Cloud Console, as shown in Request Google Ads API access below.

note

Earlier guides send you to API Center in Google Ads for a developer token. API Center exists only in manager accounts and is now used only for the App Conversion Tracking API. You don't need a manager account for this connector.

Customer ID​

Your Customer ID is a unique 10-digit identifier for your Google Ads account (sometimes called Client Customer ID). This determines which account the API calls will be made against.

How to find your Customer ID:

  1. Sign in to your Google Ads account
  2. Look at the top right corner of any page
  3. Your Customer ID is displayed next to your account name (format: 123-456-7890)
  4. Important: Remove the hyphens when entering in Willow (use 1234567890)
note

If you manage multiple Google Ads accounts through a manager account (MCC), each sub-account has its own Customer ID. Use the specific Customer ID for the account you want to access. If the signed-in user has access only through the manager (not directly on the sub-account), also set Manager Account ID to the manager's 10-digit ID.

Setting up OAuth​

Follow these steps to configure OAuth authentication for Google Ads:

1. Create a Google Cloud Project​

  1. Go to the Google Cloud Console
  2. Click Select a project at the top of the page, then click New Project
  3. Enter a project name (e.g., "Willow Google Ads Integration")
  4. Click Create

2. Enable the Google Ads API​

  1. In your Google Cloud project, navigate to APIs & Services > Library
  2. Search for "Google Ads API"
  3. Click on Google Ads API and click Enable
  4. Wait for the API to be enabled (this may take a minute)

3. Request Google Ads API access​

Without this step the project stays at Test access and can't reach real accounts.

  1. In the same project, open Google Ads API → Overview (https://console.cloud.google.com/google/ads-apis/overview?project=<your-project-id>)
  2. Under Access level, apply for Explorer access and fill in the short form
  3. Wait for Current access level: Explorer. This is usually immediate. If you see "That action is temporarily unavailable", retry after a minute.
caution

Google may reject Explorer or Basic applications from projects on a Google Cloud free trial. If that happens, upgrade the project's billing account to a paid account and apply again.

  1. Navigate to APIs & Services > OAuth consent screen
  2. Select External as the User Type (or Internal if you're using Google Workspace and want to restrict to your organization)
  3. Click Create
  4. Fill in the required information:
    • App name: Enter your application name (e.g., "Willow")
    • User support email: Select your email address
    • Developer contact information: Enter your email address
  5. Click Save and Continue
  6. On the Scopes page, click Add or Remove Scopes
  7. Scroll down or search for the Google Ads API scope:
    • https://www.googleapis.com/auth/adwords (required for Google Ads API access)
  8. Check the box next to this scope
  9. Click Update and then Save and Continue
  10. If using External user type, add test users who should have access during development (add the email addresses of Google Ads account users)
  11. Click Save and Continue to review, then click Back to Dashboard
tip

The Google Ads API uses a single OAuth scope (adwords) that grants full access. Unlike some Google APIs, there are no separate read-only or limited scopes.

5. Create OAuth 2.0 Credentials​

  1. Navigate to APIs & Services > Credentials
  2. Click Create Credentials at the top and select OAuth client ID
  3. Select Web application as the Application type
  4. Enter a name for your OAuth client (e.g., "Willow Web Client")
  5. Under Authorized redirect URIs, add:
    • For SaaS deployments: https://{org}.withwillow.ai/{org}/api/auth/callback
    • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback
  6. Click Create
  7. A dialog will appear with your Client ID and Client Secret
  8. Copy both values - you'll need them for Willow configuration
tip

The redirect URI must match exactly, including the org slug in the path. If Google shows redirect_uri_mismatch, copy the redirect_uri value from the Google error page's request details and add that to the client.

6. Configure in Willow​

  1. Log in to your Willow instance
  2. Navigate to Connectors or Integrations
  3. Find and select Google Ads
  4. Under Configuration:
    • Customer ID: Enter your 10-digit Customer ID (no hyphens)
    • Manager Account ID: Leave empty unless you reach the account through a manager account
    • Developer Token: Leave empty
  5. Choose OAuth as the authentication method
  6. Paste your Client ID from step 5
  7. Paste your Client Secret from step 5
  8. The scope https://www.googleapis.com/auth/adwords is pre-selected
  9. Click Connect or Authorize
  10. You'll be redirected to Google to grant permissions
  11. Important: Sign in with a Google account that has access to the Google Ads account specified by your Customer ID
  12. Review the permissions and click Allow
  13. You'll be redirected back to Willow with a successful connection
caution

The connector includes tools that create, change, and remove campaigns, budgets, keywords, and ads, which can affect ad spend. For reporting-only use, disable every tool that isn't read-only on the Tools tab before publishing.

7. Verify the Connection​

After authorization, test the connection:

  1. Use the List Accessible Customers tool to verify you can access your account
  2. Try the Get Customer Details tool to see your account information
  3. Run a simple List Campaigns query to verify data access

Common Use Cases​

Campaign Performance Monitoring​

Use the reporting tools to track campaign performance:

Tool: Get Campaign Performance Report
Parameters:
- dateRange: "LAST_30_DAYS"
- campaignStatus: "ENABLED"

This returns key metrics (impressions, clicks, cost, conversions) for all active campaigns over the last 30 days.

Bulk Keyword Management​

Add multiple keywords to an ad group efficiently:

Tool: Add Keywords
Parameters:
- adGroup: "customers/1234567890/adGroups/98765"
- keywords: [
{"text": "buy shoes online", "matchType": "PHRASE"},
{"text": "running shoes", "matchType": "BROAD"},
{"text": "nike shoes", "matchType": "EXACT"}
]

Campaign Creation​

Create a new search campaign:

Tool: Create Campaign
Parameters:
- name: "Summer Sale 2026"
- advertisingChannelType: "SEARCH"
- status: "PAUSED"
- campaignBudget: "customers/1234567890/campaignBudgets/11111"
- biddingStrategyType: "MAXIMIZE_CONVERSIONS"

Custom Reporting with GAQL​

For advanced users, execute custom queries using Google Ads Query Language:

Tool: Run Custom GAQL Query
Parameters:
- query: "SELECT campaign.name, ad_group.name, metrics.clicks, metrics.impressions, metrics.cost_micros FROM ad_group WHERE campaign.status = 'ENABLED' AND segments.date DURING LAST_7_DAYS ORDER BY metrics.clicks DESC LIMIT 50"

Automated Bid Adjustments​

Update keyword bids based on performance:

Tool: Update Keywords
Parameters:
- keywords: [
{
"resourceName": "customers/1234567890/adGroupCriteria/98765~11111",
"cpcBidMicros": 2500000
}
]

Note: 2,500,000 micros = $2.50 (or 2.50 in your account currency)

Understanding Key Concepts​

Resource Names​

Google Ads API uses resource names to identify entities. The format is:

  • Campaign: customers/1234567890/campaigns/98765
  • Ad Group: customers/1234567890/adGroups/98765
  • Keyword: customers/1234567890/adGroupCriteria/98765~11111

Micros (Currency)​

All monetary values in the Google Ads API are represented in "micros":

  • 1 currency unit = 1,000,000 micros
  • $1.50 = 1,500,000 micros
  • €10.25 = 10,250,000 micros

To convert: amount_in_currency * 1,000,000 = micros

GAQL (Google Ads Query Language)​

GAQL is a SQL-like language for querying Google Ads data:

SELECT
campaign.name,
metrics.impressions,
metrics.clicks
FROM campaign
WHERE campaign.status = 'ENABLED'
AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.clicks DESC
LIMIT 100

Key features:

  • SELECT: Choose fields to retrieve
  • FROM: Specify the resource type
  • WHERE: Filter results
  • ORDER BY: Sort results
  • LIMIT: Restrict number of rows

Batch Operations​

Many mutate operations support batch processing for efficiency:

  • Create multiple campaigns in one request
  • Update multiple keywords simultaneously
  • Remove multiple ads at once

Use the "Mutate" tools (e.g., Mutate Campaigns, Mutate Ad Groups) for batch operations.

Troubleshooting​

"CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION" or "ACTION_NOT_PERMITTED"​

Cause: The Google Cloud project that owns the OAuth client still has Test access, so it can't reach real accounts.

Solution:

  1. Open Google Ads API → Overview for the project in the Google Cloud Console
  2. Apply for Explorer access (or Basic for higher limits)
  3. Once the page shows the new access level, retry the tool call. You don't need to reconnect.

"INVALID_CUSTOMER_ID" Error​

Cause: The Customer ID format is incorrect or the account doesn't exist.

Solution:

  1. Verify your Customer ID in Google Ads (top right corner, format: 123-456-7890)
  2. Remove hyphens when entering in Willow (use 1234567890)
  3. Ensure the Customer ID is exactly 10 digits
  4. Verify the authenticated user has access to this Customer ID
  5. Update the Customer ID in Configuration

"User Does Not Have Permission to Access Customer"​

Cause: The Google account used for OAuth doesn't have access to the specified Customer ID.

Solution:

  1. Verify the Customer ID is correct
  2. Sign in to Google Ads with the same Google account you used for OAuth
  3. Check if you can see and access the account with that Customer ID
  4. If not, ask a Google Ads administrator to grant you access with at least:
    • Standard access level for read operations
    • Admin access level for write operations
  5. After gaining access, re-authorize the connection in Willow

"QUERY_ERROR" - GAQL Syntax Issues​

Cause: The GAQL query has syntax errors or references invalid field combinations.

Solution:

  1. Check the GAQL documentation for correct syntax
  2. Use the Google Ads Query Validator to test queries
  3. Common issues:
    • Incorrect field names (use campaign.name, not campaignName)
    • Invalid field combinations (some metrics can't be queried with certain attributes)
    • Missing quotes around string values in WHERE clauses
  4. Try a simpler query first, then add complexity

Rate Limiting / Quota Exceeded​

Cause: You've exceeded the daily operations limit for your Cloud project's access level.

Solution:

  1. Explorer: 2,880 operations/day. Apply for Basic in the Cloud Console (requires brand verification)
  2. Basic: optimize queries or apply for Standard access
  3. Standard: unlimited for most use cases
  4. Use batch operations to reduce API call count
  5. Use SearchStream for large reports instead of paginated Search
  6. Cache frequently accessed data instead of repeated queries

"OAuth Scope Mismatch" or Insufficient Permissions​

Cause: The OAuth token doesn't have the required adwords scope.

Solution:

  1. Go to APIs & Services > Credentials in Google Cloud Console
  2. Verify the OAuth consent screen includes the https://www.googleapis.com/auth/adwords scope
  3. In Willow, disconnect and reconnect the Google Ads integration
  4. During OAuth flow, ensure you grant the requested permissions
  5. If the scope isn't requested, check your Willow connector configuration

Response Too Large / Memory Issues​

Cause: Query returns too much data causing timeouts or memory issues.

Solution:

  1. Use the Stream Large Report tool instead of regular search for large datasets
  2. Add LIMIT clause to GAQL queries to restrict results
  3. Add more specific WHERE clauses to filter data
  4. Query date ranges in smaller chunks (e.g., one week at a time instead of all time)
  5. Select only the fields you need in the SELECT clause

"Invalid Resource Name" Error​

Cause: The resource name format is incorrect or the resource doesn't exist.

Solution:

  1. Verify resource name format:
    • Campaign: customers/1234567890/campaigns/98765
    • Ad Group: customers/1234567890/adGroups/98765
    • Keyword: customers/1234567890/adGroupCriteria/98765~11111
  2. Ensure no extra spaces or typos
  3. Verify the resource exists (not removed)
  4. Get resource names from List or Search tools rather than constructing manually

Advanced Topics​

Using Manager Accounts (MCC)​

If you manage multiple Google Ads accounts through a Manager Account (MCC), you can access sub-accounts by specifying different Customer IDs in individual tool calls. When the signed-in user's access comes through the manager, set Manager Account ID to the manager's ID. Willow then sends it as the login-customer-id header on every call. Leave it empty when the user has direct access to the account.

Understanding Bidding Strategies​

Google Ads supports multiple bidding strategies:

  • Manual CPC: You set bids manually
  • Maximize Conversions: Google automatically sets bids to get the most conversions
  • Target CPA: Automatically sets bids to achieve a target cost per acquisition
  • Target ROAS: Aims for a specific return on ad spend
  • Maximize Conversion Value: Gets the most conversion value within your budget

Choose the appropriate strategy when creating campaigns based on your goals.

Performance Metrics vs. Attributes​

In GAQL queries:

  • Attributes (e.g., campaign.name, ad_group.status) describe the resource
  • Metrics (e.g., metrics.clicks, metrics.impressions) measure performance
  • Segments (e.g., segments.date, segments.device) break down data by dimensions

Not all combinations are valid - use the Google Ads API Field Reference to check compatibility.

Additional Resources​