fix(checkout): CHECKOUT-10026 Add new Places API support for Google Autocomplete with legacy fallback

[bc-maxy]

What/Why?

Makes the new Google Places API the primary autocomplete provider (behind experiment flag CHECKOUT-10026.new_google_places_api), falling back to the legacy API on permission errors. Moves merchants onto the cheaper new API automatically, with no change for stores whose keys aren't yet provisioned for it.

How

GoogleAutocomplete.tsx now tries the new API first. On gRPC PERMISSION_DENIED it latches a page-session-wide fallback flag and switches to the legacy AutocompleteService/PlacesService for the rest of the session. Added a 300ms debounce on suggestion fetching. New newGooglePlacesApi/ module handles the new API (loader, service, session tokens, field mapping). Both old and new loaders now share one Maps script load via importLibrary, since loading the Maps JS API twice breaks it.

Billing

Session tokens bundle keystrokes + selection into one billed session. Field masks request only addressComponents/displayName, keeping calls in the cheapest pricing tier so this should improve costs significantly.

Rollout/Rollback

Revert the PR.

Testing

CI + Manual testing.

Before

Existing customers with old API keys:

Screen.Recording.2026-06-30.at.3.16.03.PM.mov

New customers with new API keys (doesn't work):

Screen.Recording.2026-06-30.at.3.18.15.PM.mov

After

Existing customers with old API keys (Initial 403, then fallback to the old service. Billing step will remember that we fallback and skips new api):

Screen.Recording.2026-06-30.at.3.30.18.PM.mov

New customers with new API keys:

Screen.Recording.2026-06-30.at.3.24.12.PM.mov

---

Note

Medium Risk
Changes checkout address entry and external Google SDK loading with session-wide fallback behavior; regressions could affect suggestion quality, latency, or merchants on legacy-only keys, though legacy paths are preserved.

Overview
Checkout address Google Autocomplete now prefers the new Places API (AutocompleteSuggestion / Place) and falls back to the legacy AutocompleteService / PlacesService when the new API fails. A shared newGooglePlacesApiState.isUnavailable flag latches after gRPC PERMISSION_DENIED so legacy-only API keys skip repeated new-API calls for the rest of the page session; transient errors still retry the new API.

GoogleAutocomplete wires both services, adds 300ms debounced suggestion fetching (immediate clear when the input is empty), and routes selection through new or legacy place-details paths with the same PlaceResult shape for onSelect.

The Maps loader is replaced with Google’s importLibrary bootstrap and loadPlacesLibrary (no @bigcommerce/script-loader callback URL). Legacy GoogleAutocompleteService now loads the places library the same way. New NewGooglePlacesApiService adds session tokens, prediction caching via toPlace(), minimal field masks, and legacy↔new mapping helpers.

Broad unit tests cover the component fallback matrix, loader bootstrap/memoization, and the new service/utils.

^{Reviewed by Cursor Bugbot for commit 45efb30. Bugbot is set up for automated code reviews on this repo. Configure here.}

[bc-maxy]

cursor review

[bc-maxy]

cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e02bfce. Configure here.}

[bc-maxy]

cursor review

[bc-maxy]

cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 45efb30. Configure here.}