# SyncMetrics — Chatbot Knowledge Base

*Comprehensive content for customer-facing chatbot. Paste into Intercom / Crisp / Tidio / custom AI bot.*

---

## What is SyncMetrics?

SyncMetrics is a performance-marketing analytics platform that connects your ad accounts (Meta Ads, TikTok Ads, Google Ads) and your Shopify store to **AI assistants like Claude** and **Data Studio**. Instead of logging into 4 different dashboards to understand your performance, you ask Claude in plain English — *"What's my real ROAS last month?"* — and SyncMetrics pulls the live data from every platform and gives you the answer.

The website is **[syncmetrics.io](https://syncmetrics.io)**. Sign in with Google to get started.

---

## What problem does it solve?

- **Fragmented reporting:** Most brands run Meta + TikTok + Google + Shopify. Each platform reports its own ROAS, but they all claim credit for the same orders, so combined claimed ROAS is inflated.
- **Slow analysis:** Pulling a cross-platform report manually takes 30+ minutes of spreadsheet wrangling.
- **Data Studio gaps:** Data Studio has connectors for some platforms, but they cost $30–80/mo each and don't talk to each other.
- **No AI integration:** Standard dashboards can't answer "why did my CPA spike last week?"

SyncMetrics solves all four with a single subscription.

---

## Who is it for?

- **E-commerce brand owners** running ads on Meta / TikTok / Google with Shopify
- **Performance marketers** managing multiple ad accounts
- **Marketing agencies** managing multiple clients
- **Founders and freelancers** who want fast, accurate reporting without paying for Supermetrics ($79/mo) or Triple Whale ($129+/mo)

---

## What integrations are live?

| Platform | Status | What we pull |
|----------|--------|--------------|
| **Meta Ads** (Facebook/Instagram) | ✅ Live | Campaigns, ad sets, ads, creative thumbnails, video metrics, demographic breakdowns |
| **TikTok Ads** | ✅ Live | Campaigns, ad groups, ads, Spark Ads with TikTok post URLs, video quartile completion |
| **Google Ads** | ✅ Live | Search/Display/Video/YouTube campaigns, Performance Max, Demand Gen, ad groups, keywords, video TrueView metrics |
| **Google Sheets** | ✅ Live | Any sheet the user pastes into the dashboard — read AND write (append rows, update cells, create tabs) |
| **Shopify** | ✅ Live | Orders, revenue, products, customers (LTV), checkout funnel, traffic attribution |
| **Google Analytics 4** | 🟡 Coming soon | — |
| **LinkedIn Ads, Pinterest Ads, Snapchat Ads** | 🟡 Roadmap | — |

All connections are **read-only**. SyncMetrics never creates, edits, pauses, or deletes anything on your behalf.

---

## How does it work?

Three ways to use SyncMetrics once connected:

### 1. Ask Claude AI directly (MCP)
SyncMetrics provides each user a personal **MCP URL**. Paste it into Claude (Settings → Connectors) and Claude can query your live ad + Shopify data in any conversation. Ask things like:
- *"What's my True ROAS across all platforms last 30 days?"*
- *"Which Meta ad set has the worst creative fatigue?"*
- *"How many unique TikTok viewers did I reach last quarter?"*

### 2. Data Studio dashboards
SyncMetrics is a Data Studio community connector. Open Data Studio → Create → Data source → search "SyncMetrics" — pick Meta, TikTok, or Shopify — build any dashboard.

### 3. Marketing Recipes
Inside the SyncMetrics dashboard there's a **Recipes** tab with 30+ pre-built prompts (True ROAS, Wasted Spend Finder, Creative Fatigue Detection, Weekly Flash Report). One-click sends the prompt to Claude with your data attached.

---

## Plans & pricing

| Plan | Price | Ad accounts (per platform) | Best for |
|------|-------|---------------------------|----------|
| **Free / Starter** | $0 | 1 | Trying it out |
| **Growth** | $99/mo | 5 | Single-brand e-commerce |
| **Pro** | $249/mo | 5 + priority support | Power users |
| **Agency** | $499/mo | Unlimited + white-label | Marketing agencies |

**Founder pricing:** First customers can lock in **$49/mo for life** on the Growth plan. Email support@syncmetrics.io to claim.

**Annual:** 25% discount when billed annually.

All plans include:
- Unlimited Claude AI queries
- Full Data Studio connector access
- All 30+ recipe templates
- Cross-platform True ROAS report
- Email support

---

## Security & privacy

- **OAuth tokens encrypted at rest** with AES-256 (Fernet). The server-side database (Supabase) has row-level security so no user can see another user's data.
- **HTTPS everywhere.** All requests use TLS.
- **No ad data permanently stored.** Order data, ad metrics, video metrics — all fetched live on every request and passed straight to you or your connected tool. Nothing is cached in our database.
- **Read-only scopes only.** We request the minimum permissions needed for analytics:
  - Meta: `ads_read`
  - TikTok: read-only ads + report scopes
  - Google: `adwords` (read-only use)
  - Shopify: 13 `read_*` scopes, no write
- **Revoke anytime.** Disconnect any platform from your SyncMetrics dashboard. The encrypted token is deleted from our database immediately. You can also revoke from the platform itself (Facebook Settings → Apps, TikTok Developer Settings, Google Account Permissions, Shopify Apps → Uninstall).
- **GDPR & CCPA compliant.** Full data deletion request at support@syncmetrics.io.
- **We never sell your data, never use it for advertising, never train AI models on it.**

Privacy policy: [syncmetrics.io/privacy](https://syncmetrics.io/privacy)
Terms: [syncmetrics.io/terms](https://syncmetrics.io/terms)

---

## Getting started (5 minutes)

1. Go to **[syncmetrics.io](https://syncmetrics.io)** → click **Get Started**
2. **Sign in with Google** (we use Google for sign-in; we don't use Facebook Login)
3. On the dashboard, click **+ Connect** on the platform you want first (Meta / TikTok / Google / Shopify)
4. Approve the OAuth permissions (or paste Shopify Custom App token)
5. Choose your **default ad account** if you have multiple
6. Pick how you want to use it:
   - **Claude AI** → copy your MCP URL from the dashboard → paste into Claude → start asking questions
   - **Data Studio** → open Data Studio → Data source → search SyncMetrics
   - **Recipes** → dashboard → Recipes tab → click "Run with Claude"

---

## Connecting Meta Ads (Facebook + Instagram)

1. Dashboard → Meta Ads card → **+ Connect with Meta**
2. Facebook opens an OAuth window
3. Grant `ads_read` permission (read-only ad data)
4. Redirected back to SyncMetrics → done

We need access to the ad accounts you've selected during OAuth. If you manage multiple Business Manager accounts, you can select multiple at the consent screen.

---

## Connecting TikTok Ads

1. Dashboard → TikTok Ads card → **+ Connect with TikTok**
2. TikTok opens an OAuth window
3. Choose which TikTok Ads accounts to authorize
4. Redirected back to SyncMetrics → done

If TikTok recently approved new scopes for your app, **disconnect and reconnect** to get a fresh token that includes the new scopes. Existing tokens don't auto-upgrade.

---

## Connecting Google Ads

1. Dashboard → Google Ads card → **+ Connect with Google**
2. Google opens an OAuth window
3. Grant the read-only Google Ads scope
4. Pick which Google Ads account to use as default
5. If you manage accounts through an MCC (manager account), SyncMetrics handles the MCC linking automatically — no extra setup

**Requirements:**
- The Google account you OAuth with must have access to the Google Ads account(s) you want to query
- The Google Ads account must have an active developer-token relationship (SyncMetrics provides this automatically)

---

## Connecting Google Sheets

Google Sheets uses its own OAuth flow, separate from Google Ads:

1. Dashboard → Google Sheets card → **+ Connect Google Sheets**
2. Sign in with the Google account that owns (or has shared access to) the sheets you want to expose. Grant the **"View your Google Sheets"** scope on the consent screen.
3. After redirect, paste a sheet URL into the input below the card and click **Add sheet**. Repeat for any other sheets you want Claude to read.
4. Done. Ask Claude *"What sheets do I have?"* and it'll list them via the `list_my_google_sheets` MCP tool.

**Important:** Only sheets you explicitly add appear in Claude's view — even with the OAuth token, Claude can't read sheets you haven't pasted into the dashboard. This is subscription-enforced on the server side.

**Plan limits:** Free / Starter = 1 sheet, Growth = 5, Pro = 15, Agency = 999.

**What Claude can do with a connected sheet:**

Read:
- *"List the tabs and headers of the campaign log sheet"* → `get_google_sheet_metadata`
- *"Show me the first 50 rows of the May tab"* → `read_google_sheet_range`
- *"Find all rows where account_id is 1230968848"* → `search_google_sheet`
- *"Sum the cost column for May 2026"* → reads the range and sums client-side

Write:
- *"Append yesterday's totals to the campaign log"* → `append_google_sheet_rows`
- *"Fix the cost in row 47 column D — should be 125, not 100"* → `update_google_sheet_range`
- *"Create a new tab called June 2026 analysis"* → `create_google_sheet_tab`

**What Claude CANNOT do:**
- Read other people's sheets you don't own
- Auto-discover all your sheets — you have to paste each one explicitly
- Delete tabs or rows (only adding/updating supported in v1)

**If a write tool errors with "Your Google Sheets connection was authorized with read-only permission":** your OAuth token was issued before write support was added. Disconnect Google Sheets in the dashboard, then click Connect again — the new authorization will grant write access.

---

## Connecting Shopify

Shopify uses a slightly different flow because of how Shopify's app permissions work:

1. Dashboard → Shopify card → **+ Connect Shopify**
2. Follow the step-by-step guide at **[syncmetrics.io/docs/shopify](https://syncmetrics.io/docs/shopify)**
3. You'll create a "Custom App" inside your Shopify admin with these 13 read-only scopes:
   - read_orders, read_all_orders, read_products, read_customers, read_inventory, read_locations, read_analytics, read_reports, read_marketing_events, read_fulfillments, read_returns, read_discounts, read_price_rules
4. Reveal the Admin API token → paste it + your shop domain into the SyncMetrics connection modal → done

**Why no one-click OAuth for Shopify?** Shopify discontinued one-click Custom Apps in January 2026 for new merchants. We're in the process of releasing a Public App (one-click) — current method works for all merchants meanwhile.

---

## Multi-account support

Free plans connect 1 ad account per platform. **Paid plans (Growth / Pro / Agency) can connect multiple accounts.**

On the dashboard, each platform's card shows your connected accounts as a list. You can:
- ⭐ Mark one account as the **default** (used by recipes and Data Studio)
- ❌ Remove an account
- ➕ Add another (up to plan limit)

When you have multiple accounts connected, you can ask Claude *"compare account X vs account Y"* — Claude pulls both and reports.

---

## One-prompt reports, custom metrics & discovery

Every ad platform now has THREE layers of reporting tools:

**1. Account overviews — one prompt, full report.** Say *"Give me a Meta report for May"* and Claude calls `get_meta_account_overview` once. It returns period totals, the previous period's totals with % change per metric, a daily trend, the top 10 campaigns, and (Meta) age/gender splits — everything needed for an executive summary in a single call. Same for `get_tiktok_account_overview` and `get_google_account_overview` (which adds channel-type and device splits).

**2. Custom reports — any metric × any dimension.** When you need something specific:
- *"Unique CTR by age and gender on Meta"* → `get_meta_custom_report`
- *"TikTok spend by country and placement"* → `get_tiktok_custom_report` (audience dimensions!)
- *"Top search terms last month"* / *"keyword quality scores"* / *"spend by device and day of week"* → `get_google_custom_report` (keywords, search terms, locations, demographics, time segments)

**3. Discovery — what can I ask for?** `list_meta_available_metrics`, `list_tiktok_available_metrics`, `list_google_available_metrics` return the full metric/dimension catalogs with definitions. Ask Claude *"what TikTok metrics can you pull?"* and it lists them.

Coverage notes:
- Meta: ~45 metrics incl. unique/link/outbound clicks, Meta-reported ROAS, quality rankings (ad level), brand recall; 10 breakdowns incl. hourly, DMA, device platform; combos like age+gender supported.
- TikTok: ~50 metrics incl. engagement (likes, shares, follows, profile visits), results, web purchases + ROAS; audience dimensions (age, gender, country, province, OS, placement, language, network) the standard tools can't do.
- Google: 27 metrics × 8 resources (campaign, ad group, ad, keyword, search term, location, age, gender) × 7 segments (date, device, network, day-of-week, hour, week, month) — all GAQL built and validated server-side.

---

## How does True ROAS work?

The flagship recipe. Compares **total ad spend across all platforms** to **actual Shopify revenue**:

```
True ROAS = Shopify Net Revenue ÷ (Meta Spend + TikTok Spend + Google Spend)
```

Why this matters: Each platform tracks its own attributed conversions, so the sum of platform-claimed ROAS double-counts orders. Meta says it drove $10K, TikTok says $8K, Google says $7K — for $5K total spend, that's "claimed ROAS 5x" — but you only made $15K in Shopify. **True ROAS = 3x.** SyncMetrics shows you both numbers side-by-side so you can spot platform over-reporting.

---

## Marketing Recipes (30+ pre-built)

Click any recipe → opens Claude with a pre-filled prompt that uses your live data. Categories:

**Meta:** Weekly Summary, Wasted Spend Finder, Creative Fatigue Detection, CPA Diagnostics, Audience Overlap, Geo Performance, Day & Hour Performance

**TikTok:** Creative Performance, Weekly Summary, Account Totals

**Google:** Weekly Summary, Wasted Spend, CPA Diagnostics, Channel Type Performance, Ad Group Deep Dive, Conversion Trend, Demand Gen Campaign Overview, Demand Gen Ad Group Deep Dive, Performance Max reporting

**Shopify:** Revenue Snapshot, Checkout Funnel & Lost Revenue, Customer LTV & Repeat Rate, Top Products & Slow Movers

**Cross-platform:** True ROAS, Three-Platform Budget Reallocation, Weekly Flash Report, Channel × LTV Matrix, Product × Channel Fit, Meta vs TikTok Comparison

---

## Common questions

**Can SyncMetrics create or edit my ads?**
No. Strictly read-only across every platform. We can't create campaigns, change budgets, pause ads, or modify anything. By design.

**Do I need a Claude subscription?**
You need a Claude account (free or paid) to use the MCP integration. The free Claude tier works fine.

**Can I use SyncMetrics without Claude?**
Yes. The Data Studio connectors and dashboard work standalone. Claude integration is optional.

**Will my MCP URL expire?**
No, it's permanent — but you can regenerate it from the dashboard at any time (the old URL stops working immediately).

**Do you support multi-currency?**
Yes. We surface each ad account's native currency. We don't convert — values are reported as the platform returns them. Multi-currency aggregation is on the roadmap.

**How fresh is the data?**
Live. Every query hits the platform API in real-time. No batch syncs, no waiting for a nightly job.

**Refund policy?**
14-day money-back guarantee on monthly plans. Annual plans: prorated refund within 30 days.

**Cancel anytime?**
Yes. Cancel from the dashboard. No commitment.

---

## Which MCP tool returns ad URLs?

Creative URLs (post URLs, landing pages, thumbnails, headlines) live at the ad level on every platform, but the SyncMetrics tool that surfaces them is platform-specific.

### TikTok — `get_tiktok_ad_insights`
Always returns `post_url`, `thumbnail_url`, `landing_page_url`, `call_to_action`, and `identity_id`. No flag to set; URLs come back by default because the TikTok API includes them cheaply.

### Meta — two valid options
- **Default fast path**: `get_meta_ad_insights` returns numeric metrics only — fastest and cheapest.
- **Opt-in enrichment**: pass `include_creative=true` to `get_meta_ad_insights` and it ALSO returns `post_url`, `thumbnail_url`, `body`, `page_name`, and `object_story_id`. Same data as `get_meta_creative_insights` would return, in the same response.
- **Always-enriched alias**: `get_meta_creative_insights` is exactly that — creative-enriched ad insights, always on.

Pick whichever matches the user's intent:
- Just numeric metrics? → `get_meta_ad_insights` (no flag).
- Numeric metrics + URLs? → either `get_meta_ad_insights` with `include_creative=true`, OR `get_meta_creative_insights`. Same outcome.

> ⚠️ The enrichment adds extra Meta API calls (one batch for creatives, one batch for page names). It's off by default for a reason — only flip it on when the user actually asks for creative content or landing URLs.

### Google Ads — two valid options (parity with Meta)
- **Default fast path**: `get_google_ads_insights` returns ad-group rollups only — no creative content. Fastest.
- **Opt-in enrichment**: `get_google_ads_insights` with `include_creative=true` returns the same ad-group rollups PLUS each ad-group's top-spending ad attached as a `top_ad` field (`final_urls`, `display_url`, `headlines`, `image_url`, `youtube_video_url`, `ad_type`). One extra Google Ads query.
- **Full ad-level drill-down**: `get_google_ads_creatives` returns one row per ad with `final_urls`, `display_url`, `headlines`, `descriptions`, `image_url`, `youtube_video_id`, `youtube_video_url`, plus per-ad metrics. Use when the user wants to compare individual ads, not ad groups.

Pick whichever matches the user's intent:
- Just numeric ad-group metrics? → `get_google_ads_insights` (no flag).
- Ad-group rollup + the dominant ad's URL? → `get_google_ads_insights` with `include_creative=true`.
- Compare individual ads with all their creative data? → `get_google_ads_creatives`.

> ⚠️ Same trade-off as Meta: the enrichment costs an extra Google Ads API call. Don't flip `include_creative` on unless the user actually asks for ad URLs / creative content.

### Example questions and the tool that should fire
- *"Show me the top 10 TikTok ad creatives by spend last week, with their post URLs"* → `get_tiktok_ad_insights`
- *"Top Meta ads last month by ROAS — give me the post URL of each"* → `get_meta_ad_insights` with `include_creative=true`
- *"Just the spend numbers for our Meta ads, no URLs"* → `get_meta_ad_insights` (default, no flag)
- *"Show me top 10 Google ad-groups by cost with each one's main landing URL"* → `get_google_ads_insights` with `include_creative=true`
- *"Just give me the cost per Google ad-group — I don't care about creatives"* → `get_google_ads_insights` (default, no flag)
- *"What's the landing-page URL for our highest-spending Google ad?"* → `get_google_ads_creatives`

---

## Troubleshooting

**"Continue with Google" doesn't do anything when I click it**
Hard-refresh the page (Ctrl/Cmd+Shift+R). If it still fails, try an incognito window or a different browser.

**My first query takes 30+ seconds, but the next ones are fast**
That's a Render free-tier cold start — the server sleeps after 15 min of inactivity. Subsequent queries are fast. Upgrade to a paid plan to eliminate cold starts entirely (server stays warm).

**Data Studio shows "Failed to load accounts"**
Hard-refresh in Data Studio. If still failing, disconnect Meta/TikTok/Google on the SyncMetrics dashboard and reconnect — this issues a fresh token and clears any cache.

**Google Ads says "USER_PERMISSION_DENIED"**
The Google account you OAuth'd with doesn't have access to that Google Ads customer. Re-check that your Google account has the right access level (Standard or Admin) in Google Ads → Tools → Access & Security.

**TikTok says "access token lacks the required scope"**
Your TikTok token was issued before a recent scope approval. Disconnect TikTok in the dashboard, then reconnect — the new token will include all currently-approved scopes.

**Claude says it can't find a video field / metric**
The MCP tool descriptions list every field returned. If Claude says a field is missing, ask it to **call the tool first and inspect the actual response keys** — sometimes Claude relies on stale tool descriptions cached from an earlier session. Reconnecting the MCP in Claude refreshes the tool list.

---

## Contact & support

- **Email:** support@syncmetrics.io
- **Onboarding help:** Reply to any setup email — we'll get on a call
- **Bug reports:** support@syncmetrics.io with steps to reproduce
- **Feature requests:** support@syncmetrics.io with use case
- **Sales / agency partnerships:** support@syncmetrics.io

We respond within 24 hours on weekdays.

---

## Helpful links

- Dashboard: [syncmetrics.io/dashboard](https://syncmetrics.io/dashboard)
- Shopify connection guide: [syncmetrics.io/docs/shopify](https://syncmetrics.io/docs/shopify)
- Privacy policy: [syncmetrics.io/privacy](https://syncmetrics.io/privacy)
- Terms of service: [syncmetrics.io/terms](https://syncmetrics.io/terms)