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; forVALID, stop unless the user asked for other Google-backed work. A403,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 retryableCONNECTING_USER_LOOKUP_UNAVAILABLEerror 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
- Call Get Connect URL once and read
connectUrl. - Present
connectUrlto 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. - 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.
- When the owner reports they have finished (or while waiting, on a modest
interval of a few seconds), call Get Connection and confirm
statusisVALID. Thestatusfield is the only source of truth — a returned connect URL alone proves nothing. - If the 15-minute window elapses with
statusunchanged, 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
403orPERMISSION_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.