Spring til indhold

Guide

Adresse-autocomplete i Shopify

Shopify har en understøttet indgang til præcis det her: Address Autocomplete API'en lader dig udskifte udbyderen af adresseforslag i checkout. Peger du den mod DAR, får dine kunder rigtige danske adresser i stedet for et generisk internationalt opslag.

Læs det her først: checkout UI extensions kræver Shopify Plus. Er du ikke på Plus, kan adresseforslagene i selve checkout ikke skiftes ud — checkout.liquid er udfaset, og vilkårlige scripts i checkout er ikke længere mulige. Du kan stadig bruge adresseopslaget andre steder i butikken og vaske de adresser, der allerede er kommet ind; se nederst.

Opsætning — og den ene linje, der vælter det

Checkout UI extensions er sandkassede. Glemmer du network_access, må extensionen ikke kalde ud, og opslaget fejler tavst — uden at der er noget galt med koden. Det er værd at sætte rigtigt fra start.

shopify.extension.tomltext
# shopify.extension.toml
# api_version sættes af Shopify CLI, når den scaffolder extensionen —
# brug den, den genererer, frem for at kopiere en fast værdi ind.
api_version = "2025-10"

[[extensions]]
type = "ui_extension"
name = "grundfast-adresse"
handle = "grundfast-adresse"

  [[extensions.targeting]]
  target = "purchase.address-autocomplete.suggest"
  module = "./src/suggest.js"

  # UDEN denne må extensionen ikke lave netværkskald, og opslaget fejler.
  [extensions.capabilities]
  network_access = true

1. Forslag mens kunden skriver

Slå kun op, når det giver mening: dansk land­ekode, adressefeltet, og mindst to tegn. Kaldet går gennem din egen app-backend, så nøglen ikke ligger i noget, der kører hos kunden. Shopify viser højst fem forslag.

src/suggest.jstypescript
// src/suggest.js — target: purchase.address-autocomplete.suggest
// Ingen import og ingen wrapper: det er en almindelig default async
// funktion, og inputtet ligger på den globale 'shopify'.
export default async () => {
  const { field, value, selectedCountryCode } = shopify.target;

  // Kun danske adresser giver mening at slå op mod DAR.
  if (selectedCountryCode !== 'DK' || field !== 'address1' || value.length < 2) {
    return { suggestions: [] };
  }

  // Dit eget app-endpoint — nøglen bliver på din server, ikke i extensionen.
  // shopify.signal afbryder kaldet, når kunden skriver videre.
  const res = await fetch(
    'https://din-app.example.com/adresse?q=' + encodeURIComponent(value),
    { signal: shopify.signal }
  );
  if (!res.ok) return { suggestions: [] };
  const { results } = await res.json();

  // Shopify viser HØJST fem forslag.
  return {
    suggestions: results.slice(0, 5).map((r) => ({
      id: r.adgangsadresse_id,
      label: r.betegnelse,
      // Ingen delstrenge at fremhæve — vi rangerer serverside.
      matchedSubstrings: [],
      // Fordi /v1/adresse/search allerede gav os de strukturerede felter,
      // kan vi levere den færdige adresse med det samme. Shopify udfylder
      // formularen med den, når kunden vælger forslaget.
      formattedAddress: {
        address1: [r.vejnavn, r.husnr].filter(Boolean).join(' '),
        address2: '',
        city: r.postnrnavn ?? '',
        zip: r.postnr ?? '',
        provinceCode: '',
        countryCode: 'DK',
      },
    })),
  };
};

2. Det andet target, du formentlig ikke skal bruge

format-suggestion findes, fordi mange adresse-udbydere først kan levere den fulde adresse, når kunden har valgt — så koster valget et opslag mere. Sådan er det ikke her: fordi /v1/adresse/search allerede gav vejnavn, husnummer, postnummer og by i søgesvaret, sender du formattedAddress med hvert forslag, og Shopify udfylder formularen med den ved valget. Tag kun targetet med, hvis du af andre grunde vil slå op igen.

src/format-suggestion.jstypescript
// src/format-suggestion.js — target:
// purchase.address-autocomplete.format-suggestion
//
// Dette target er til udbydere, der FØRST kan levere den fulde adresse,
// når kunden har valgt. Det behøver du ikke her: formattedAddress fulgte
// allerede med forslaget ovenfor. Tag kun targetet med, hvis du af andre
// grunde vil slå op igen ved valget.
export default async () => {
  const { selectedSuggestion } = shopify.target;
  return selectedSuggestion.formattedAddress;
};

Er du ikke på Plus

Så er checkout lukket land, og det skal siges rent ud frem for at sælge dig en løsning, der ikke kan installeres. To ting virker stadig, og de er ikke ingenting: adresseopslag i de formularer, du selv styrer i temaet eller i din backoffice — og datavask af de adresser, der allerede er kommet ind, med rangerede kandidater og konfidensbånd.

Byg det på en test-nøgle

En gf_test_-nøgle giver rigtige svar, faktureres aldrig og har 25.000 kald/md.

Se også

Ofte stillede spørgsmål

Kan alle Shopify-butikker bruge det her?

Nej. Checkout UI extensions — og dermed Address Autocomplete API’en — er forbeholdt Shopify Plus. Er du ikke på Plus, kan du ikke ændre adresseforslagene i selve checkout. Du kan stadig bruge Grundfast andre steder i butikken, fx i et adressefelt på en kundeprofil-side, i en formular i temaet eller i din backoffice — og du kan vaske de adresser, der allerede er kommet ind.

Kan jeg ikke bare skrive noget JavaScript ind i checkout?

Ikke længere. checkout.liquid er udfaset, og Shopify-checkout kan ikke ændres med vilkårlige scripts. Address Autocomplete API’en findes netop for at give en understøttet indgang til at udskifte udbyderen af adresseforslag — brug den frem for at lede efter en vej udenom.

Skal jeg bruge begge extension targets?

Nej, i praksis kun suggest. De to targets findes, fordi mange adresse-udbydere først kan levere den fulde adresse, når kunden har valgt et forslag — så henter format-suggestion den i et opslag mere. Vores /v1/adresse/search returnerer vejnavn, husnummer, postnummer og by allerede i søgesvaret, så du kan sende formattedAddress med hvert forslag. Shopify udfylder formularen med den ved valget, og andet opslag er overflødigt.

Hvorfor virker mit fetch-kald ikke i extensionen?

Sandsynligvis fordi extensionen ikke har fået lov til at gå på nettet. Checkout UI extensions er sandkassede, og netværkskald kræver network_access = true under [extensions.capabilities] i shopify.extension.toml. Uden den fejler opslaget, uden at der er noget galt med din kode.

Skal API-nøglen ligge i extensionen?

Nej. Læg et lille endpoint i din app-backend, som extensionen kalder, og hold nøglen der. Så kan du samtidig cache og rate-limite, før kaldene rammer os — og du undgår at udstille nøglen i noget, der kører hos kunden.

Hvad med adresser, der allerede er registreret?

Vask dem mod DAR med /v1/datavask/adgangsadresser. Du får rangerede kandidater med A/B/C-konfidensbånd og bfe_nummer, så det sikre kan rettes automatisk og resten sendes til gennemsyn. Det virker uanset hvilken Shopify-plan du er på.