> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/business-management/google-business-profile/connection-v1/introduction.md

## Article Content:

# About the Google Business Profile Connection API

The Connection API connects a Wix site to a Google Business Profile account, reports whether that
connection is still usable, and removes it. A connection is the prerequisite for Google-backed
operations and imports in the Google Business Profile Locations API. Wix-only reads and deletes do
not need active Google credentials.

Wix holds the site owner's Google credentials server-side. This API never returns an access token, a
refresh token, or any Google identity — only whether a connection exists and when it was created.

## What the API provides

With the Connection API, your app can:

- Start a Google authorization by retrieving a connect URL for the site owner to open.
- Check whether a site has usable Google credentials on file.
- Distinguish "never connected" from "connected but the credentials are gone".
- Disconnect a site, deleting the credentials Wix stores.

**What `VALID` does and doesn't tell you.** `VALID` means Wix holds a credential for this site. It is
not a live health check — Get Connection does not call Google, deliberately, so that polling it never
touches the stored credential. A connection can therefore report `VALID` and still be refused by
Google, for example if the owner revoked Wix's access from 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 you see one.

## Connecting an account

1. Call **Get Connect URL**. You get back a Google authorization URL.
2. Surface that URL to the site owner and have them open it. They authorize in their own browser —
   your app never handles their Google password or the authorization code.
3. Google redirects back to Wix, which completes the OAuth exchange server-side.
4. Poll **Get Connection** until `status` is `VALID`.

To disconnect, call **Disconnect**.

## Before you begin

- **The site owner must authorize in a browser.** There is no way to connect a Google account purely
  server-to-server, whether the flow starts in your app or in the SEO dashboard. Plan for a step your
  app cannot complete on the owner's behalf.
- **A site can have one connected Google account.** Get Connection and Disconnect therefore take no
  ID. Get Connect URL is no longer rejected just because the site is already connected — it starts
  a new authorization attempt whatever Get Connection reports, and neither case requires a
  Disconnect first. (It is not unconditional: a site that somehow holds two connections returns
  `MULTIPLE_CONNECTIONS_NOT_REPRESENTABLE`, described below.) Authorizing with the same Google
  account heals the connection in place **while its stored credentials are still there**, meaning
  Get Connection reports `VALID`. Authorizing with a different one replaces it — permanently
  removing every Business Profile location on the connection it replaced — created and imported
  alike.
- **A connect URL is single-use and expires after 15 minutes.** Request a fresh one for every
  attempt. Don't cache one or hand the same URL to two people.
- **Get Connect URL is not idempotent, despite its GET route.** Each successful call creates a
  distinct authorization attempt. Do not configure automatic retries or retry after a timeout or
  ambiguous response; first re-check the connection and let the site owner explicitly start another
  attempt if needed. The typed `CONNECTING_USER_LOOKUP_UNAVAILABLE` error is safe to retry because it
  occurs before an authorization attempt is created.
- **Completion is asynchronous.** Get Connect URL returning a URL does not mean the site is
  connected — only that authorization can now begin. `status` is the source of truth.
- **`NEEDS_RECONNECT` is not the same as an error.** It means the connection record still exists but
  the stored Google credentials are gone, typically because the Google account holder exercised a
  data-deletion request. Google-backed Locations calls and imports will fail until the site owner
  connects again, so treat it as a prompt to re-run the connect flow rather than as a transient
  failure to retry.

  **Reconnecting from `NEEDS_RECONNECT` always replaces the connection, even with the same Google
  account.** This is the one case where the same-account heal above does not apply. Wix identifies
  the account by an opaque reference to the stored credentials, so once those are erased there is
  nothing left to match the incoming account against, and the reconnect is treated as a
  replacement. Warn the site owner first: every Business Profile location on the old
  connection are permanently removed, and for locations migrated from an earlier Wix integration
  that cannot be reversed by re-importing.
- **Disconnecting is a Wix-side operation.** It deletes the credentials Wix stores. It does not change
  the customer's Google Business Profile, and it does not revoke Wix's grant inside their Google
  account — the owner does that from their Google account settings.
- **The connection is owned by the calling user.** When the caller is an app rather than a user, the
  connection is owned by the site owner instead.

Get Connect URL can fail while resolving that owner for an app caller:

- `CONNECTING_USER_LOOKUP_UNAVAILABLE` means the site-owner lookup failed temporarily. Retry Get
  Connect URL.
- `CONNECTING_USER_NOT_RESOLVABLE` means Wix could not identify a user to own the credential. This is
  not retryable until the caller identity or site ownership is corrected.

## Use cases

REST:

- Add a "Connect Google Business Profile" step to an onboarding flow, then poll until it completes.
- Show connection health on a dashboard and prompt for reconnection when `status` is
  `NEEDS_RECONNECT`.
- Check for a connection before attempting a Google-backed Locations call or import, so a missing
  connection is reported as a setup step rather than a failure.

Velo:

- Not available. This API is not mapped on site or Wix Code hosts, and site visitors are not an
  allowed audience, so it cannot be called from site code.

SDK:

- Drive the connect flow from a dashboard extension or a headless client, letting Wix own the OAuth
  exchange.

## Terminology

- **Connection**: The link between a Wix site and a Google account authorized to manage its Business
  Profile. Holds dates only — no Google identity and no credentials.
- **Connect URL**: A single-use, 15-minute Google authorization URL for the site owner to open.
- **Connection status**: `NEVER_CONNECTED`, `VALID`, or `NEEDS_RECONNECT`.
- **Google Business Profile (GBP)**: Google's product for managing how a business appears on Google
  Search and Maps. Business Profile *locations* are managed through the Locations API.

@sdk_package_setup