Astro-Entwickler in Hamburg

#Ein paar Produkte verkaufen, ohne einen Shop zu bauen

Viele Hamburger Betriebe verkaufen wenig, aber regelmäßig: ein Dutzend Produkte, Gutscheine, Kurse, ein Zubehörsortiment neben der eigentlichen Dienstleistung. Dafür ein vollständiges Shopsystem mit Theme, Konten und Filtern zu betreiben, ist oft mehr Aufwand als Umsatz. Die Alternative: Ihre Astro-Website zeigt die Produkte, Warenkorb und Kasse liegen bei Shopify.

Ich bin Mariusz Szatkowski, selbstständiger Entwickler in Gdynia, und arbeite ausschließlich aus der Ferne und schriftlich. Das Layout der Produktseiten liefern Sie, ich setze es um.

Foto: Thomas Wolf, www.foto-tw.de, CC BY-SA 3.0 de, Wikimedia Commons.

Shopify beschreibt auf seiner Seite zu Headless-Storefronts mehrere Wege für Websites, die schon existieren: die Storefront API, den Buy Button und die Storefront Web Components. Hydrogen und eine vollständige Shop-Oberfläche sind ein anderes Projekt, dazu schreibe ich unter Next.js in Leipzig und nicht hier.

#Drei Wege im Überblick

Der Buy-Button-Kanal ist laut Shopify Hilfe in allen Tarifen enthalten. Ebenfalls dort steht ein Hinweis: Buy Buttons auf dem eigenen Shopify-Onlineshop oder -Blog empfiehlt Shopify nicht, weil sie den Bestellvorgang stören können. Für eine Astro-Website außerhalb von Shopify ist das genau der vorgesehene Einsatz. Quelle: help.shopify.com, Buy Button.

#Storefront Web Components: der kürzeste Weg

Die Komponenten binden Sie mit einem Skript ein, das von cdn.shopify.com geladen wird. Die Elemente shopify-store und shopify-context holen die Daten. Der Warenkorb shopify-cart baut laut Dokumentation auf dem HTML-Element dialog auf. Für den Direktkauf rufen Sie buyNow(event) am Store auf, der Kunde landet dann mit der gewählten Variante in der Kasse.

Ein Zugriffstoken ist für Basisdaten zu Produkten, Preisen und Medien nicht nötig. Für Bestandszahlen oder eigene Produktdaten brauchen Sie den öffentlichen Storefront-Token, den Sie über den Headless-Kanal in der Shopify-Verwaltung erzeugen. Mit den Attributen country und language steuern Sie, welcher Markt mit Preisen und Inhalten angezeigt wird. Quelle: shopify.dev, Getting started.

Für diesen Weg gilt: Sie laden ein fremdes Skript. Eine strenge Content Security Policy muss die Shopify-Domain dann zulassen. Wie ich Sicherheitsheader in Astro aufsetze, steht unter Astro in Frankfurt.

#Storefront API: Warenkorb über einen eigenen Endpunkt

Wenn die Produktseite genau nach Ihrem Layout aussehen soll, sprechen Sie die Storefront API selbst an. Sie ist nur per GraphQL und nur über POST erreichbar. Die Adresse folgt dem Muster https://{store_name}.myshopify.com/api/2026-10/graphql.json; die Version steht im Pfad, im Beispiel der Dokumentation ist es 2026-10 (Stand November 2026).

Zwei Zugriffsarten unterscheidet Shopify. Der öffentliche Token ist für Browser und Apps gedacht und wird im Header X-Shopify-Storefront-Access-Token gesendet. Der private Token gehört in einen Server-Kontext und kommt im Header Shopify-Storefront-Private-Token; er darf nicht im Client-Code stehen. Die Dokumentation nennt für Käuferverkehr kein festes Anfragelimit pro Minute, begrenzt aber Bots und die Erstellung von Kassen. Quelle: shopify.dev, Storefront API.

In Astro liegt der private Token in einer Server-Variablen. Mit astro:env legen Sie ein Schema fest und markieren die Variable mit context: "server" und access: "secret". Geheime Server-Variablen landen laut Astro nicht im Bundle. Quelle: docs.astro.build, Umgebungsvariablen.

Der Ablauf zur Kasse ist kurz. Ein Formular auf der Produktseite sendet die Variante per POST an einen Endpunkt. Der Endpunkt legt mit cartCreate einen Warenkorb an, liest checkoutUrl und leitet weiter:

// src/pages/api/kasse.ts
import type { APIRoute } from "astro";
import { SHOPIFY_DOMAIN, SHOPIFY_PRIVATE_TOKEN } from "astro:env/server";

export const prerender = false;

export const POST: APIRoute = async ({ request, redirect }) => {
  const form = await request.formData();
  const variant = String(form.get("variant") ?? "");

  const res = await fetch(`https://${SHOPIFY_DOMAIN}/api/2026-10/graphql.json`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Shopify-Storefront-Private-Token": SHOPIFY_PRIVATE_TOKEN,
    },
    body: JSON.stringify({
      query: `mutation ($lines: [CartLineInput!]!) {
        cartCreate(input: { lines: $lines }) {
          cart { checkoutUrl }
          userErrors { message }
        }
      }`,
      variables: { lines: [{ quantity: 1, merchandiseId: variant }] },
    }),
  });

  const { data } = await res.json();
  const url = data?.cartCreate?.cart?.checkoutUrl;
  return url ? redirect(url, 303) : new Response("Warenkorb nicht angelegt", { status: 502 });
};

Das ist ein Gerüst, kein fertiger Shop: Fehlerbehandlung, Mengen und mehrere Positionen kommen hinzu. Zwei Punkte aus der Dokumentation: Der Warenkorb liegt bei Shopify und lässt sich später über seine vollständige ID abrufen, die ein Geheimnis enthält. Und die checkoutUrl soll erst angefordert werden, wenn der Käufer zur Kasse geht. Bei Serveraufrufen mit angemeldeten Kunden verlangt Shopify zusätzlich den Header Shopify-Storefront-Buyer-IP. Quelle: shopify.dev, Cart verwalten.

#Produktdaten: beim Build oder je Anfrage

Astro rendert Seiten, Routen und Endpunkte standardmäßig beim Build als statische Seiten. Ein fetch im Komponentenskript läuft dann einmal beim Build; die ausgelieferte Seite ruft die Daten nicht noch einmal ab. Mit export const prerender = false stellen Sie einzelne Seiten auf Abruf um, dafür ist ein Adapter nötig. Quellen: On-demand-Rendering und Daten abrufen. Welchen Adapter und welches Hosting Sie wählen, behandle ich unter Astro in Berlin.

Meine Faustregel für einen kleinen Katalog:

• Beschreibung, Bilder, Varianten: beim Build. Sie ändern sich selten, die Seite lädt ohne Server.
• Preis und Verfügbarkeit: nicht fest in die Seite schreiben, wenn sie sich öfter ändern. Ein Preis, der auf der Seite alt und in der Kasse neu ist, ist ein Streitfall.
• Kasse und Warenkorb: immer je Anfrage, über den Endpunkt oben.

Für Preis und Bestand gibt es in Astro die Server Islands. Mit server:defer wird nur ein Baustein auf Abruf gerendert, der Rest der Seite bleibt statisch. Bis der Baustein da ist, steht ein Platzhalter im Slot fallback. Die Antwort kommt per GET, deshalb gelten normale Cache-Control-Header. Props müssen serialisierbar sein; bei Betrieb hinter einem CDN setzen Sie ASTRO_KEY. Quelle: docs.astro.build, Server Islands. Zum Prinzip der Inseln, die Skripte nur dort laden, wo sie nötig sind, schreibe ich unter Astro in Wiesbaden.

Eine Frage bleibt für den Betrieb offen: Wer stößt einen neuen Build an, wenn sich Produkte ändern? Das lässt sich über den Hoster lösen, ist aber eine Entscheidung vor dem Start und kein Detail.

#Was das deutsche Recht auf Ihrer Seite verlangt

Die Astro-Seite ist Ihre Seite, nicht die von Shopify. Deshalb gelten die Pflichten für Händler dort, wo Sie das Angebot zeigen.

• Gesamtpreis: § 3 PAngV verlangt von Unternehmern, die Verbrauchern Waren anbieten oder mit Preisen werben, die Angabe der Gesamtpreise.
• Umsatzsteuer und Versand: § 6 PAngV verlangt bei Fernabsatzverträgen die Angabe, dass die Preise Umsatzsteuer und sonstige Preisbestandteile enthalten, und ob Fracht-, Liefer- oder Versandkosten anfallen. Fallen sie an, ist ihre Höhe anzugeben, soweit sie vernünftigerweise im Voraus berechnet werden können. Quelle: § 6 PAngV.
• Bestellbutton: § 312j Abs. 3 BGB verlangt, dass der Verbraucher mit der Bestellung ausdrücklich bestätigt, sich zur Zahlung zu verpflichten. Eine Schaltfläche muss mit nichts anderem als den Wörtern zahlungspflichtig bestellen oder einer entsprechend eindeutigen Formulierung beschriftet sein. Nach Abs. 4 kommt der Vertrag nur zustande, wenn Sie diese Pflicht erfüllen. Quelle: § 312j BGB.

Ein Kaufen-Button auf der Astro-Seite ist noch nicht der Bestellbutton, er führt in die Kasse. Den Text der Schaltfläche am Ende der Kasse prüfen Sie in einer Testbestellung auf Deutsch, bevor die Seite live geht. Ob die Kasse einer bestimmten Shopify-Konfiguration das erfüllt, kann ich nicht aus der Ferne zusichern; die Prüfung gehört in Ihre Abnahme.

Zusätzlich: Ein Warenkorb, dessen Kennung im Browser liegt, berührt § 25 TDDDG. Danach ist das Speichern von Informationen im Endgerät nur mit Einwilligung zulässig, außer es ist unbedingt erforderlich, damit ein vom Nutzer ausdrücklich gewünschter Dienst bereitgestellt werden kann (§ 25 Abs. 2 Nr. 2). Ob der Warenkorb darunter fällt, entscheiden Sie im Einzelfall; ich halte die gespeicherten Daten so knapp wie möglich. Quelle: § 25 TDDDG.

#Hamburg: Gastbestellung und die Datenschutzbehörde

Zuständig für den Datenschutz ist der Hamburgische Beauftragte für Datenschutz und Informationsfreiheit (HmbBfDI). Er berichtet auf seiner Website über ein Urteil zum Thema Gastzugang: Das Hanseatische Oberlandesgericht bestätigte am 27. Februar 2025 (Az. 5 U 30/24) in zweiter Instanz die Auffassung des HmbBfDI. Geklagt hatte die Verbraucherzentrale Nordrhein-Westfalen gegen Otto.de mit dem Ziel, Gastbestellungen zu erzwingen; das Gericht wies die Klage ab. Ein Kundenkonto verstoße nicht gegen die Datenminimierung, wenn inaktive Konten automatisch gelöscht werden und nur Daten erhoben werden, die für die Vertragserfüllung nötig sind.

Die Behörde schreibt außerdem, nach einem Beschluss der Datenschutzkonferenz von 2022 dürften Onlinehändler grundsätzlich kein Kundenkonto verlangen und müssten Gastbestellungen zulassen, mit Ausnahmen etwa für Marktplätze. Das Gericht habe den Beschluss nicht als bindend, aber als Soft Law betrachtet. Bei einer Prüfung Hamburger Onlineshops habe der HmbBfDI von einem Versandhändler verlangt, künftig Gastbestellungen zu ermöglichen. Quelle: datenschutz-hamburg.de.

Für Ihre Lösung heißt das: Die Frage, ob in der Kasse ein Konto nötig ist, liegt nicht im Astro-Code. Klären Sie sie vor dem Start und legen Sie sie in der schriftlichen Abnahme fest. Zu Datenschutz im Handel allgemein gibt es dort außerdem eine Seite für den Handel.

#Wann ein eigenes Shopsystem besser ist

Diese Lösung stößt an Grenzen, bevor sie kompliziert wird:

• Großer Katalog: Filter, Suche und Kategorien selbst zu bauen ist ein Shop-Frontend. Dann lohnt sich die Lösung aus dem Beitrag zu Next.js in Leipzig oder ein Shopify-Theme.
• Kundenkonten, Bestellhistorie, Abos: das sind Funktionen des Shops, nicht der Website.
• Verkauf in mehrere EU-Länder: Märkte, Steuer und Versand je Land stehen im Beitrag zu Shopify in Hamburg.
• Ihr Team pflegt Inhalte im WordPress-Backend: dann ist WooCommerce in Hamburg oft näher an Ihrem Alltag.
• Mehrsprachige Seite: Produktseiten in mehreren Sprachen sind lösbar; den Aufbau beschreibe ich unter Astro in Zürich.

Wenn Sie schon bei Shopify verkaufen und nur eine schnelle Vorstellungsseite mit Kaufbutton daneben wollen, reichen die Web Components. Wenn Sie nie verkauft haben, empfehle ich, zuerst mit zwei oder drei Produkten zu beginnen und erst danach auszubauen.

#Checkliste vor dem Start

• Wie viele Produkte und Varianten gibt es, und wie oft ändern sich Preise?
• Wer stößt einen neuen Build an, wenn sich Produkte ändern?
• Liegt der private Token nur als Server-Variable vor?
• Stehen Gesamtpreis, Umsatzsteuerhinweis und Versandkosten neben dem Preis?
• Ist der Text der Bestellschaltfläche in einer Testbestellung geprüft?
• Ist geklärt, ob Gastbestellung möglich sein soll?
• Lässt die Content Security Policy die Shopify-Domain zu?

#So arbeite ich mit Ihnen

Sie schicken mir schriftlich Ihr Ziel, die Produkte und das Layout, am einfachsten in einer Tabelle, die Sie nach meiner Vorlage ausfüllen. Das Layout samt Mockups und Wireframes bringen Sie mit. Ich beantworte offene Fragen schriftlich, lege Umfang und Annahmen schriftlich fest, setze die Seite auf einer Staging-Umgebung um und übergebe sie nach Ihrer Abnahme. Auf Wunsch betreue ich die Seite danach; siehe Wartung und Support in Hamburg. Gerade bei einem Shop sollten Updates zuerst auf Staging laufen, damit Warenkorb und Kasse nicht ausfallen. Einzelne Formulare und deren Spamschutz beschreibt der Beitrag Astro in Wuppertal.

#Häufige Fragen

#Brauche ich für den Verkauf von einer Astro-Seite einen Server?

Nicht für Produktseiten, die beim Build entstehen. Sobald ein Preis oder Bestand je Anfrage kommen soll, oder ein Endpunkt einen Warenkorb anlegt, braucht Astro laut Dokumentation einen Adapter und eine Seite mit prerender = false.

#Darf ich den Storefront-Token im Browser verwenden?

Der öffentliche Token ist nach der Dokumentation von Shopify dafür gedacht, dass Käufer ihn sehen. Der private Token gehört nur auf den Server und darf nicht im Client-Code stehen.

#Wer verantwortet den Bestellbutton, wenn die Kasse bei Shopify liegt?

Das Gesetz richtet sich an den Unternehmer, also an Sie. § 312j Abs. 3 BGB verlangt eine Schaltfläche, die mit zahlungspflichtig bestellen oder gleich eindeutig beschriftet ist. Prüfen Sie den Text in einer Testbestellung auf Deutsch.

#Müssen Preise auf der Astro-Seite Umsatzsteuer und Versand nennen?

Ja, die Seite mit dem Angebot ist Ihre Seite. § 3 PAngV verlangt den Gesamtpreis, § 6 PAngV bei Fernabsatz den Hinweis auf Umsatzsteuer und darauf, ob Versandkosten anfallen, mit Höhe, soweit vorab berechenbar.

#Reicht ein Buy Button oder sind Web Components besser?

Shopify nennt beide Wege für Produkte auf einer bestehenden Website. Der Buy-Button-Kanal erzeugt Schaltflächen und Warenkorb-Permalinks, die Web Components bringen Produktdaten, Warenkorb und Direktkauf als HTML-Elemente. Welcher passt, hängt vom Umfang der Produktseite ab.

#Wann ist ein eigenes Shopsystem die bessere Wahl?

Bei großen Katalogen mit Filtern, Kundenkonten, Abos oder Bestandsführung in Echtzeit. Dann sind Shopify selbst, WooCommerce oder ein komplettes Headless-Frontend sinnvoller als einzelne Kaufbuttons.

#Schreiben Sie mir

Schicken Sie mir über die Kontaktseite die Adresse Ihrer Website, die Produkte, die Sie verkaufen wollen, Ihr Shopify-Konto oder Ihre Pläne dafür und einen Wunschtermin. Ich melde mich schriftlich an Werktagen. Meine erste schriftliche Einschätzung zu Ihrem Vorhaben kostet nichts.