RECIPE: Manage a Campaign Success Guide

A campaign success guide is a prioritized list of improvements for an existing Google Ads PERFORMANCE_MAX_LEADS campaign. Offer it as a useful next step after creating a Performance Max campaign. Once Create Campaign returns the campaign ID, ask whether the user wants to retrieve the guide; call the API only after they approve. There is no need to wait for the campaign to leave LEARNING or generate performance metrics because the guide analyzes the landing page, campaign configuration, and relevant site connections rather than depending on campaign performance data.

Also use this recipe for requests such as "How can I improve my campaign?", "What should I fix next?", "Show my campaign success guide", "I made the call-to-action button clearer as the success guide recommended", "Mark this recommendation complete", or "Reopen that guide item."

A direct request to improve a campaign, see what to fix next, or show its success guide is itself approval to retrieve the guide once the campaign is identified. Do not ask whether the user wants the guide after they have already made one of those requests. Separate approval is needed only when you proactively offer the guide after campaign creation.

This differs from Get AI Campaign Suggestions, which generates keywords, budgets, locations, copy, images, and other inputs used while building a campaign. Do not route pre-campaign keyword, budget, creative, or targeting generation here.

Base URL: https://www.wixapis.com/pa-platform/suggestions/v1. <AUTH> is the Authorization header; body calls also need Content-Type: application/json.

Resolve the campaign

The guide endpoints require a campaign UUID, but users often provide only a campaign name or say "my campaign."

1. If the user provides a campaign UUID, use it.

2. Otherwise follow Manage Campaign Lifecycle and call:

   Copy

   Read each campaign's id, name, campaignType, and status.

3. Select a campaign only when one result clearly matches the user's wording. If none or multiple plausibly match, show concise choices and ask the user to choose; never guess.

4. Continue only for campaignType: "PERFORMANCE_MAX_LEADS". If the selected campaign has another type, explain that campaign success guides currently support Google Ads Performance Max Leads campaigns only. For a supported campaign, do not gate guide retrieval on status or query analytics first: LEARNING and missing performance metrics are not reasons to wait.

The common flow always sends platformType: "GOOGLE"; do not ask the user to provide it.

Retrieve or create the guide

The first call may analyze the landing page, campaign configuration, and relevant site connections and can take up to 120 seconds. Later calls normally return the saved guide unless campaign changes require another analysis. Wait for the request; do not retry prematurely. If execution times out with an unknown outcome, report the uncertainty and retrieve the guide later instead of immediately triggering another analysis.

Present only the suggestions the API returns and preserve their order; suggestions is already in priority order. An empty array means no currently detected items need attention, not an API failure. Show campaignSuccessGuide.url when it helps identify the analyzed landing page.

OPEN means pending action. COMPLETED means the user marked the item completed; it does not mean the API changed the site or campaign for them.

Translate suggestion types for the user

Keep the enum value unchanged in API calls, but use these labels when explaining the guide:

Mark an item completed or reopen it

The update endpoint identifies the suggestion by its type, not its suggestion id. A clear statement that the user completed a specific guide recommendation—for example, "I made the call-to-action button clearer as the success guide recommended"—is an actionable request to mark that item COMPLETED, not merely an FYI. Do not require the user to turn it into a question or ask for redundant confirmation.

Before executing an update:

1. Identify the campaign and a suggestion type currently present in its latest guide.
2. Match the user's wording to one returned suggestion and infer the requested status only when it is clear: a statement that they completed the recommendation means COMPLETED; a request to reopen it means OPEN.
3. Execute immediately when the campaign, suggestion, and status are unambiguous. Ask one targeted clarification only when any of them is unclear; never guess.

Mark an item completed:

Reopen the same item by sending:

The response wraps the updated guide as { "campaignSuccessGuide": { ... } }. Treat that returned guide as the new source of truth: report the changed tracking status and summarize remaining OPEN suggestions in priority order. Do not claim the underlying recommendation was implemented. Do not update multiple items unless the user's wording clearly identifies all of them.

If a mutation times out with an unknown outcome, do not retry automatically. Retrieve the guide later to determine the current status first.

Errors

References

• Suggestions API introduction
• Get or Create Campaign Success Guide
• Update Campaign Success Guide Suggestion Status