@wix/agent-skills 1.15.1 → 1.16.0

package/skills/wix-manage/references/google-ads/create-performance-max-campaign.md

@@ -0,0 +1,212 @@
+---
+name: "Create and Launch a Performance Max Campaign"
+description: "Creates and launches a Google Ads Performance Max (PMAX) campaign for a Wix site — a goal-based campaign that runs across all Google channels (Search, Display, YouTube, Gmail, Discover, Maps) from an asset group of headlines, descriptions, images, and (for PMAX Leads) search-theme signals. Covers generating AI text and image assets, generating search themes, getting a Google budget recommendation, assembling the asset group with the required minimum assets, choosing PERFORMANCE_MAX vs PERFORMANCE_MAX_LEADS (leads: phone/form goals, negative keywords, 28-day learning) vs retail/Shopping (Merchant Center feed), creating in PAUSED, and launching. Use for 'create a Performance Max campaign', 'PMAX', 'run ads across all of Google', 'lead-gen Google campaign', or 'Google Shopping ads'. Requires an existing Google Ads account. REST base https://www.wixapis.com/google-ads/v1."
+---
+# RECIPE: Create and Launch a Performance Max Campaign
+
+A **Performance Max (PMAX)** campaign runs across every Google channel from a single **asset group** — a bundle of headlines, descriptions, images, and (optionally) videos that Google mixes into ads. There are three flavors, set by `campaignType`:
+
+- **`PERFORMANCE_MAX`** — general multi-channel campaign.
+- **`PERFORMANCE_MAX_LEADS`** — lead-gen variant (phone/form conversions, search-theme signals, negative keywords, a ~28-day learning phase). **Requires** at least one asset group with headlines, descriptions, and images; assets are validated synchronously, so bad assets fail the create call immediately.
+- **Retail / Shopping** — a `PERFORMANCE_MAX` campaign linked to a Google Merchant Center feed (set `merchantCenterAccountId` on the account first — see [install-and-create-account](install-and-create-account.md) — and use `feedLabel`). Retail campaigns don't require a hand-built asset group.
+
+Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. The bidding strategy is server-enforced to `MAXIMIZE_CONVERSIONS` — never set it yourself.
+
+> **Launching spends real money.** Present the assembled asset group and budget and get explicit approval before the Launch call (STEP 5). Create in `PAUSED` first — nothing serves until Launch.
+
+**Prerequisite:** a Google Ads account (`ACCOUNT_NOT_FOUND` → run [install-and-create-account](install-and-create-account.md)). You need `account.id` as `campaign.accountId`.
+
+**Flow:** STEP 1 text assets → STEP 2 image assets → STEP 3 (leads) search themes → STEP 4 budget recommendation → assemble & create PAUSED → **show & approve** → STEP 5 launch.
+
+---
+
+## STEP 1: Generate text assets (headlines & descriptions)
+
+`suggestionInfo.landingPageUrl` and `textSuggestionInfo.languageCode` are both required. Response may take up to 60s.
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/text-asset-suggestions' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{
+    "suggestionInfo": { "landingPageUrl": "https://www.example.com", "assetTypes": ["HEADLINE", "DESCRIPTION"] },
+    "textSuggestionInfo": { "languageCode": "en" }
+  }'
+```
+
+```json
+{ "assetSuggestions": [
+  { "assetType": "HEADLINE", "headlineAsset": { "text": "Fresh Baked Every Morning" } },
+  { "assetType": "HEADLINE", "headlineAsset": { "text": "Award-Winning Pastries" } },
+  { "assetType": "DESCRIPTION", "descriptionAsset": { "text": "Visit us for artisan breads, custom cakes, and more." } }
+] }
+```
+
+## STEP 2: Generate image assets
+
+Images are generated with AI and **automatically uploaded to the site's Wix Media Manager** — the returned `url` is a `static.wixstatic.com` link you can use directly in the asset group. `suggestionInfo.landingPageUrl` is required.
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/image-asset-suggestions' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{ "suggestionInfo": { "landingPageUrl": "https://www.example.com", "assetTypes": ["MARKETING_IMAGE", "SQUARE_MARKETING_IMAGE"] } }'
+```
+
+```json
+{ "assetSuggestions": [
+  { "assetType": "MARKETING_IMAGE", "imageAsset": { "name": "storefront-banner", "url": "https://static.wixstatic.com/media/abc123.jpg" } },
+  { "assetType": "SQUARE_MARKETING_IMAGE", "imageAsset": { "name": "product-square", "url": "https://static.wixstatic.com/media/def456.jpg" } }
+] }
+```
+
+## STEP 3 (PMAX Leads only): Generate search themes
+
+Search themes are the targeting signals for a leads campaign's asset group. `textSuggestionInfo.languageCode` is required.
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/search-theme-suggestions' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{ "landingPageUrl": "https://www.example.com", "textSuggestionInfo": { "languageCode": "en" } }'
+```
+
+```json
+{ "searchThemes": ["artisan bakery", "custom birthday cakes", "fresh bread delivery", "gluten free pastries", "wedding cake shop"] }
+```
+
+Each string becomes a `{ "searchTheme": { "text": "…" } }` signal in the asset group (max 25).
+
+## STEP 4: Get a budget recommendation
+
+PMAX uses **Generate Budget Recommendation** (not the Smart-campaign budget-suggestions endpoint). `campaignType`, `assetGroupInfo` (with a `finalUrl`), and `currency` are required.
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/budget-recommendation' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{
+    "campaignType": "PERFORMANCE_MAX",
+    "assetGroupInfo": [ {
+      "finalUrl": "https://www.example.com",
+      "headlines": ["Fresh Baked Every Morning", "Award-Winning Pastries"],
+      "descriptions": ["Artisan breads and custom cakes baked fresh daily."]
+    } ],
+    "currency": "USD",
+    "countryCodes": ["US"],
+    "languageCodes": ["en"]
+  }'
+```
+
+```json
+{ "budgetRecommendation": {
+  "recommendedBudgetAmountMicros": "15000000",
+  "budgetOptions": [
+    { "budgetAmountMicros": "8000000",  "impact": { "potentialMetrics": { "impressions": 1200, "clicks": 35, "conversions": 2 } } },
+    { "budgetAmountMicros": "15000000", "impact": { "potentialMetrics": { "impressions": 2800, "clicks": 78, "conversions": 5 } } }
+  ]
+} }
+```
+
+Use `recommendedBudgetAmountMicros` as `budget.amountMicros`, or present the `budgetOptions` with their projected impact and let the user pick. `budgetRecommendation` is absent when Google has too little data — fall back to a manual budget within `GET /v1/campaign/daily-budget-boundaries`.
+
+---
+
+## Assemble & create the campaign (in PAUSED)
+
+An **asset group** lives at `performanceMaxCampaign.assetGroups[]`. Its creative assets go under `assetGroupAssets.assets[]` — each asset sets **exactly one** payload field plus its `assetFieldType`. For a PMAX Leads asset group, meet Google's minimums or the create call fails with `NOT_ENOUGH_ASSETS`:
+
+| Asset | Payload field | `assetFieldType` | Count | Max chars |
+| --- | --- | --- | --- | --- |
+| Short headline | `headlineAsset.text` | `HEADLINE` | 3–15 | 30 |
+| Long headline | `longHeadlineAsset.text` | `LONG_HEADLINE` | exactly 1 | 90 |
+| Description | `descriptionAsset.text` | `DESCRIPTION` | 2–4 | 90 |
+| Business name | `businessNameAsset.text` | `BUSINESS_NAME` | exactly 1 | 25 |
+| Landscape image (1.91:1) | `imageAsset.{name,url}` | `MARKETING_IMAGE` | ≥1 | — |
+| Square image (1:1) | `imageAsset.{name,url}` | `SQUARE_MARKETING_IMAGE` | ≥1 | — |
+| Logo (1:1) | `imageAsset.{name,url}` | `LOGO` | ≥1 | — |
+| CTA button | `callToActionSelectionAsset.callToAction` | `CALL_TO_ACTION_SELECTION` | optional | `LEARN_MORE` \| `SHOP_NOW` \| `SIGN_UP` \| `CONTACT_US` |
+| YouTube video | `youtubeVideoAsset.{title,id}` | `YOUTUBE_VIDEO` | optional (1–5) | 11-char video id |
+
+Image `url` must be a Wix Media Manager URL (`static.wixstatic.com`) — the STEP 2 generated images already are; for other images, upload via the Media Manager first (see [Upload Media to Wix](../media/upload-media-to-wix.md)). Search themes go under `assetGroupSignals.signals[]` (PMAX Leads).
+
+**Create a PMAX Leads campaign** (status required; create `PAUSED`):
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/campaigns' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{
+    "campaign": {
+      "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "campaignType": "PERFORMANCE_MAX_LEADS",
+      "status": "PAUSED",
+      "name": "Summer Lead-Gen PMAX",
+      "budget": { "amountMicros": "15000000" },
+      "locations": [
+        { "location": { "geoTargetConstant": "geoTargetConstants/1023191" }, "displayName": "New York, United States" }
+      ],
+      "performanceMaxCampaign": {
+        "url": "https://www.example.com",
+        "languages": [ { "languageCode": "en" } ],
+        "assetGroups": [ {
+          "assetGroupAssets": { "assets": [
+            { "headlineAsset":     { "text": "Fresh Baked Every Morning" }, "assetFieldType": "HEADLINE" },
+            { "headlineAsset":     { "text": "Award-Winning Pastries" },    "assetFieldType": "HEADLINE" },
+            { "headlineAsset":     { "text": "Order Custom Cakes Today" },  "assetFieldType": "HEADLINE" },
+            { "longHeadlineAsset": { "text": "Artisan breads and custom cakes baked fresh every morning" }, "assetFieldType": "LONG_HEADLINE" },
+            { "descriptionAsset":  { "text": "Award-winning pastries made fresh daily." }, "assetFieldType": "DESCRIPTION" },
+            { "descriptionAsset":  { "text": "Custom cakes for every occasion. Order online." }, "assetFieldType": "DESCRIPTION" },
+            { "businessNameAsset": { "text": "Sunrise Bakery" }, "assetFieldType": "BUSINESS_NAME" },
+            { "imageAsset": { "name": "storefront-banner", "url": "https://static.wixstatic.com/media/abc123.jpg" }, "assetFieldType": "MARKETING_IMAGE" },
+            { "imageAsset": { "name": "product-square",    "url": "https://static.wixstatic.com/media/def456.jpg" }, "assetFieldType": "SQUARE_MARKETING_IMAGE" },
+            { "callToActionSelectionAsset": { "callToAction": "SHOP_NOW" }, "assetFieldType": "CALL_TO_ACTION_SELECTION" }
+          ] },
+          "assetGroupSignals": { "signals": [
+            { "searchTheme": { "text": "artisan bakery" } },
+            { "searchTheme": { "text": "custom birthday cakes" } }
+          ] }
+        } ]
+      }
+    }
+  }'
+```
+
+For a **general `PERFORMANCE_MAX`** campaign, use `campaignType: "PERFORMANCE_MAX"` (the `assetGroupSignals` are Leads-only). For **retail/Shopping**, link a Merchant Center account on the account first and set `performanceMaxCampaign.feedLabel`; a retail campaign can serve from the product feed without a hand-built asset group.
+
+Save the returned `campaign.id` and `resourceName`. `status` is read-only and syncs from Google — a PMAX Leads campaign shows `LEARNING` for ~28 days after launch.
+
+**Now show the user the asset group** (headlines, descriptions, images) and the daily budget, and get explicit approval.
+
+---
+
+## STEP 5: Launch the campaign
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/campaigns/{campaignId}/launch' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' -d '{}'
+```
+
+Returns the campaign with an updated `status`. Ads begin serving across Google channels; see [Query Campaign Performance Analytics](query-campaign-analytics.md) — PMAX Leads supports per-asset metrics.
+
+---
+
+## Error handling
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ACCOUNT_NOT_FOUND` | No Google Ads account | Run [install-and-create-account](install-and-create-account.md) |
+| `INVALID_ARGUMENT` / `NOT_ENOUGH_ASSETS` | Asset group below minimums | Add assets to meet the per-type counts in the table |
+| `INVALID_ARGUMENT` / `INVALID_ASSET_GROUP_ASSETS` | An asset is malformed or violates Google requirements | Fix the offending asset (length, type, url) |
+| `INVALID_ARGUMENT` / `INVALID_IMAGE_FORMAT` | Image format/dimensions unsupported | Use a supported ratio/size; regenerate via image-asset-suggestions |
+| `INVALID_ARGUMENT` / `DUPLICATE_IMAGE_ASSETS` / `DUPLICATE_ASSET` | Same asset provided twice | Deduplicate the asset group |
+| `INVALID_ARGUMENT` / `SEARCH_THEME_POLICY_VIOLATION` / `POLICY_VIOLATION` | A signal/asset violates Google policy | Remove or rewrite the flagged item |
+| `INVALID_ARGUMENT` / `RESTRICTED_LOCATION` | Targeted geo is restricted | Remove it; pick a specific allowed place |
+| `INVALID_ARGUMENT` / `CAMPAIGN_DAILY_BUDGET_TOO_HIGH` | Budget over the account max | Lower it within `daily-budget-boundaries` |
+| `FAILED_PRECONDITION` / `MAXIMUM_NUMBER_OF_CAMPAIGNS_REACHED` | 5 live campaigns already | Pause one before launching |
+| `INVALID_ARGUMENT` / `GOOGLE_ADS_API_ERROR` | Unexpected Google Ads rejection | Surface the message; verify and retry |
+
+## References
+
+- [Campaign Service introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/campaign-v1/introduction)
+- [Create Campaign](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/campaign-v1/create-campaign)
+- [Launch Campaign](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/campaign-v1/launch-campaign)
+- [Get Text Asset Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-text-asset-suggestions)
+- [Get Image Asset Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-image-asset-suggestions)
+- [Get Search Theme Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-search-theme-suggestions)
+- [Generate Budget Recommendation](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/generate-budget-recommendation)

package/skills/wix-manage/references/google-ads/get-campaign-suggestions.md

@@ -0,0 +1,110 @@
+---
+name: "Get AI Campaign Suggestions for Google Ads"
+description: "Reference for the Google Ads Suggestions API on a Wix site: AI/Google-generated inputs that help build effective campaigns — keyword themes (from a URL or autocomplete), geo-target options, low/recommended/high daily-budget tiers with estimated clicks, PMAX budget recommendations, text assets (headlines/descriptions), AI image assets (auto-uploaded to Wix Media), search themes, promotional incentive offers, and complete AI-generated campaign configurations from a campaign brief. Use when the user asks 'suggest keywords for my ads', 'what budget should I use', 'where should I target', 'generate ad copy/headlines', 'generate ad images', 'suggest a whole campaign', or when a create-campaign flow needs suggested values. REST base https://www.wixapis.com/google-ads/v1."
+---
+# RECIPE: Get AI Campaign Suggestions for Google Ads
+
+The Suggestions API produces the values that make a campaign effective — keywords, locations, budgets, and creative assets — either from Google directly or from Wix's AI. It's the input layer for the create-campaign recipes; this file is the standalone reference for each endpoint and for the two that don't appear there (full campaign suggestions from a brief, and incentive offers).
+
+Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. All suggestion endpoints are **read-only** — none create or spend anything, so run them freely.
+
+> **Two conventions to carry into every answer (this is where they trip people up):**
+> - **Budgets come back in micros.** Every `dailyBudget` / `budgetAmountMicros` / `recommendedBudgetAmountMicros` is in micros, where `1,000,000` micros = 1 unit of the account's currency (so `15000000` = $15.00/day). Always convert to currency units when presenting to a user, and pass micros back when creating a campaign.
+> - **Geo suggestions return an `id`, not a usable target.** `geo-options` returns each location's `id` (e.g. `"1023191"`). To target it in a campaign you must wrap it as `geoTargetConstants/{id}` (e.g. `"geoTargetConstants/1023191"`) in `locations[].location.geoTargetConstant`. The raw `id` alone is not accepted.
+
+**Which suggestion do you need?**
+
+| Goal | Endpoint | Used by |
+| --- | --- | --- |
+| Keyword themes for a Smart campaign | `keyword-theme-suggestions` / `keyword-theme-options` | Smart campaigns |
+| Geo targets | `geo-options` | Smart & PMAX |
+| Daily budget tiers (Smart) | `budget-suggestions` | Smart campaigns |
+| Budget recommendation (PMAX) | `budget-recommendation` | [PMAX](create-performance-max-campaign.md) |
+| Headlines & descriptions (PMAX) | `text-asset-suggestions` | [PMAX](create-performance-max-campaign.md) |
+| AI images (PMAX) | `image-asset-suggestions` | [PMAX](create-performance-max-campaign.md) |
+| Search themes (PMAX Leads) | `search-theme-suggestions` | [PMAX](create-performance-max-campaign.md) |
+| A full AI campaign config from a brief | `campaign-suggestions` | this recipe |
+| Promotional credit offers | `incentives` | [account setup](install-and-create-account.md) |
+
+For the campaign-building endpoints (keyword themes, geo, Smart budget, PMAX text/image/search-theme assets, PMAX budget recommendation), see the Quick Reference below — and the [Performance Max recipe](create-performance-max-campaign.md) for the PMAX asset/budget calls in context. Below are the two endpoints unique to this reference.
+
+---
+
+## Full AI campaign suggestions (from a campaign brief)
+
+Generates one or more complete, ready-to-use campaign configurations — assets, keywords, and geo targets bundled into a `campaign` object you can pass almost directly to Create Campaign. Smart suggestions come from a previously created **campaign brief**; PMAX Leads suggestions come from the site's marketing settings and pages. Uses an LLM — responses can take up to **120 seconds**.
+
+- `campaignBriefId` — required for `SMART` (the brief id you created earlier). PMAX Leads doesn't need one.
+- `amount` — how many suggestions to generate (max 3).
+- `campaignType` — `SMART` (default) or `PERFORMANCE_MAX_LEADS`.
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/campaign-suggestions' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{ "campaignBriefId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "amount": 1, "campaignType": "SMART" }'
+```
+
+```json
+{ "campaignSuggestions": [ {
+  "campaignMessaging": "Reach local customers searching for fresh-baked goods",
+  "campaign": {
+    "name": "Sunrise Bakery – Smart Campaign",
+    "campaignType": "SMART",
+    "budget": { "amountMicros": "15000000" },
+    "smartCampaign": {
+      "businessName": "Sunrise Bakery",
+      "url": "https://www.example.com",
+      "languageCode": "en",
+      "adGroups": [ { "ads": [ {
+        "headlines": ["Fresh Baked Daily", "Order Custom Cakes"],
+        "descriptions": ["Award-winning pastries made fresh every morning.", "Custom cakes for every occasion."]
+      } ] } ]
+    }
+  }
+} ] }
+```
+
+Present `campaignMessaging` and the config to the user, then use the `campaign` object as the basis for creating the campaign (add `accountId`, `status`, `budget`, and `locations` before Create). `costInMicrocents` in the response is the AI cost — absorbed by Wix, not charged to the caller. Errors: `MISSING_CAMPAIGN_BRIEF_ID` (Smart without a brief), `MAX_CAMPAIGNS_TO_SUGGEST_EXCEEDED` (`amount` > 3).
+
+---
+
+## Promotional incentive offers
+
+Credit offers for **new** accounts, granted after a spend threshold. Only supported currencies return offers. This drives the optional incentive step of [account setup](install-and-create-account.md).
+
+```bash
+curl -X GET 'https://www.wixapis.com/google-ads/v1/incentives?currency=USD' -H 'Authorization: <AUTH>'
+```
+
+Returns `lowOffer` / `mediumOffer` / `highOffer`, each with `incentiveId`, `awardAmount`, and `requiredAmount`, plus a `consolidatedTermsAndConditionsUrl`. Pass the chosen `incentiveId` as `selectedIncentiveId` when creating the account.
+
+---
+
+## Quick reference — the create-flow suggestion endpoints
+
+- **Keyword themes:** `POST /v1/keyword-theme-suggestions` with `{ suggestionInfo: { liveSiteUrl, languageCode, businessName? } }` → themes with `displayName`. Autocomplete: `GET /v1/keyword-theme-options?queryText=&languageCode=&countryCode=`.
+- **Geo targets:** `GET /v1/geo-options?queryLocation=&languageCode=&countryCode=` → geo targets with `id` (→ `geoTargetConstants/{id}`). May include restricted countries (rejected at create).
+- **Smart budget tiers:** `POST /v1/budget-suggestions` with `{ suggestionInfo: { liveSiteUrl, languageCode } }` → `low`/`recommended`/`high` with `dailyBudget` (micros) and estimated clicks.
+- **PMAX budget:** `POST /v1/budget-recommendation` with `{ campaignType, assetGroupInfo:[{finalUrl,...}], currency, ... }` → `recommendedBudgetAmountMicros` + `budgetOptions`.
+- **Text assets:** `POST /v1/text-asset-suggestions` (`suggestionInfo.landingPageUrl` + `textSuggestionInfo.languageCode` required).
+- **Image assets:** `POST /v1/image-asset-suggestions` (`suggestionInfo.landingPageUrl` required; images auto-uploaded to Wix Media).
+- **Search themes:** `POST /v1/search-theme-suggestions` (`textSuggestionInfo.languageCode` required).
+
+## Error handling
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `INVALID_ARGUMENT` / `MISSING_CAMPAIGN_BRIEF_ID` | `SMART` campaign-suggestions without a brief | Create a campaign brief first, or request `PERFORMANCE_MAX_LEADS` |
+| `INVALID_ARGUMENT` / `MAX_CAMPAIGNS_TO_SUGGEST_EXCEEDED` | `amount` > 3 | Request at most 3 |
+| Slow response on campaign/asset/budget suggestions | LLM/Google calls (SLA up to 60–120s) | Wait; don't retry prematurely |
+| Incentives returns no offers | Currency not supported | Proceed without an incentive |
+| `INVALID_ARGUMENT` on text/image assets | `landingPageUrl`/`languageCode` missing | Provide the required fields |
+
+## References
+
+- [Suggestions Service introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/introduction)
+- [Get Campaign Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-campaign-suggestions)
+- [Get Keyword Theme Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-keyword-theme-suggestions)
+- [Get Geo Options](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-geo-options)
+- [Get Budget Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-budget-suggestions)
+- [Get Incentives](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-incentives)

package/skills/wix-manage/references/google-ads/google-ads-dashboard-navigation.md

@@ -0,0 +1,25 @@
+---
+name: "Google Ads Dashboard Navigation"
+description: "Builds a direct link to the Wix Google Ads dashboard page on manage.wix.com, where campaigns created via the Google Ads API recipes are managed. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+---
+
+# Google Ads Dashboard Navigation
+
+Build direct links into the Google Ads page of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Google Ads | `google-ads` | The Google Ads account, campaigns, and their performance |
+
+## Pairing Entities with Their Read APIs
+
+Fetch state via the Google Ads recipes in this area (`GET /google-ads/v1/accounts/current-site`, `GET /google-ads/v1/accounts/current-site/conversion-actions`), then link the page.
+
+Example — after creating a campaign:
+
+```
+Your Performance Max campaign is live.
+Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/google-ads
+```

package/skills/wix-manage/references/google-ads/install-and-create-account.md

@@ -0,0 +1,155 @@
+---
+name: "Install Google Ads and Create an Account"
+description: "One-time setup for running Google paid ads on a Wix site: install the Wix Google Ads app, then create the Google Ads account that every campaign, suggestion, and analytics call depends on. Covers checking whether an account already exists, choosing a currency, optionally attaching a promotional incentive (credit offer), linking a Google Merchant Center account, and deleting an account. Use when the user wants to 'set up Google Ads', 'connect Google Ads', 'start advertising on Google', 'create a Google Ads account', or hits an ACCOUNT_NOT_FOUND / app-not-installed error before creating a campaign. Google Ads REST API, base https://www.wixapis.com/google-ads/v1."
+---
+# RECIPE: Install Google Ads and Create an Account
+
+Setting up Google Ads on a Wix site is a **strict two-step prerequisite** for everything else in this area: (1) install the Wix Google Ads app, then (2) create the Google Ads account. Campaigns, suggestions, analytics, and billing all fail with `ACCOUNT_NOT_FOUND` (or an app-not-installed error) until both are done. This is a one-time setup per site.
+
+Base URL for all endpoints: `https://www.wixapis.com/google-ads/v1`. The `<AUTH>` placeholder is shorthand for the `Authorization` header; body-bearing calls also need `Content-Type: application/json`.
+
+> **This flow creates a billable advertising account.** Creating the account and launching campaigns spends the site owner's real money. Confirm intent with the user before calling **Create Account**, and surface the chosen currency.
+
+---
+
+## STEP 0: Check whether an account already exists (do this first)
+
+Before installing or creating anything, check for an existing account. **Get Account For Current Site** returns an empty response (not an error) when none exists, so it's the safe probe.
+
+```bash
+curl -X GET 'https://www.wixapis.com/google-ads/v1/accounts/current-site' -H 'Authorization: <AUTH>'
+```
+
+- **`account` present** → setup is already done. Skip to whatever the user actually wants (create a campaign, view analytics, etc.). Do **not** create a second account — Create Account returns `ACCOUNT_ALREADY_EXISTS`.
+- **Empty response `{}`** → no account yet. Continue to STEP 1.
+
+Example response for an existing account:
+
+```json
+{
+  "account": {
+    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "googleAccountId": "123-456-7890",
+    "currency": "USD",
+    "accountStatus": "ACTIVE",
+    "currentBudget": { "value": "50.00", "currency": "USD" },
+    "spentBudget": { "value": "12.50", "currency": "USD" },
+    "paymentStatus": { "status": "PAID" }
+  }
+}
+```
+
+`account.id` is the Wix-internal GUID used as `campaign.accountId` when creating campaigns. `googleAccountId` is the underlying Google Ads customer ID (display only). `currentBudget` is remaining ad credit — a **negative** value means outstanding debt not yet charged.
+
+---
+
+## STEP 1: Install the Wix Google Ads app
+
+Idempotent — safe to call even if already installed (no effect). Required before Create Account.
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/install-if-not-installed' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' -d '{}'
+```
+
+Returns `{}`. Always run this before the first Create Account on a site.
+
+---
+
+## STEP 2 (optional): Offer a promotional incentive
+
+New accounts in supported currencies can attach an **incentive** — a promotional credit granted after the account spends a threshold. Skip this step for unsupported currencies (the call returns no offers).
+
+```bash
+curl -X GET 'https://www.wixapis.com/google-ads/v1/incentives?currency=USD' -H 'Authorization: <AUTH>'
+```
+
+Returns up to three tiers (`lowOffer`, `mediumOffer`, `highOffer`), each with an `incentiveId`, an `awardAmount` (credit granted), and a `requiredAmount` (spend needed to unlock it), plus a `consolidatedTermsAndConditionsUrl`. Present the tiers to the user and let them pick; carry the chosen `incentiveId` into STEP 3 as `selectedIncentiveId`. The incentive is recorded now and applied automatically once the account's budget is assigned — there is no separate apply call in this flow.
+
+---
+
+## STEP 3: Create the Google Ads account
+
+Requires `currency` (ISO-4217, e.g. `USD`). Pass `selectedIncentiveId` if the user picked one in STEP 2. **Confirm with the user before this call** — it provisions a billable account.
+
+```bash
+curl -X POST 'https://www.wixapis.com/google-ads/v1/accounts' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{
+    "currency": "USD",
+    "selectedIncentiveId": "incentive-promo-2024-usd-500"
+  }'
+```
+
+**Response** — save `account.id` for campaign creation:
+
+```json
+{
+  "account": {
+    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "googleAccountId": "123-456-7890",
+    "currency": "USD",
+    "accountStatus": "ACTIVE",
+    "paymentStatus": { "status": "PENDING_SUBSCRIPTION" },
+    "selectedIncentiveId": "incentive-promo-2024-usd-500"
+  }
+}
+```
+
+The currency choice is durable and drives budget minimums/maximums and manager-account selection — settle it with the user before creating. A currency Google doesn't natively support (only USD, EUR, GBP, JPY are native) still works; the account reports `budgetInSupportedCurrency` as the converted amount.
+
+---
+
+## Managing an existing account
+
+### Link a Google Merchant Center account (for Shopping / retail PMAX)
+
+`UpdateAccount` is a partial update — send only the fields you're changing. Merchant Center linking is needed before a retail Performance Max campaign can serve product ads.
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/google-ads/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{ "account": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "merchantCenterAccountId": "9876543210" } }'
+```
+
+The response's `merchantCenterAccountLinkStatus.status` starts at `PENDING` — the Merchant Center account owner must approve the link before it becomes `ENABLED`.
+
+### View conversion actions
+
+Conversion actions (Purchase, Page View, etc.) are what campaigns optimize toward. To inspect them:
+
+```bash
+curl -X GET 'https://www.wixapis.com/google-ads/v1/accounts/current-site/conversion-actions' -H 'Authorization: <AUTH>'
+```
+
+### Delete the account
+
+`DeleteAccount` unlinks and removes the account. This is destructive and cannot be undone — **always confirm with the user first**, and prefer pausing campaigns over deleting the whole account when the user just wants to stop spending.
+
+```bash
+curl -X DELETE 'https://www.wixapis.com/google-ads/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890' -H 'Authorization: <AUTH>'
+```
+
+Returns `{}`. Errors with `ACCOUNT_NOT_FOUND` if no account exists.
+
+---
+
+## Error handling
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ALREADY_EXISTS` / `ACCOUNT_ALREADY_EXISTS` on Create Account | An account is already linked to this site | Don't create another — use Get Account For Current Site and continue with the existing `account.id` |
+| `INTERNAL` / `CREATION_BLOCKED` on Create Account | Account creation is temporarily disabled platform-wide | Not a caller error; surface it and retry later |
+| `ACCOUNT_NOT_FOUND` on any campaign/analytics/billing call | Setup wasn't completed (no account) | Run this recipe: install the app, then Create Account |
+| App-not-installed error before Create Account | STEP 1 was skipped | Call Install (STEP 1); it's idempotent |
+| Get Incentives returns no offers | Currency not supported for incentives | Proceed to Create Account without `selectedIncentiveId` |
+| `NOT_FOUND` / `ACCOUNT_NOT_FOUND` on Delete Account | No account exists for the site | Nothing to delete; confirm with Get Account For Current Site |
+
+## References
+
+- [Google Ads APIs introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/introduction)
+- [App Installer Service](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-ads-app-installer-v1/introduction)
+- [Account Service](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/introduction)
+- [Create Account](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/create-account)
+- [Get Account For Current Site](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/get-account-for-current-site)
+- [Get Incentives](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-incentives)

package/skills/wix-manage/references/google-ads/manage-campaign-lifecycle.md

@@ -0,0 +1,63 @@
+---
+name: "Manage Campaign Lifecycle"
+description: "Manages existing Google Ads campaigns on a Wix site: list/get, launch (first activation) vs resume (reactivate after a pause), pause a running campaign — optionally with a scheduled auto-resume date — update name/budget/targeting, change the daily budget, delete permanently, and read status history / change log. Use when the user wants to 'pause my Google ad', 'resume my campaign', 'stop the campaign', 'change my daily budget', 'rename the campaign', 'delete this campaign', 'list my Google Ads campaigns', or 'why did my campaign status change'. Requires an existing Google Ads account and campaign. REST base https://www.wixapis.com/google-ads/v1."
+---
+# RECIPE: Manage Campaign Lifecycle
+
+Operate on campaigns that already exist. Base URL: `https://www.wixapis.com/google-ads/v1`; `<AUTH>` = `Authorization` header, and body calls also need `Content-Type: application/json`.
+
+**Answer directly.** When the user asks *how* to do something, give the endpoint, an example request, and the key behavior right away — use `{campaignId}` as a placeholder rather than asking which campaign. Only pause to confirm when you are about to **execute** a launch, resume, or delete on the user's behalf (those spend money or are irreversible); explaining how never requires confirmation.
+
+> **Launch vs Resume — the key distinction.** **Launch** activates a campaign for the *first time* (`POST /v1/campaigns/{campaignId}/launch`). **Resume** reactivates one that was live and then *paused* (`POST /v1/campaigns/{campaignId}/resume`). Both move it to `LIVE` and both count against the **5-live-campaigns-per-site** cap.
+
+## Read
+
+- **List:** `GET /v1/campaigns` → `{ "campaigns": [ { "id", "campaignType", "status", "name", "budget": { "amountMicros" } } ] }`
+- **Get one:** `GET /v1/campaigns/{campaignId}` — `status` and `budget` are synced live from Google on each read.
+
+`status` (read-only, can change on its own via policy/billing): `DRAFT`, `LIVE`, `PAUSED`, `LEARNING` (PMAX Leads, ~28d post-launch), `IN_REVIEW`, `DISAPPROVED`, `NOT_SERVING` (budget), `ENDED`, `ERROR`.
+
+## Launch / Pause / Resume
+
+```bash
+# Launch (first activation)  → status LIVE
+curl -X POST 'https://www.wixapis.com/google-ads/v1/campaigns/{campaignId}/launch' -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' -d '{}'
+
+# Pause a running campaign (settings + data preserved) → status PAUSED
+curl -X POST 'https://www.wixapis.com/google-ads/v1/campaigns/{campaignId}/pause' -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{ "scheduledResumeDate": "2024-04-15T08:00:00.000Z" }'
+
+# Resume a paused campaign → status LIVE
+curl -X POST 'https://www.wixapis.com/google-ads/v1/campaigns/{campaignId}/resume' -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' -d '{}'
+```
+
+- **Pause** stops delivery immediately without losing configuration. Optional body fields: `scheduledResumeDate` (ISO 8601 — the campaign **auto-resumes** at that time; pass `null` to cancel a scheduled resume), `resumeReminderDate` (dashboard reminder), `turnAutoRenewOff`. Send `{}` to pause with no auto-resume. To temporarily stop a campaign, **pause it — never delete**.
+- **Resume** accepts `{ "turnAutoRenewOn": true }` to re-enable subscription auto-renewal. Fails with `MAXIMUM_NUMBER_OF_CAMPAIGNS_REACHED` if 5 are already live.
+
+## Update (partial) & change budget
+
+`PATCH /v1/campaigns/{id}` — send only the fields you're changing, plus the required `id` and `accountId`. Budget is in **micros** (`20000000` = $20.00/day).
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/google-ads/v1/campaigns/{campaignId}' -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{ "campaign": { "id": "...", "accountId": "...", "name": "New name", "budget": { "amountMicros": "20000000" } } }'
+```
+
+Changing only the daily budget = the same call with just `id`, `accountId`, and `budget.amountMicros`. Over the account max → `CAMPAIGN_DAILY_BUDGET_TOO_HIGH` (check `GET /v1/campaign/daily-budget-boundaries`, returns min/max in micros).
+
+## Delete & history
+
+- **Delete (irreversible):** `DELETE /v1/campaigns/{id}` → `{}`. Confirm first; prefer Pause if the user only wants to stop spending.
+- **Change log:** `GET /v1/campaigns/{id}/change-log` → `{ "entries": [ { "action": "CREATED|LAUNCHED|PAUSED|RESUMED|UPDATED|ENDED", "timestamp" } ] }` — use this to explain "why/when did my campaign change." (`GET /v1/campaigns/{id}/status-history` is a legacy equivalent.)
+
+## Errors
+
+| Code | Meaning / fix |
+| --- | --- |
+| `CAMPAIGN_NOT_FOUND` | Wrong or deleted id — re-list campaigns |
+| `ACCOUNT_NOT_FOUND` | No Google Ads account — run the install-and-create-account recipe |
+| `MAXIMUM_NUMBER_OF_CAMPAIGNS_REACHED` | 5 live already — pause one, then Launch/Resume |
+| `CAMPAIGN_DAILY_BUDGET_TOO_HIGH` | Budget over account max — lower within daily-budget-boundaries |
+| `CUSTOM_CHARGES_SUBSCRIPTION_EXPIRED` / `…_AUTO_RENEWAL_OFF` | Renew / re-enable auto-renewal (Resume accepts `turnAutoRenewOn`) |
+
+[Campaign Service docs](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/campaign-v1/introduction)