For end users

Google Ads integration

Connects Pectus to a Google Ads account so it can pull daily campaign metrics, change history, and conversion value.

Approval delay: developer-token approval takes 1–3 business days for Basic access. Test access is instant but only works against test accounts.

Env vars set by this flow:

GOOGLE_ADS_DEVELOPER_TOKEN=
GOOGLE_ADS_CLIENT_ID=
GOOGLE_ADS_CLIENT_SECRET=
GOOGLE_ADS_REFRESH_TOKEN=
GOOGLE_ADS_CUSTOMER_ID=
GOOGLE_ADS_LOGIN_CUSTOMER_ID=

The OAuth client ID and secret can be reused from the one created in the main install flow for Search Console / Analytics.

1. Get a developer token

The developer token is issued at the Manager (MCC) account level. If the account is a regular Ads account, switch to the manager that owns it via the top-right account picker.

Go to https://ads.google.com/aw/apicenter
Apply for a developer token
Choose Basic access unless you only have test accounts. Approval takes 1–3 business days.

Save the token to .env.local as GOOGLE_ADS_DEVELOPER_TOKEN.

2. Enable the Google Ads API in your GCP project

Direct link (substitute your project):

https://console.cloud.google.com/apis/library/googleads.googleapis.com

Click Enable. Wait ~30 seconds for the change to propagate.

Cloud Console → APIs & Services → OAuth consent screen → Audience
Scroll to Scopes, click Add or remove scopes
The Ads scope often isn’t in the picker. Scroll to the bottom and use Manually add scopes — paste:
```
https://www.googleapis.com/auth/adwords
```
Add to table → Update → Save

Add yourself as a test user under Test users if you aren’t already (consent screens in Testing mode reject non-test users).

4. Add OAuth Playground as a redirect URI

Cloud Console → APIs & Services → Credentials
Open the OAuth 2.0 Client ID for your app
Under Authorized redirect URIs, click Add URI
Paste: https://developers.google.com/oauthplayground
Save. Wait ~30 seconds.

5. Generate a refresh token via OAuth Playground

Open https://developers.google.com/oauthplayground
Click the gear icon (top right). Tick Use your own OAuth credentials and paste the OAuth client ID + secret
In Step 1 left panel, scroll to Input your own scopes and paste https://www.googleapis.com/auth/adwords
Click Authorize APIs. Sign in as the Google user with access to the Ads manager account
Step 2 → click Exchange authorization code for tokens
Copy the value next to Refresh token (starts with 1//..., NOT ya29...)

Save it to .env.local as GOOGLE_ADS_REFRESH_TOKEN.

The refresh token doesn’t expire under normal use, so this is a one-time step.

6. Get the Customer IDs

In the Ads UI, the 10-digit Customer ID is shown in the header next to the account name.

GOOGLE_ADS_CUSTOMER_ID = the actual ad account you want data from
GOOGLE_ADS_LOGIN_CUSTOMER_ID = the Manager (MCC) ID, only if the ad account sits under one

Strip the dashes when pasting into env vars: 123-456-7890 → 1234567890.

7. Verify

Once your credentials are saved, open the per-app page in the CMS at /apps/google-ads and click Test connection. Pectus runs a small probe call against the API and surfaces the response inline.

Common errors

UNIMPLEMENTED: GRPC target method can't be resolved — the Google Ads API isn’t enabled in the GCP project. Re-check step 2.

Access denied: 403 during OAuth Playground sign-in — the Google user you’re signing in as isn’t on the OAuth consent screen’s Test users list. Add them under OAuth consent screen → Audience → Test users.

Library version mismatch — Google sunsets old Ads API versions after ~12 months. If you see “GRPC target method can’t be resolved” after the API is enabled, your google-ads-api npm package is too old. npm install google-ads-api@latest.

Manager-account requirement — developer tokens are issued to manager accounts, not regular ad accounts. The token works for every account linked under the manager. If a customer Pectus is being installed for doesn’t have a manager account, they’ll need to create one (free) at https://ads.google.com/home/tools/manager-accounts/.