@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-manage/references/bookings/booking-system-integration-gaps.md

@@ -51,7 +51,7 @@ The Wix Bookings system contains **fundamental undocumented integration patterns
 - ❌ **NOT** documented booking status vs order status separation
 - ❌ **NOT** documented service properties preservation in checkout
 - ❌ **NO** mention of `BACKOFFICE_MERCHANT` channel requirement
-- ❌ **NO** explanation of why checkout/order APIs are needed for bookings
+- ❌ **NO** explanation of why the cart/order APIs are needed for bookings
 
 **Additional Service-Specific Gaps**:
 - ❌ **Courses**: Dual API requirement (booking + calendar events) completely undocumented
@@ -69,7 +69,7 @@ The Wix Bookings system contains **fundamental undocumented integration patterns
 - Create booking → Booking system creates reservation only
 - Use booking ID as catalog item in ecom system
 - Ecom system handles all pricing, tax, discount calculations
-- Create checkout and order for actual payment processing
+- Create a cart and place the order for actual payment processing
 - Async messaging system handles payment confirmation
 - Booking status (CONFIRMED) independent of payment status
 
@@ -125,7 +125,7 @@ Actual Required Flow: Booking API → Ecom Integration → Payment ✓
 
 **Universal Pattern** (Works for ALL Service Types):
 ```
-Create Booking → Extract Booking ID → Use as Catalog Item ID → Create Checkout → Create Order → Process Payment
+Create Booking → Extract Booking ID → Use as Catalog Item ID → Create Cart → Place Order → Process Payment
 ```
 
 ### 2. Identify Service Type-Specific Booking Patterns
@@ -266,26 +266,33 @@ Create calendar events using `POST https://www.wixapis.com/calendar/v3/bulk/even
 
 **MAJOR DISCOVERY**: ALL booking payments use identical ecommerce integration pattern.
 
-**Step 6A: Create Checkout with Booking ID as Catalog Item**
+**Step 6A: Create Cart with Booking ID as Catalog Item**
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout))
+Cart V2 unifies cart and checkout — there is no separate checkout entity, so the created cart's `id` is what later steps use as the cart/checkout id.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart))
 
 ```json
 {
-  "lineItems": [{
+  "catalogItems": [{
     "catalogReference": {
       "catalogItemId": "<BOOKING_ID>",
       "appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97"
     },
     "quantity": 1
-  }],
-  "channelType": "WEB"
+  }]
 }
 ```
 
-**Step 6B: Create Order for Payment Processing**
+**Step 6B: Place Order for Payment Processing**
+
+First calculate the cart to obtain a price-verification token:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/calculate` — read `summary.priceVerificationToken` from the response.
+
+Then place the order, passing that token:
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder`
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/place-order` (body `{ "priceVerificationToken": "<TOKEN>" }`)
 
 **Critical Architecture Discoveries**:
 - **Automatic ID Transformation**: Booking IDs automatically valid as catalog item IDs
@@ -297,7 +304,7 @@ Create calendar events using `POST https://www.wixapis.com/calendar/v3/bulk/even
 
 **Payment Processing Architecture**:
 ```
-Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
+Booking (CONFIRMED) → Cart → Place Order → Payment Processing (async)
                                               ↓
                                         Messaging System
                                               ↓
@@ -322,7 +329,7 @@ Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
 **Service Packages**: Multi-service booking + ecom integration
 
 **Universal Integration Considerations**:
-- All service types use same checkout/order creation pattern
+- All service types use the same cart/order creation pattern
 - Pricing calculations always handled by ecom system
 - Async payment confirmation applies to all booking types
 - Service properties preserved across all integration points
@@ -406,7 +413,7 @@ Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
 * [Standard Booking Flow](https://dev.wix.com/docs/api-reference/business-solutions/bookings/flow-single-service-booking) - Missing payment integration
 * [Create Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking) - No payment processing guidance
 * [Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types) - Missing integration patterns
-* [Ecommerce Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/introduction) - No booking integration mention
+* [Ecommerce Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) - No booking integration mention
 
 **Completely Undocumented**:
 * **Booking→Ecom Integration**: Universal pattern affecting all booking payments

package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md

@@ -19,7 +19,7 @@ Step-by-step flow for implementing a complete booking experience using REST APIs
 - **Services API**: [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
 - **Time Slots V2 API**: [List Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots)
 - **Bookings API**: [Create Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking), [Confirm Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/confirm-booking)
-- **eCommerce API**: [Create Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout)
+- **eCommerce API**: [Create Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart)
 
 ---
 
@@ -226,15 +226,17 @@ Use the `id` and `revision` from the Create Booking response. Set `paymentStatus
 
 **Result**: Booking status changes to `CONFIRMED` and is visible in the booking calendar.
 
-### For online payments: Create checkout
+### For online payments: Create a cart
 
-**4a. Create Checkout**
+Cart V2 unifies cart and checkout — there is no separate checkout entity. The created cart's `id` is what you use for the checkout URL and for placing the order.
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts`
+**4a. Create Cart**
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts`
 
 ```json
 {
-  "lineItems": [
+  "catalogItems": [
     {
       "catalogReference": {
         "catalogItemId": "<BOOKING_ID>",
@@ -242,22 +244,33 @@ Use the `id` and `revision` from the Create Booking response. Set `paymentStatus
       },
       "quantity": 1
     }
-  ],
-  "channelType": "WEB"
+  ]
 }
 ```
 
-Use the booking ID as `catalogItemId` with the Wix Bookings app ID.
+Use the booking ID as `catalogItemId` with the Wix Bookings app ID. Save `cart.id` from the response.
 
 **4b. Get Checkout URL**
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/getCheckoutUrl`
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/get-checkout-url`
 
 Redirect the user to the returned `checkoutUrl`. After payment, the booking is automatically confirmed.
 
-**4c. Create Order (alternative, server-to-server)**
+**4c. Place Order (alternative, server-to-server)**
+
+First calculate the cart to get a price-verification token:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/calculate`
+
+Save `summary.priceVerificationToken` from the response, then place the order:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/place-order`
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder`
+```json
+{
+  "priceVerificationToken": "<PRICE_VERIFICATION_TOKEN>"
+}
+```
 
 Creates an order directly without redirect.
 

package/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md

@@ -10,7 +10,7 @@ This recipe documents how to convert CMS collections into sellable product catal
 
 Converting a CMS collection to a catalog enables:
 - Items in the collection become purchasable products
-- Integration with Wix Cart and Checkout APIs
+- Integration with the Wix Cart API (Cart V2, which unifies cart and checkout)
 - Real-time price and availability from your CMS data
 
 ## Prerequisites
@@ -73,7 +73,7 @@ POST https://www.wixapis.com/wix-data/v2/collections/add-plugin
 Most Wix sites with Stores, Bookings, or similar apps already have eCommerce installed. Check by querying the Cart API:
 
 ```
-POST https://www.wixapis.com/ecom/v1/carts
+POST https://www.wixapis.com/ecom/v2/carts
 ```
 
 ## Step 3: Use Catalog Items in Cart
@@ -87,12 +87,12 @@ e593b0bd-b783-45b8-97c2-873d42aacaf4
 ### Add CMS Catalog Item to Cart
 
 ```
-POST https://www.wixapis.com/ecom/v1/carts/{cartId}/add-to-cart
+POST https://www.wixapis.com/ecom/v2/carts/{cartId}/add-line-items
 ```
 
 ```json
 {
-  "lineItems": [
+  "catalogItems": [
     {
       "catalogReference": {
         "appId": "e593b0bd-b783-45b8-97c2-873d42aacaf4",
@@ -133,4 +133,4 @@ CMS Catalogs are best for simple product catalogs. For complex eCommerce needs,
 
 - [CMS Schema Management](cms-schema-management.md)
 - [CMS Data Operations](cms-data-items-crud.md)
-- [Wix Cart API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/introduction)
+- [Wix Cart API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction)

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

@@ -0,0 +1,141 @@
+---
+name: "Manage a Campaign Success Guide"
+description: "Retrieves and manages the campaign success guide for an existing Wix Google Ads Performance Max Leads campaign. Offer it after creating a supported campaign, even while it is learning or has no metrics; that proactive offer requires approval before retrieval. A direct request to improve a campaign, see what to fix next, or show the guide is already approval to retrieve it. Also use when a user reports completing or wants to reopen a guide item. Treat a clear completion report as an actionable update request even when phrased as a statement. Covers campaign selection, prioritized guide retrieval, and suggestion status updates without redundant confirmation. REST base https://www.wixapis.com/pa-platform/suggestions/v1."
+---
+# 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](create-performance-max-campaign.md). 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](get-campaign-suggestions.md), 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](manage-campaign-lifecycle.md) and call:
+
+   ```bash
+   curl -X GET 'https://www.wixapis.com/google-ads/v1/campaigns' \
+     -H 'Authorization: <AUTH>'
+   ```
+
+   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
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/pa-platform/suggestions/v1/campaign-success-guides/get-or-create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "campaignId": "7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab",
+    "platformType": "GOOGLE"
+  }'
+```
+
+```json
+{
+  "campaignSuccessGuide": {
+    "id": "7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab",
+    "url": "https://www.example.com/request-a-quote",
+    "suggestions": [
+      {
+        "id": "131b82f1-44f5-4f32-8cf1-f783a5f35222",
+        "type": "CLEAR_CTA_COPY",
+        "status": "OPEN"
+      }
+    ]
+  }
+}
+```
+
+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:
+
+| Enum | User-facing meaning |
+| --- | --- |
+| `CLEAR_CTA_COPY` | Clarify the primary call-to-action button's conversion intent. |
+| `ABOVE_THE_FOLD_CTA` | Put a call-to-action where visitors can see it without scrolling. |
+| `HEADER_MATCH` | Align the landing-page heading with the campaign's ad headlines. |
+| `CONVERSION_POINT` | Add a visible lead form or booking action. |
+| `GOOGLE_REVIEWS` | Display Google reviews or ratings. |
+| `TESTIMONIAL` | Add customer testimonials attributed to named people. |
+| `CONTACT_AND_CREDIBILITY` | Display a phone number and email address. |
+| `FAQ_SECTION` | Add a visible FAQ section. |
+| `MINIMIZE_FORM_FIELDS` | Limit the lead form to four visible fields. |
+| `SOCIAL_CHANNELS` | Add a visible social profile link. |
+| `GOOGLE_MERCHANT_CENTER_CONNECTION` | Connect Google Merchant Center. |
+| `GOOGLE_BUSINESS_PROFILE_CONNECTION` | Connect a Google Business Profile. |
+| `GOOGLE_ADS_SEARCH_THEMES` | Configure Google Ads search themes. |
+| `MOBILE_OPTIMIZATION` | Improve mobile optimization. |
+| `SITE_SPEED` | Improve site speed. |
+
+## 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:
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/pa-platform/suggestions/v1/campaign-success-guides/7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab/update-suggestion-status' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "type": "CLEAR_CTA_COPY",
+    "status": "COMPLETED"
+  }'
+```
+
+Reopen the same item by sending:
+
+```json
+{
+  "type": "CLEAR_CTA_COPY",
+  "status": "OPEN"
+}
+```
+
+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
+
+| Error | Response behavior |
+| --- | --- |
+| `PLATFORM_NOT_SUPPORTED` | Use `GOOGLE`; do not substitute another platform value. |
+| `CAMPAIGN_TYPE_NOT_SUPPORTED` | Explain that success guides currently support Google Ads Performance Max Leads campaigns only. |
+| `SUGGESTION_NOT_FOUND` | Retrieve the latest guide and choose a `type` actually present; do not keep retrying stale data. |
+| Authentication or permission error | Stop after the first rejected campaign or guide call and explain that the current collaborator cannot access or modify it. Do not try alternate base URLs, infer that Google Ads is not installed, or probe other endpoints to bypass authorization. |
+
+## References
+
+- [Suggestions API introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/introduction)
+- [Get or Create Campaign Success Guide](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/get-or-create-campaign-success-guide)
+- [Update Campaign Success Guide Suggestion Status](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/update-campaign-success-guide-suggestion-status)

package/skills/wix-manage/references/google-business-profile/connect-google-business-profile.md

@@ -0,0 +1,134 @@
+---
+name: "Connect a Wix Site to Google Business Profile"
+description: Connect the authenticated Wix site to a Google Business Profile account, check whether an existing connection is still usable, recover a connection whose stored credentials are gone, switch to a different Google account, or disconnect. The site owner authorizes in their own browser through a single-use connect URL; the agent never completes the Google authorization itself. Warns before any reconnect that permanently removes the site's imported locations.
+---
+
+# Connect a Wix Site to Google Business Profile
+
+Use the public **Google Business Profile Connection API** to link the
+authenticated Wix site to a Google Business Profile account. The REST requests
+do not contain a site ID — the site comes from the caller's authorization
+context. Use the site the environment already supplies; if no site is selected,
+list the user's sites once and auto-select the only one, or ask the user to
+choose by site name when several are available. Never invent a site ID or ask
+the user to type one. A connection is the prerequisite for Google-backed work in the Google
+Business Profile Locations API — establish it before importing or managing
+locations.
+
+> **Bounded connect path — read first.** Read the connection once. For
+> `NEVER_CONNECTED`, request one connect URL and hand it to the owner; for
+> `VALID`, stop unless the user asked for other Google-backed work. A `403`,
+> `PERMISSION_DENIED`, or other terminal recovery-rule error ends the flow:
+> the **next action is the final response** explaining the blocker. Make no
+> further tool call: no API probe, documentation search, alternate request
+> shape, or call against another site. Only the explicitly
+> retryable `CONNECTING_USER_LOOKUP_UNAVAILABLE` error permits another connect-URL
+> attempt.
+
+Wix stores the Google credentials server-side. The API never returns tokens or
+any Google identity — only whether a connection exists and its dates.
+
+## Direct calls for this flow
+
+These are the complete request shapes needed for a fresh connection. Use them
+directly; do not search the API reference before calling them.
+
+| Method | Call |
+|---|---|
+| **Get Connection** | `GET https://www.wixapis.com/gbp/v1/connection` — no body or parameters |
+| **Get Connect URL** | `GET https://www.wixapis.com/gbp/v1/connect-url` — no body or parameters |
+
+For the common `NEVER_CONNECTED` path the only API calls are one **Get
+Connection**, then one **Get Connect URL**. If either returns `403` or
+`PERMISSION_DENIED`, stop immediately and explain it; do not look for another
+method or request shape.
+
+## Check the status first
+
+Always start with **Get Connection** and branch on `status`:
+
+| `status` | Meaning | What to do |
+|---|---|---|
+| `VALID` | Wix holds a credential for this site | Proceed with Google-backed work |
+| `NEVER_CONNECTED` | The site has never been connected | Run the connect flow — this is a setup step, not an error |
+| `NEEDS_RECONNECT` | The connection record exists but the stored credentials are gone | Warn the owner (see below), then run the connect flow |
+
+`VALID` is not a live health check: **Get Connection** deliberately does not
+call Google, so a connection can report `VALID` and still be refused by
+Google — for example after the owner revoked Wix's access in their Google
+account settings. Treat a Google-side authorization failure on a Locations
+call as the authoritative signal and re-run the connect flow when one appears.
+
+## Run the connect flow
+
+1. Call **Get Connect URL** once and read `connectUrl`.
+2. Present `connectUrl` to the site owner as a link to open in their own
+   browser, where they sign in to Google and grant access. Never fetch or open
+   the URL yourself — it is for a human, single-use, and expires after
+   15 minutes.
+3. Explain that completion is asynchronous: Google redirects the owner's
+   browser back to Wix, which finishes the OAuth exchange and stores the
+   credentials server-side.
+4. When the owner reports they have finished (or while waiting, on a modest
+   interval of a few seconds), call **Get Connection** and confirm `status` is
+   `VALID`. The `status` field is the only source of truth — a returned
+   connect URL alone proves nothing.
+5. If the 15-minute window elapses with `status` unchanged, request a fresh
+   URL and let the owner try again.
+
+**Get Connect URL is not idempotent, despite its GET route.** Every successful
+call creates a distinct live authorization attempt. Never retry it
+automatically after a timeout or ambiguous response — re-check
+**Get Connection** first and let the owner explicitly start another attempt.
+
+## Warn before a reconnect that replaces the connection
+
+Two flows permanently remove every Business Profile location imported into the
+site — the locations created through Wix as well as the imported ones. For
+locations migrated from an earlier Wix integration this cannot be reversed by
+re-importing. Get the owner's explicit confirmation **before** handing them
+the connect URL; there is no confirmation step later:
+
+- **Switching to a different Google account.** No Disconnect is needed — the
+  new account simply replaces the connection when its authorization completes.
+- **Reconnecting from `NEEDS_RECONNECT`, even with the same Google account.**
+  The stored credentials are gone, so there is nothing to match the incoming
+  account against and the reconnect is always treated as a replacement.
+
+While credentials are still present (`VALID`), authorizing again with the
+**same** Google account heals the connection in place and removes nothing.
+
+Also tell the owner that replacing or disconnecting changes nothing inside
+Google Business Profile itself — locations, reviews, and photos stay exactly
+as they are on Google — and does not revoke Wix's access inside their old
+Google account; they remove that from their Google account settings.
+
+## Disconnect
+
+Call **Disconnect** only after the owner confirms. It deletes the credentials
+Wix stores; it does not touch the Google Business Profile and does not revoke
+Wix's grant inside the Google account.
+
+## Recovery rules
+
+- **`CONNECTING_USER_LOOKUP_UNAVAILABLE`:** the site-owner lookup failed
+  temporarily, before any authorization attempt was created. This is the one
+  failure of **Get Connect URL** that is safe to retry.
+- **`CONNECTING_USER_NOT_RESOLVABLE`:** Wix could not identify a user to own
+  the credential. Stop — this is not retryable until the caller identity or
+  site ownership is corrected. Explain the blocker instead of trying other
+  request shapes.
+- **Timeout or ambiguous response from Get Connect URL:** do not retry. Call
+  **Get Connection** to learn the actual state, then let the owner decide.
+- **`MULTIPLE_CONNECTIONS_NOT_REPRESENTABLE`:** the site holds more than one
+  connection and the API will not guess which one is meant. Not a caller error
+  and not retryable — report it and direct the user to contact Wix support.
+- **Permission denied:** stop after the first `403` or `PERMISSION_DENIED`.
+  Do not retry with another request shape or site, and do not search for an
+  alternate API or method. Explain that the current Wix identity is not
+  authorized to manage the site's Google connection.
+
+The direct calls above are self-contained for the normal connect path. Consult a
+specific public method reference only for an edge case not covered here, and
+only before making a call. Once a status or typed error selects a branch above,
+do not search or browse for an alternate API, method, or request shape.