> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Google Ads

> Manage PPC campaigns, view metrics, and optimize spend

Google Ads is the most involved Google integration in Hiveku — in addition to OAuth, it requires a Google-issued **developer token** and a **customer ID**. Once connected, you get campaign metrics, ad group performance, keyword data, and conversion tracking.

<Info>
  Before you start: [Set up a Google Cloud OAuth app](/how-tos/google-oauth-app) and enable the **Google Ads API** in your Google Cloud project.
</Info>

## What You'll Need

| Item                   | Where to get it                                              |
| ---------------------- | ------------------------------------------------------------ |
| Google OAuth app       | [Set up a Google Cloud OAuth app](/how-tos/google-oauth-app) |
| Google Ads API enabled | Google Cloud > APIs & Services > Library                     |
| Developer token        | Google Ads manager account > Tools > API Center              |
| Customer ID            | Google Ads UI, top-right corner (10 digits)                  |
| Manager ID (optional)  | Your MCC customer ID, if applicable                          |

## Getting a Developer Token

A developer token authenticates your app to the Google Ads API. It's tied to a **manager account** (MCC).

<Steps>
  <Step title="Sign in to a Google Ads manager account">
    Go to [ads.google.com](https://ads.google.com) and sign in with a Google account that has a manager account (MCC). If you don't have one, create one at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts).
  </Step>

  <Step title="Open API Center">
    In the manager account, navigate to **Tools > API Center**. (On newer UIs: **Admin > API Center**.)
  </Step>

  <Step title="Apply for a developer token">
    Fill out the form describing how you'll use the Google Ads API. Google reviews this — approval can take anywhere from minutes to a few business days. You start with **Test access** (which only works against test accounts).

    For production — pulling data from real campaigns — request **Basic access** or **Standard access**. Upgrades are typically required before you can ingest live campaign data.
  </Step>

  <Step title="Copy the developer token">
    Once approved, copy the token string from the API Center. It looks like a short alphanumeric code.
  </Step>
</Steps>

<Warning>
  A test token only works with test accounts. If your connection returns no data, check your token's access level first.
</Warning>

## Finding Your Customer ID

Every Google Ads account has a 10-digit customer ID — shown in the top-right corner of the Google Ads UI as `123-456-7890`.

**Paste without the dashes**: `1234567890`.

If you manage accounts via an MCC, you also need the MCC's customer ID as the **Manager ID** (login customer ID).

## Connect via One-Click OAuth

<Steps>
  <Step title="Open the integration">
    **Marketing > PPC > Add Connection > Google Ads**.
  </Step>

  <Step title="Fill in the fields">
    * **OAuth app:** select your registered Google app
    * **Developer token:** paste the token from API Center
    * **Customer ID:** 10 digits, no dashes
    * **Manager ID (optional):** if you're managing via an MCC, paste the MCC's customer ID
  </Step>

  <Step title="Authorize with Google">
    Click **Authorize**. You'll be redirected to Google to consent to the `adwords` scope:

    ```
    https://www.googleapis.com/auth/adwords
    ```

    Sign in with an account that has access to the Google Ads customer ID you entered.
  </Step>

  <Step title="Confirm the connection">
    Hiveku saves the OAuth tokens plus the developer token and customer IDs. Campaigns start populating on the PPC dashboard within a few minutes.
  </Step>
</Steps>

## Connect via Manual Refresh Token

For automation-heavy setups, you can generate a refresh token out-of-band.

<Steps>
  <Step title="Open OAuth Playground">
    Go to [developers.google.com/oauthplayground](https://developers.google.com/oauthplayground). In the gear icon, set **Use your own OAuth credentials** and paste your Client ID and Secret. Temporarily add the Playground URL as an authorized redirect URI in your Google Cloud OAuth client.
  </Step>

  <Step title="Authorize the adwords scope">
    Pick **Google Ads API** and the scope:

    ```
    https://www.googleapis.com/auth/adwords
    ```

    Sign in, consent, and exchange the authorization code for tokens. Copy the refresh token.
  </Step>

  <Step title="Paste into Hiveku">
    In **Marketing > PPC > Add Connection > Google Ads**, switch to the **Manual** tab:

    * **Refresh token:** paste
    * **Developer token:** paste
    * **Customer ID:** 10 digits, no dashes
    * **Manager ID (optional):** MCC customer ID

    Save.
  </Step>
</Steps>

## What You Get

* **Campaign metrics** — spend, impressions, clicks, conversions, CPA, ROAS
* **Ad group performance**
* **Keyword-level data** — match types, quality score, position
* **Conversion tracking** — view-through and click-through
* **Search terms report**

Data refreshes on a schedule. Historical data is backfilled based on your Google Ads account's retention.

## Connecting Multiple Accounts

Repeat the flow for each customer ID. If all accounts are under a single MCC, you can reuse the same developer token and manager ID across connections — just swap the customer ID.

## Verify the Connection

* Connection status shows **Active**
* Campaigns list populates within a few minutes
* Spend and performance metrics match what's in the Google Ads UI (small differences are expected due to timing)

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Developer token not approved' or 'Developer token not on allowlist'">
    Your token is either pending Google review or is at **Test access** level and trying to query a non-test account. Check status in **API Center**. Request an upgrade to **Basic** or **Standard** access for production accounts.
  </Accordion>

  <Accordion title="'Customer ID not found' or invalid">
    Make sure the customer ID is the 10-digit number from the Google Ads UI, **without** dashes. Also confirm the account is still active in Google Ads — closed accounts won't respond to API calls.
  </Accordion>

  <Accordion title="'Access denied' when using an MCC">
    The **Manager ID** field must be the MCC's own customer ID, and the authorized Google user must be a member of the MCC. Don't put a sub-account's customer ID here — that goes in the **Customer ID** field.
  </Accordion>

  <Accordion title="Test account returns no data">
    Test developer tokens only work against Google Ads test accounts, which have no real spend. Create a test account via the MCC or request Basic/Standard token access to use real accounts.
  </Accordion>

  <Accordion title="Rate limits or quota errors">
    Google Ads API has per-developer-token quotas. If you're consistently hitting them, reduce sync frequency, batch requests, or contact Google via API Center to request a quota increase.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Connect Meta Ads" icon="facebook" href="/how-tos/connect-meta-ads">
    Add Facebook and Instagram advertising
  </Card>

  <Card title="Connect TikTok Ads" icon="tiktok" href="/how-tos/connect-tiktok-ads">
    Bring TikTok campaigns into the same dashboard
  </Card>
</CardGroup>