Setting the file. One moment.
Subchapter 8.72
references/google-ads/get-campaign-suggestions.mdMarkdown9 KBView on GitHub
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/recommendedBudgetAmountMicrosis in micros, where1,000,000micros = 1 unit of the account’s currency (so15000000= $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-optionsreturns each location’sid(e.g."1023191"). To target it in a campaign you must wrap it asgeoTargetConstants/{id}(e.g."geoTargetConstants/1023191") inlocations[].location.geoTargetConstant. The rawidalone 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 |
| Headlines & descriptions (PMAX) | text-asset-suggestions | PMAX |
| AI images (PMAX) | image-asset-suggestions | PMAX |
| Search themes (PMAX Leads) | search-theme-suggestions | PMAX |
| A full AI campaign config from a brief | campaign-suggestions | this recipe |
| Promotional credit offers | incentives | account setup |
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 for the PMAX asset/budget calls in context. Below are the two endpoints unique to this reference.
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.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" }'{ "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).
Credit offers for new accounts, granted after a spend threshold. Only supported currencies return offers. This drives the optional incentive step of account setup.
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.
POST /v1/keyword-theme-suggestions with { suggestionInfo: { liveSiteUrl, languageCode, businessName? } } → themes with displayName. Autocomplete: GET /v1/keyword-theme-options?queryText=&languageCode=&countryCode=.GET /v1/geo-options?queryLocation=&languageCode=&countryCode= → geo targets with id (→ geoTargetConstants/{id}). May include restricted countries (rejected at create).POST /v1/budget-suggestions with { suggestionInfo: { liveSiteUrl, languageCode } } → low/recommended/high with dailyBudget (micros) and estimated clicks.POST /v1/budget-recommendation with { campaignType, assetGroupInfo:[{finalUrl,...}], currency, ... } → recommendedBudgetAmountMicros + budgetOptions.POST /v1/text-asset-suggestions (suggestionInfo.landingPageUrl + textSuggestionInfo.languageCode required).POST /v1/image-asset-suggestions (suggestionInfo.landingPageUrl required; images auto-uploaded to Wix Media).POST /v1/search-theme-suggestions (textSuggestionInfo.languageCode required).| 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 |