Ctrlk
design-packs.comView on Shopify App Store
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Setting Up a Google Maps API Key

This guide walks you through getting a Google Maps API key for use with the Map – pins section. If you'd rather not deal with a Google account or billing, you can leave the section's "Map provider" set to OpenStreetMap — it's free, requires no setup, and works out of the box.

Why use Google Maps?

Google Maps gives you:

  • A look and feel that most shoppers immediately recognise

  • Premium map styles (Silver, Retro, Dark, etc.)

  • More detailed labels for businesses, transit, and landmarks

  • Smoother panning and zooming in dense urban areas

The trade-off: Google requires a billing-enabled account and charges per map load above their free monthly credit.

Costs at a glance

Google currently includes a $200 monthly credit on every Maps Platform account, which translates to roughly 28,000 free dynamic map loads per month. Most small and mid-sized stores stay well within that.

You still have to attach a billing method to your Google Cloud account to activate the key — even if you never exceed the free credit. Google won't charge the card unless you go over.

For current pricing, see Google Maps Platform Pricing.

Step 1 — Create a Google Cloud project

  1. Go to the Google Cloud Console.

  2. Sign in with your Google account (or create one).

  3. In the top bar, click the project dropdown → New Project.

  4. Give it a name like My Store Maps and click Create.

  5. Once it's created, make sure that project is selected in the top bar.

Step 2 — Enable the Maps JavaScript API

  1. In the Cloud Console search bar at the top, type Maps JavaScript API and select it from the results.

  2. Click Enable.

If prompted to set up billing, do so now — see Step 3.

Step 3 — Add a billing account

  1. In the left sidebar, go to Billing.

  2. Click Link a billing account (or Create billing account if you don't have one).

  3. Follow the prompts to add a credit/debit card.

  4. Link the billing account to your new project.

This is required even though you'll be inside the free tier — Google uses it as an identity check and to bill any overage.

Step 4 — Create the API key

  1. In the left sidebar, go to APIs & Services → Credentials.

  2. Click + Create Credentials → API key.

  3. Google will generate a key that looks like AIzaSy…. Copy it.

  4. Click Edit API key to open its settings — you'll restrict it in the next step.

Step 5 — Restrict the key (important!)

An unrestricted key can be copied off your site and used by anyone, racking up charges on your account. Restrict it so it only works on your store.

In the API key's settings page:

Application restrictions

  1. Select Websites.

  2. Click Add and enter each of the following (replacing yourstore.com with your actual domain):

    • https://yourstore.com/*

    • https://www.yourstore.com/*

    • https://yourstore.myshopify.com/* (your .myshopify.com domain)

  3. If you use a staging or preview environment, add those too.

API restrictions

  1. Select Restrict key.

  2. From the dropdown, choose Maps JavaScript API.

  3. Click Save.

Step 6 — Add the key to your section

  1. In your Shopify admin, go to Online Store → Themes → Customize.

  2. Navigate to a page containing the Map – pins section (or add it).

  3. Open the section's settings.

  4. Under 🗺 Map provider, change Map provider to Google Maps.

  5. Paste your key into the Google Maps API key field.

  6. Pick a Google Maps style (Default, Grayscale, Silver, Retro, or Dark).

  7. Save.

The map should refresh and display through Google Maps within a few seconds.

Troubleshooting

"This page can't load Google Maps correctly" / grey map with watermark

  • The API key is missing, wrong, or your project doesn't have Maps JavaScript API enabled.

  • Double-check Step 2 and Step 4.

"RefererNotAllowedMapError" in the browser console

  • Your storefront's domain isn't in the Website restrictions list for the key.

  • Open the key's settings and add the exact domain (including the https:// and trailing /*).

  • Save and wait 1–2 minutes for changes to propagate.

"BillingNotEnabledMapError"

  • The Google Cloud project doesn't have a billing account attached.

  • Revisit Step 3.

"ApiNotActivatedMapError"

  • Maps JavaScript API isn't enabled on this project.

  • Revisit Step 2 — and make sure you're enabling it on the same project the key was created in.

The map shows but my pins or styles look off

  • Make sure you've also selected a Google Maps style in the section settings.

  • The Color filter setting only applies to OpenStreetMap — for Google Maps, use the Google Maps style dropdown instead.

Optional — Monitor usage and set a budget

To avoid surprise charges:

  1. In the Cloud Console, go to Billing → Budgets & alerts.

  2. Click Create budget.

  3. Set a monthly target (e.g. $0 if you only want the free tier).

  4. Add email alerts at 50%, 90%, and 100% of the budget.

You can also cap daily request quotas on the Maps JavaScript API under APIs & Services → Maps JavaScript API → Quotas.

Reverting to OpenStreetMap

If you ever want to remove the Google Maps key:

  1. Open the section's settings in the customizer.

  2. Change Map provider back to OpenStreetMap (free).

  3. Save.

Your locations and search bar will continue to work — only the map tiles and styling change.

PreviousGift Card: How to leverage gift card shortcodes in text block
NextModals: How to Use the "Link Trigger" for Showing Extra Information

Last updated