How Bestwearly talks to Google Ads

Overview

Bestwearly is a thin operator-facing layer on top of the Google Ads API. We don't build a parallel system — every operation is a direct, authenticated call against the official googleads.googleapis.com endpoint for a specific service. This page documents what we call and why.

1. Authentication

The suite runs under a single OAuth 2.0 client in offline mode:

# Authorization URL (standard Google OAuth 2.0)
https://accounts.google.com/o/oauth2/v2/auth
  ?client_id=<OAUTH_CLIENT_ID>
  &redirect_uri=https://app.bestwearly.com/auth/callback
  &response_type=code
  &scope=https://www.googleapis.com/auth/adwords
  &access_type=offline
  &prompt=consent
      

Tokens we receive:

Token	TTL	Use
access_token	~60 min	Bearer token for every API request
refresh_token	Until revoked	Stored encrypted at rest; renewed automatically

2. login-customer-id

Every call from Bestwearly sets login-customer-id to the operator's MCC ID. This is what tells the Google Ads API which developer token is being exercised, and which accounts under that MCC are in scope.

# Required header on every call
login-customer-id: 5066360168
developer-token: <DEVELOPER_TOKEN>
authorization: Bearer <ACCESS_TOKEN>
      

3. API services we touch

Service	Use
GoogleAdsService	Reporting queries via search() and searchStream(). The primary data source.
CampaignBudgetService	Daily budget updates across all accounts, applied via mutate().
CampaignService	Create, pause, resume campaigns at scale.
AdGroupService	Ad group lifecycle operations.
AdGroupAdService	Ad copy creation, A/B rotation, asset lifecycle.
AdGroupCriterionService	Keyword add / remove / pause; negative keyword sync.
KeywordService	Bulk negative-keyword operations across accounts.
AdGroupBidModifierService	Hour-of-day and device bid modifiers, applied per schedule.
ConversionUploadService	Server-side conversion uploads (phase 2).

4. Operational profile

Metric	Value
Daily API call volume (avg)	~250 ops/day
Peak call volume (batch windows)	~1,000 ops/day
Polling cadence	Hourly
Batch operations window	Sundays 02:00 UTC
Refresh-token rotation	On expiry (≤ 60 days)
Token storage	AES-256-GCM at rest

5. Error handling

We respect Google's recommended exponential backoff for any RESOURCE_EXHAUSTED or UNAVAILABLE error, and every retry is logged with the request ID returned in the request-id response header.

6. GAQL examples

The reporting queries look like this:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.cost_micros,
  metrics.conversions,
  metrics.ctr
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC
LIMIT 50