Dokumentation

Was ist ShopiPixel?

ShopiPixel ist eine Shopify-App für Server-Side Conversion Tracking. Statt Tracking-Daten über den Browser deiner Kunden zu senden, übermittelt ShopiPixel Bestellungen und Kundenaktionen direkt von deinem Server an Werbeplattformen wie Meta, Google Analytics, TikTok und weitere.

Warum Server-Side Tracking?

Herkömmliches Browser-Tracking verliert zunehmend an Zuverlässigkeit: Ad-Blocker verhindern die Datenübertragung, iOS-Einschränkungen verkürzen Cookie-Laufzeiten und Browser blockieren Drittanbieter-Cookies. Das Ergebnis: Deine Werbekampagnen scheinen schlechter zu performen als sie es tatsächlich tun.

Mit Server-Side Tracking sendet ShopiPixel die Daten direkt und sicher an die Plattformen — unabhängig vom Browser. Das bedeutet: mehr erkannte Conversions, genauere Daten und ein besserer Return on Ad Spend (ROAS).

Dual-Track: Maximale Datenqualität

ShopiPixel kombiniert zwei Datenquellen für höchste Genauigkeit:

• Browser-Tracking (Web Pixel): Erfasst Klick-IDs aus Werbe-URLs und Browser-Daten wie Session-Kennungen.
• Server-Webhooks: Empfängt vollständige Bestelldaten direkt von Shopify — zuverlässig und unabhängig vom Browser.

Beide Quellen werden automatisch zusammengeführt, sodass jeder Event die bestmöglichen Daten enthält.

Erste Schritte & Einrichtung

Die Installation dauert nur wenige Minuten. In drei Schritten bist du startklar:

1. App installieren
   Installiere ShopiPixel aus dem Shopify App Store. Das Web Pixel wird automatisch aktiviert.
2. Plattform verbinden
   Gehe in die Einstellungen und trage die Zugangsdaten deiner Werbeplattform ein (z.B. Meta Pixel-ID und Access Token). Eine ausführliche Anleitung für jede der 10 Plattformen findest du unter Plattform-Einrichtung.
3. Plattform-seitige Konfiguration
   Neben den Credentials muss auch die Plattform selbst konfiguriert werden. Bei Google Ads z.B. muss Enhanced Conversions mit der Methode "Google Ads API" aktiviert sein, damit API-Events verarbeitet werden. Details pro Plattform findest du in der Einrichtungsanleitung.
4. Events prüfen
   Führe eine Testaktion in deinem Shop durch und prüfe im Dashboard, ob Events erfolgreich gesendet werden. Verifiziere auch in der jeweiligen Werbeplattform, ob Events dort ankommen und verarbeitet werden.

Ausführliche Anleitungen

Dashboard

Das Dashboard gibt dir einen Echtzeit-Überblick über dein Tracking. Hier siehst du auf einen Blick, wie deine Events performen.

KPI-Cards

Umsatz-Diagramm

Das Diagramm zeigt deinen Umsatz über Zeit. Du kannst verschiedene Zeiträume wählen (heute, 7 Tage, 30 Tage, Monat). Die verfügbaren Zeiträume hängen von deinem Plan ab.

Conversion Funnel

Der Funnel visualisiert den Weg deiner Kunden durch den Kaufprozess:

• Seitenaufruf → Produktansicht → Warenkorb → Checkout → Kauf

An jeder Stufe siehst du, wie viele Besucher abspringen. So erkennst du Schwachstellen in deinem Shop und kannst gezielt optimieren.

Plattform-Vergleich

Vergleiche Events und Erfolgsrate pro verbundener Plattform. So erkennst du sofort, wenn eine Plattform Probleme hat oder besonders gut performt.

Live Events

Der Event-Feed zeigt dir die aktuellsten Events in Echtzeit — mit Event-Typ, Plattform und Status. Fehlerhafte Events werden farblich hervorgehoben.

Top-Produkte

Eine Übersicht deiner bestverkauften Produkte, sortiert nach Umsatz. Zeigt Produktname, Anzahl der Verkäufe und Gesamtumsatz.

Tracking & Consent

Tracking-Modi

In den Einstellungen kannst du wählen, wie ShopiPixel Daten erfasst:

Consent Management (DSGVO)

ShopiPixel respektiert die Einwilligung deiner Kunden. Tracking-Events werden nur gesendet, wenn eine gültige Einwilligung vorliegt.

Shopify Privacy Banner

Shopifys eingebautes Privacy Banner wird automatisch erkannt. Keine zusätzliche Konfiguration nötig.

Drittanbieter Consent Management

ShopiPixel unterstützt alle gängigen Consent-Management-Plattformen:

• Cookiebot
• OneTrust
• Pandectes
• Consentmo
• Eigene CMP-Lösung

Die Consent-Signale werden automatisch erkannt und ausgewertet.

Google Consent Mode v2

ShopiPixel unterstützt Google Consent Mode v2 mit den Signalen „Ad User Data“ und „Ad Personalization“. Diese werden automatisch an Google Analytics 4 und Google Ads übermittelt.

Consent-Protokollierung

Jede Einwilligung wird mit Zeitstempel, Dokumentversion und Rechtsgrundlage protokolliert (Art. 7 DSGVO). Diese Aufzeichnungen stehen dir in der App unter Einstellungen zur Verfügung.

Enhanced Conversions

ShopiPixel sendet pseudonymisierte Kundendaten (gehashte E-Mail, Telefonnummer) an die Plattformen. Das verbessert die Zuordnung von Events zu echten Nutzern und erhöht die Event Match Quality bei Meta, Google und anderen Plattformen deutlich.

Events

ShopiPixel erfasst automatisch alle relevanten E-Commerce-Events in deinem Shopify-Shop und sendet sie an deine verbundenen Plattformen.

Unterstützte Events

Event-Quellen

• Browser (Web Pixel): Erfasst Events direkt im Shop deines Kunden. Enthält Click-IDs und Cookie-Daten für bessere Zuordnung.
• Server (Shopify Webhooks): Empfängt vollständige Bestelldaten direkt von Shopify — zuverlässig und unabhängig vom Browser.
• Beide Quellen werden automatisch zusammengeführt für maximale Datenqualität.

Automatische Deduplizierung

ShopiPixel erkennt und entfernt doppelte Events automatisch. Wenn ein Kauf sowohl vom Web Pixel als auch per Webhook gemeldet wird, wird nur ein Event an die Plattform gesendet — mit den kombinierten Daten beider Quellen.

Dual-Track: Kanalübergreifende Deduplizierung

Im Dual-Track-Modus (Web Pixel + Webhooks aktiv) werden Purchase- und InitiateCheckout-Events kanalübergreifend dedupliziert. Sobald das Web Pixel ein Event erfolgreich an alle Plattformen gesendet hat, wird der erneute Versand automatisch übersprungen. Das verhindert zuverlässig doppelte Conversions in GA4, Meta, TikTok und allen weiteren Plattformen — ohne dass du etwas konfigurieren musst.

Event-Browser

In der App unter „Events“ kannst du alle Events einsehen:

• Filtern nach Plattform und Status
• CSV-Export (ab STARTER-Plan)
• Event-Details: Zeitpunkt, Status, Plattform, Fehlermeldung

Automatische Wiederholung

Fehlgeschlagene Events werden automatisch erneut versucht. So gehen keine Daten verloren, selbst wenn eine Plattform vorübergehend nicht erreichbar ist.

Event-Konfiguration

Mit der Event-Konfiguration steuerst du, welche Events an welche Plattformen gesendet werden. Standardmäßig werden alle Events an alle konfigurierten Plattformen gesendet (Full-Funnel Tracking).

Das Opt-Out-Pattern bedeutet: Nur wenn du ein Event für eine bestimmte Plattform explizit deaktivierst, wird es dort nicht mehr gesendet. So behältst du die volle Kontrolle über dein Event-Routing.

Custom Events

Custom Events ermöglichen es dir, eigene Event-Typen zu definieren, die über die Standard-E-Commerce-Events hinausgehen. Jedes Custom Event kann einen eigenen Namen und ein individuelles Plattform-Mapping erhalten.

Pro Shop können maximal 20 Custom Events erstellt werden. Event-Namen müssen alphanumerisch sein (inkl. Underscore, max. 64 Zeichen). Die Zustellung erfolgt über die bestehenden Platform-Clients. Hinweis: Snapchat erlaubt maximal 5 Custom Events.

Custom Events per API auslösen

Sobald ein Custom Event in der App definiert ist, kannst du es per Public REST API über POST /api/v1/events auslösen — mit demselben Event-Namen, den du im Wizard vergeben hast.

Details siehe Sektion „Public REST API“. Public REST API

Offline-Abschlüsse

Offline-Abschlüsse sind Verkäufe, die außerhalb des Shopify-Checkouts zustande kommen — typischerweise per Telefon, E-Mail oder Vor-Ort-Termin. Mit ShopiPixel erfasst du diese Deals im Dashboard und sendest sie als Offline-Conversions an deine Werbeplattformen, damit dort die Kampagnen-Optimierung auch B2B-Umsatz berücksichtigt.

Abschlüsse erfassen

Im ShopiPixel-Dashboard unter „Offline-Abschlüsse“ kannst du Deals manuell anlegen oder per CSV-Upload in Batches importieren. Pro Abschluss erfasst du Betrag, Währung, Abschluss-Datum, optional eine Click-ID (gclid, fbclid, msclkid, ttclid, epik, scid, liFatId, wbraid oder gbraid) sowie E-Mail und Telefonnummer des Kunden für die pseudonymisierte Zuordnung.

Click-ID-Matching

Klickt ein Interessent vor dem Deal-Abschluss auf eine Anzeige, hängt die jeweilige Plattform eine eindeutige Click-ID an die Landing-Page-URL. ShopiPixel speichert die Click-ID beim Erstkontakt (Lead Capture) bis zu 90 Tage. Beim Anlegen des Offline-Abschlusses wird die passende Click-ID automatisch zugeordnet, sodass die Plattformen den Offline-Umsatz der ursprünglichen Kampagne zurechnen können.

Enhanced Matching — Kalt-Abschlüsse ohne Click-ID

Wenn kein vorheriger Anzeigen-Klick stattgefunden hat (z.B. telefonische Erstkontakte, Empfehlungen, Messe-Leads), werden zusätzlich die gehashten Kontaktdaten des Kunden an die Werbeplattform übermittelt. Die Plattform gleicht den Hash mit ihrer eigenen Nutzer-Datenbank ab und ordnet den Deal dem passenden Nutzerprofil zu. Dabei verlässt der Klartext niemals den Server — nur der irreversible Hashwert wird übertragen. Rechtsgrundlage ist das berechtigte Interesse nach Art. 6 Abs. 1 lit. f DSGVO; Details stehen in der Datenschutzerklärung und im AVV.

Lookback-Fenster pro Plattform

Jede Werbeplattform hat ein eigenes Attribution-Window. Deals, die später als das Plattform-Limit nach dem ursprünglichen Klick geschlossen werden, werden dort plattform-seitig verworfen — ShopiPixel filtert solche Deals bereits vor dem Versand:

Event-Trigger

Mit Event-Triggern verknüpfst du eigene Datenpunkte (z.B. B2B-Demo-Anfragen, Newsletter-Abschlüsse, Custom-Workflow-Schritte) mit plattform-spezifischen Event-Codes. Die Einrichtung läuft per No-Code-Wizard direkt im Dashboard — ohne Code-Änderungen in deinem Shop.

Unterstützte Trigger-Typen

Event-Trigger können aus verschiedenen Quellen ausgelöst werden:

• HMAC-Token-API — Sende POST-Requests an /api/events/trigger mit signiertem Token — ideal für externe Systeme wie CRM, Ticket-Software oder Event-Plattformen.
• Shopify-Webhook-Mapping — Mappe bestehende Shopify-Webhook-Topics wie orders/create oder checkouts/create auf deine Custom Events. Jeder Webhook-Aufruf triggert automatisch das verknüpfte Event.
• Shopify Flow Action — Nutze ShopiPixel als Custom Action direkt im Shopify-Flow-Editor (nur Shopify Plus). Details im Abschnitt Shopify Flow Action.

Fünf-Schritt-Wizard

Öffne im Dashboard unter Einstellungen → Event-Trigger den Wizard und folge fünf Schritten:

1. 1. Basics — Name und Beschreibung
   Lege Event-Namen (alphanumerisch, max. 64 Zeichen) und Beschreibung fest.
2. 2. Plattform-Event-Picker
   Wähle pro aktiver Werbeplattform das passende offizielle Event — z.B. Lead bei Meta, eine Conversion-Action bei Google Ads, ein Conversion Goal bei Microsoft Ads. Die Liste wird live aus den jeweiligen Plattform-APIs geladen.
3. 3. Smart-Default-Matching
   ShopiPixel schlägt automatisch passende Plattform-Events auf Basis des Event-Namens vor (Fuzzy-Match mit deutsch-englischer Synonym-Liste). Du kannst die Vorschläge per Klick übernehmen oder überschreiben.
4. 4. Trigger-Konfiguration
   Wähle den Trigger-Typ (API-Token, Webhook-Mapping oder Flow-Action) und bei API-Triggern: generiere den HMAC-Token für dein externes System.
5. 5. Review und Speichern
   Überprüfe die Payload-Vorschau pro Plattform und speichere. Das Event ist sofort aktiv und wird bei jedem Trigger an alle verknüpften Plattformen gemeldet.

Platform-Event-Picker

Für jede der neun unterstützten Plattformen (Meta mit 17 Standard-Events, Google Ads GAQL-Conversion-Actions inkl. MCC-Support, Microsoft Ads Conversion Goals, TikTok 14 Events, Pinterest 14 Events, Snapchat 16 Events, LinkedIn Lead-Forms + 7 Standard-Events, Klaviyo Metrics) kannst du das passende offizielle Event aus einem Dropdown wählen. Die Event-Kataloge werden für eine Stunde gecached, damit die Wizard-UI schnell lädt.

Smart-Defaults und Vorschau

Ein eingebauter Fuzzy-Match-Algorithmus (Levenshtein-basiert) gleicht deinen Event-Namen gegen eine deutsch-englische Synonym-Liste ab und schlägt automatisch die passende Plattform-Zuordnung vor. Pro Plattform zeigt der Wizard eine Vorschau der generierten Payload, damit du vor dem Speichern sehen kannst, wie der Event bei Meta, Google Ads & Co. ankommen wird.

Webhook-Mapping

Webhook-Mapping verknüpft Shopify-Webhook-Topics mit deinen Custom Events pro Plattform. Sobald Shopify den Webhook auslöst, dispatcht ShopiPixel das verknüpfte Event automatisch an alle konfigurierten Werbeplattformen — ohne dass du zusätzlich Code im Shop verändern musst.

Wie funktioniert das Mapping?

Im Dashboard unter Einstellungen → Event-Trigger → Webhooks legst du pro Shopify-Topic fest, welches Custom Event ausgelöst werden soll. Mehrere Mappings pro Topic sind möglich — zum Beispiel kann orders/create sowohl ein „B2B-Deal-Geschlossen“-Event als auch ein „Newsletter-Opt-In“-Event auslösen. Die Zuordnungen werden fünf Minuten im Redis-Cache gehalten, damit Änderungen zügig aktiv werden, aber der Webhook-Pfad nicht ausgebremst wird.

Unterstützte Shopify-Topics

Aktuell stehen neun Shopify-Webhook-Topics als Trigger zur Verfügung:

• orders/create — Neue Bestellung wurde angelegt
• orders/updated — Bestehende Bestellung wurde aktualisiert
• orders/cancelled — Bestellung wurde storniert
• orders/fulfilled — Bestellung wurde vollständig versendet
• checkouts/create — Checkout wurde gestartet
• carts/create — Warenkorb wurde erstellt
• customers/create — Neuer Kunden-Account wurde angelegt

Limits

Pro Shop sind maximal 20 Webhook-Mappings aktiv. Mehrere Mappings können sich ein Topic teilen — jeder Mapping-Eintrag wird eigenständig dispatched. Inaktive Mappings zählen nicht gegen das Limit.

Shopify Flow Action

ShopiPixel erscheint als Custom Action direkt im Shopify-Flow-Editor. Damit kannst du Events aus beliebigen Shopify-Flow-Workflows an ShopiPixel senden — ohne HMAC-Token oder API-Konfiguration. Die komplette Event-Pipeline inklusive Platform-Router, Consent-Checks und Rate-Limiting greift automatisch.

Voraussetzungen

Shopify Flow ist nur auf dem Shopify-Plus-Plan verfügbar. Zusätzlich benötigst du den ShopiPixel Enterprise-Plan. Beide Bedingungen werden beim Aufruf der Action automatisch geprüft — fehlt eine, zeigt der Flow-Editor einen entsprechenden Hinweis.

Einrichtung im Flow-Editor

1. 1. Flow anlegen
   Öffne in deinem Shopify-Admin den Flow-Editor und lege einen neuen Flow an — oder bearbeite einen bestehenden. Wähle einen Trigger (z.B. „Order created“, „Customer tagged“, „Product variant created“).
2. 2. ShopiPixel-Action hinzufügen
   Füge unter „Actions“ die ShopiPixel-Custom-Action hinzu. Sie heißt in der Action-Liste „Send ShopiPixel Event“.
3. 3. Custom Event auswählen
   In der eingebetteten Config-Page wählst du aus einem Dropdown das Custom Event, das bei jeder Flow-Auslösung gesendet werden soll. Die Liste zeigt alle in deinem Shop angelegten Custom Events.

Replay-Schutz und Idempotenz

Damit Shopify-Flow-Retries keine Doppel-Events verursachen, deduppt ShopiPixel anhand der action_run_id für 24 Stunden. Ein identischer Re-Send innerhalb dieser Zeit wird verworfen und mit HTTP 204 quittiert — der Flow läuft weiter, das Event wird aber nur einmal an die Plattformen gesendet.

Attribution

ShopiPixel erkennt, über welche Werbeplattform ein Kunde in deinen Shop gekommen ist. Diese Attribution basiert auf Click-IDs, die automatisch aus Werbe-URLs erfasst werden.

Click-ID Tracking

Wenn ein Kunde auf eine Anzeige klickt, hängt die Plattform eine eindeutige Kennung an die URL. ShopiPixel erfasst diese automatisch:

Automatisches Bridging

Click-IDs aus dem Browser werden automatisch mit Server-Bestelldaten zusammengeführt. Keine manuelle Konfiguration nötig — ShopiPixel übernimmt die Zuordnung vollständig.

Attribution-Modelle

Je nach Plan stehen dir verschiedene Attribution-Modelle zur Verfügung:

• Last Click — Der letzte Klick vor dem Kauf wird gewertet
• First Click — Der erste Kontaktpunkt wird gewertet
• Linear — Alle Kontaktpunkte werden gleichmäßig gewichtet
• Time Decay — Neuere Kontaktpunkte werden stärker gewichtet
• Position Based — Erster und letzter Kontaktpunkt werden betont
• Data Driven — Algorithmische Gewichtung basierend auf deinen Daten

Customer Journey

Die Customer Journey zeigt den vollständigen Weg deiner Kunden vom ersten Kontakt bis zum Kauf. So erkennst du, welche Touchpoints zum Kauf führen und wo Optimierungspotenzial liegt.

Funnel-Flow

Der Funnel-Flow visualisiert die Stationen: Seitenaufruf → Produktansicht → Warenkorb → Checkout → Kauf. An jeder Stufe siehst du die Absprungrate und kannst Schwachstellen in deinem Shop identifizieren. Du findest den Funnel im Dashboard unter dem Conversion Funnel Widget.

Einzelne Journeys analysieren

Im Attribution-Bereich kannst du einzelne Bestellungen öffnen und den vollständigen Pfad des Kunden nachvollziehen: Über welche Plattform kam der erste Kontakt? Welche Click-ID wurde verwendet? Wie lange dauerte der Kaufprozess? Diese Informationen helfen dir, deine Kampagnen gezielt zu optimieren.

Multi-Touchpoint-Analyse

Bei mehreren Touchpoints (z.B. erst Facebook-Klick, dann Google-Suche, dann direkter Besuch) zeigt ShopiPixel alle beteiligten Plattformen chronologisch an — mit Zeitstempel und Click-ID. So verstehst du die vollständige Customer Journey über mehrere Kanäle hinweg.

Ad Spend & ROAS

ShopiPixel kann Werbeausgaben von deinen verbundenen Plattformen importieren, damit du den Return on Ad Spend (ROAS) direkt im Dashboard siehst — ohne zwischen verschiedenen Tools wechseln zu müssen.

Werbekonten verbinden

Die Verbindung läuft über die gleichen Credentials, die du bereits für das Tracking eingerichtet hast. Bei Meta wird zusätzlich die Ad Account ID benötigt, bei Google Ads die Customer ID. Die Werbeausgaben werden über die jeweilige Plattform-API abgerufen.

Import-Zeitplan

Die Werbeausgaben werden mindestens einmal täglich aktualisiert. Je nach Plattform können die Daten mit einer Verzögerung von bis zu 24 Stunden eintreffen, da die Plattformen ihre Ausgabendaten zeitversetzt bereitstellen.

ROAS-Berechnung

ROAS = Umsatz / Werbeausgaben. Ein ROAS von 3,0 bedeutet: Für jeden ausgegebenen Dollar kommen 3 Dollar Umsatz zurück. Im Dashboard siehst du den ROAS pro Plattform, Kampagne und Zeitraum. Der Kampagnen-ROAS basiert auf den von der jeweiligen Werbeplattform nach deren eigener Attributionslogik gemeldeten Conversion-Werten (plattform-attribuiert) und kann daher von den im Funnel-Dashboard ausgewiesenen Werten abweichen. Verfügbar ab dem Scale-Plan.

Alerts

Alerts benachrichtigen dich automatisch, wenn etwas Wichtiges passiert — damit du nicht ständig das Dashboard im Blick haben musst.

Regeltypen

Du kannst verschiedene Alert-Regeln definieren:

• Volumen-Alerts — z.B. plötzlicher Rückgang der Events um mehr als 50%
• Fehler-Alerts — z.B. Plattform nicht erreichbar, Credential abgelaufen
• Billing-Alerts — z.B. Order-Limit bei 80% erreicht
• Performance-Alerts — z.B. Event Match Quality unter 6.0

Benachrichtigungskanäle

Alerts können als In-App-Banner, per E-Mail oder als Webhook zugestellt werden. System-kritische Alerts (z.B. Pixel-Ausfall, Plattform-Fehler) sind standardmäßig aktiv und können nicht deaktiviert werden.

Consent-Dashboard

Das Consent-Dashboard zeigt dir die Einwilligungsraten deiner Shop-Besucher und deren Auswirkung auf deine Tracking-Datenqualität. Verfügbar ab dem Growth-Plan.

Consent-Raten

Sieh auf einen Blick, wie viele deiner Besucher Tracking akzeptieren — aufgeschlüsselt nach Plattform und Zeitraum. So erkennst du, ob ein neues Cookie-Banner-Design die Opt-In-Rate verbessert hat.

Datenschutzfreundliche Berichterstattung

Alle Daten im Consent-Dashboard werden ohne personenbezogene Informationen dargestellt. Du siehst aggregierte Raten und Trends, keine individuellen Nutzerprofile.

Event-Latenz-Monitoring

Überwache die Latenz deiner Tracking-Events in Echtzeit — von der Erfassung bis zur erfolgreichen Zustellung an die Werbeplattform. Verfügbar ab dem Growth-Plan.

Latenz-Metriken

Für jede Plattform siehst du die durchschnittliche Event-Latenz mit Trend-Anzeige. So erkennst du sofort, wenn eine Plattform langsamer reagiert als üblich oder Zustellprobleme auftreten.

Proaktive Warnungen

Bei ungewöhnlich hoher Latenz oder wiederholt fehlgeschlagenen Zustellungen wirst du automatisch benachrichtigt. So kannst du eingreifen, bevor deine Datenqualität beeinträchtigt wird.

Token-Verwaltung

Die meisten Platform-Tokens sind dauerhaft gültig. Ausnahmen sind Pinterest (30 Tage) und LinkedIn (60 Tage). ShopiPixel warnt dich rechtzeitig per E-Mail.

Token-Laufzeiten

Meta, Google Analytics 4, TikTok, Google Ads, Snapchat und Klaviyo verwenden dauerhaft gültige Tokens. Microsoft Ads nutzt OAuth Refresh Tokens, die unbegrenzt gültig bleiben, solange die Berechtigung in ads.microsoft.com nicht widerrufen wird. Pinterest Access Tokens laufen nach 30 Tagen ab, LinkedIn Access Tokens nach 60 Tagen. Bei diesen Plattformen musst du den Token regelmäßig erneuern.

Automatische Warnungen

ShopiPixel überwacht die Gültigkeit deiner Tokens und sendet dir rechtzeitig eine E-Mail-Warnung, bevor ein Token abläuft. So kannst du den Token erneuern, bevor das Tracking unterbrochen wird. Die Warnungen sind in allen Plänen enthalten.

Audience Sync

Mit Audience Sync kannst du Kundensegmente an Werbeplattformen senden, um Custom Audiences, Customer Match Listen und Customer Lists zu erstellen. Unterstützt werden Meta, Google Ads, TikTok, Pinterest, Microsoft Ads und Snapchat. In die Segmente fließen nur Käufer ein, für die du als Shop-Betreiber eine Marketing-Einwilligung über dein Cookie-Banner eingeholt hast; der Abgleich wirkt ausschließlich vorwärts ab Aktivierung.

Meta Custom Audiences

Sende pseudonymisierte Kundendaten (gehashte E-Mail, Telefonnummer) an Meta, um Custom Audiences für Facebook und Instagram zu erstellen. Die Daten werden SHA256-gehasht übertragen — Meta sieht niemals die Klartextdaten. Custom Audiences ermöglichen Lookalike Audiences und gezielteres Retargeting.

Google Ads Customer Match

Erstelle Customer Match Listen in Google Ads mit gehashten Kundendaten. Google verwendet diese für ähnliche Zielgruppen und bessere Gebotsoptimierung. Enhanced Conversions müssen aktiviert sein.

TikTok Custom Audiences

Übertrage gehashte Kundendaten an TikTok, um Custom Audiences für TikTok Ads zu erstellen. TikTok nutzt diese Segmente für Lookalike Audiences und präziseres Retargeting auf der Plattform.

Pinterest Customer Lists

Erstelle Customer Lists in Pinterest mit gehashten Kundendaten. Pinterest verwendet diese für Actalike Audiences und gezieltere Kampagnen-Aussteuerung auf Pinterest.

Microsoft Ads Customer Lists

Erstelle Customer-List-Audiences in Microsoft Ads mit gehashten Kundendaten. Microsoft Advertising nutzt diese für Similar Audiences und eine gezieltere Kampagnen-Aussteuerung.

Snapchat Segments

Übertrage gehashte Kundendaten an Snapchat, um Customer Segments für Snapchat Ads zu erstellen. Snapchat nutzt diese Segmente für Lookalike Audiences und präziseres Retargeting.

Hashing & Datenschutz

Alle personenbezogenen Daten werden vor der Übertragung SHA256-gehasht (One-Way-Hash). Die Plattformen erhalten ausschließlich gehashte Werte und können die Originaldaten nicht rekonstruieren. E-Mail-Adressen werden vor dem Hashing normalisiert (Kleinschreibung, Leerzeichen entfernt). Telefonnummern werden in E.164-Format konvertiert.

Custom Reports

Erstelle individuelle Reports, die genau die Daten zeigen, die für dein Business relevant sind.

Verfügbare Metriken

Wähle aus Metriken wie Umsatz, Conversions, gesendete Events, Erfolgsrate, durchschnittlicher Bestellwert (AOV), ROAS, Event Match Quality (EMQ) und mehr. Bis zu 10 Metriken können in einem Report kombiniert werden.

Dimensionen & Filter

Gruppiere deine Daten nach Zeitraum, Plattform, Event-Typ, Produkt oder Land. Zusätzlich kannst du Filter setzen, um den Report auf bestimmte Plattformen, Event-Typen oder Zeiträume einzuschränken.

Schedule & CSV-Export

Richte einen automatischen Versand ein — täglich, wöchentlich oder monatlich per E-Mail als CSV-Anhang. Alternativ kannst du Reports jederzeit manuell als CSV oder XLSX exportieren (ab Starter-Plan).

Kohortenanalyse & LTV

Die Kohortenanalyse zeigt, wie sich Kundengruppen über die Zeit verhalten. So erkennst du Muster in der Kundenbindung und identifizierst die wertvollsten Akquisitionskanäle.

Retention-Heatmap lesen

Die Heatmap zeigt Kohorten (Gruppen von Erstkäufern aus einem bestimmten Zeitraum) vertikal und die Folgemonate horizontal. Die Farbe zeigt, wie viel Prozent der Kohorte im jeweiligen Monat erneut gekauft haben. Dunklere Farben = höhere Retention. So erkennst du auf einen Blick, ob deine Kundenbindung über die Zeit stabil bleibt oder abnimmt.

Lifetime Value (LTV) verstehen

Die LTV-Kurve zeigt den kumulierten Umsatz pro Kohorte über die Zeit. Vergleiche verschiedene Kohorten, um zu sehen, welche Akquisitionskanäle oder Kampagnen langfristig die wertvollsten Kunden bringen. Ein steiler Anstieg der LTV-Kurve in den ersten 90 Tagen deutet auf hohe Wiederkaufbereitschaft hin.

Data Warehouse Export

Exportiere deine Tracking-Daten für externe Analysen in dein Data Warehouse oder BI-Tool.

Destinations

ShopiPixel unterstützt den Export via Custom Webhook (Echtzeit-Stream an beliebige Endpoints wie BigQuery, Snowflake oder Redshift), manuellen CSV/XLSX-Download und geplanten automatischen Export per E-Mail.

Formate

CSV und XLSX Formate stehen zur Verfügung. Der XLSX-Export enthält zusätzlich eine Summary-Zeile, AutoFilter und eingefrorene Kopfzeile für einfachere Analyse in Excel oder Google Sheets.

PII-Stripping

Beim Export werden personenbezogene Daten (PII) standardmäßig entfernt oder pseudonymisiert. E-Mail-Adressen und Telefonnummern werden als SHA256-Hash exportiert. IP-Adressen werden nicht exportiert. So kannst du Daten bedenkenlos in externe Systeme übertragen.

Creative Analytics

Creative Analytics zeigt dir, welche Werbeanzeigen auf Creative-Ebene am besten performt — aufgeschlüsselt nach Bild, Video oder Text.

Verfügbare Metriken

Für jedes Creative siehst du Revenue, Conversions und Conversion-Rate. Die Daten basieren auf echten Server-Side Conversions und sind damit zuverlässiger als reine Plattform-Schätzungen.

Creative Fatigue erkennen

ShopiPixel zeigt dir Trend-Verläufe pro Creative über die Zeit. Wenn ein Creative an Performance verliert (sinkende Conversion-Rate und rückläufige Conversions im Zeitverlauf), erkennst du das frühzeitig und kannst rechtzeitig neue Varianten testen.

Marketing Mix Modelling

Marketing Mix Modelling (MMM) analysiert statistisch, wie verschiedene Marketing-Kanäle zusammenwirken und zum Gesamtumsatz beitragen.

Wie funktioniert MMM?

MMM nutzt historische Daten (Werbeausgaben, Umsatz, Saisonalität, externe Faktoren) und berechnet den marginalen Beitrag jedes Kanals. Im Gegensatz zur Click-Attribution werden auch indirekte Effekte wie Brand Awareness und kanalübergreifende Wechselwirkungen berücksichtigt.

Budget-Simulationen

Simuliere verschiedene Budget-Verteilungen und sieh, wie sich Veränderungen voraussichtlich auf deinen Umsatz auswirken. So triffst du datengestützte Budget-Entscheidungen statt nach Bauchgefühl.

Multi-Store Management mit Consent-Flow

Das Agency-Dashboard verwaltet bis zu 3 verknüpfte Shops — nach aktiver, zweistufiger Zustimmung des jeweiligen Shop-Inhabers. Du handelst im Impersonation-Kontext, nur innerhalb der delegierten Berechtigungen.

Zweistufiger Opt-In-Flow

1. Als Enterprise-Owner lädst du einen Shop ein und wählst den Link-Typ: 'Agentur-verwaltet' (AGENCY_MANAGED) für Dienstleister oder 'Eigene Organisation' (SELF_OWNED) für Multi-Shop-Betreiber. 2. Der Shop-Inhaber öffnet den App-Dialog, sieht alle geteilten Datenkategorien und wählt einzeln aus 14 Berechtigungen. Erst nach aktiver Bestätigung entsteht die Verknüpfung. Rechtsgrundlage ist die Einwilligung des Shop-Inhabers nach Art. 6 Abs. 1 lit. a DSGVO; die Einwilligung wird nach Art. 7 Abs. 1 DSGVO protokolliert und kann jederzeit nach Art. 7 Abs. 3 DSGVO widerrufen werden.

14 granulare Capabilities

Der Shop-Inhaber delegiert einzelne Aufgaben: Statistik-Lesen (view_analytics — Pflicht), Plattform-Konfiguration (manage_platforms, manage_event_config), Tracking-Einstellungen (manage_tracking_settings), Integrationen (manage_gtm, manage_headless, manage_ad_accounts), Features (manage_audiences, manage_alerts, manage_reports, manage_domain) sowie Daten-Zugriff (download_data, upload_data, access_debug). Events der verknüpften Shops zählen auf das Owner-Quota (100K). Der Owner-Plan wird verwendet (ACCEPTED mit usesOwnerBilling).

Datenisolierung & Audit-Log

Jeder Shop behält eigene Verschlüsselungsschlüssel, eigene Credentials und eigene Events. Der Agency-Owner sieht nur Daten innerhalb der delegierten Berechtigungen. Jede Aktion landet im Audit-Log des Ziel-Shops — vollständig nachvollziehbar. Der Shop-Inhaber kann die Verknüpfung jederzeit beenden (Art. 7 Abs. 3 DSGVO); bei Widerruf fällt ein ausschließlich über die Agency bezahlter Shop automatisch auf den FREE-Plan zurück.

Custom Domain Tracking

Custom Domain Tracking verbessert die Datenqualität, indem Events über deine eigene Subdomain gesendet werden.

Warum Custom Domain?

Browser wie Safari (ITP) und Firefox (ETP) beschränken Cookies von Drittanbieter-Domains. Wenn du Events über deine eigene Subdomain (z.B. track.dein-shop.de) sendest, werden Cookies als First-Party behandelt. Das verlängert die Cookie-Lebensdauer und verbessert die Zuordnung von Conversions zu Nutzern.

Einrichtung

Erstelle einen CNAME-Eintrag in deinem DNS, der auf die ShopiPixel-Infrastruktur zeigt. SSL-Zertifikate werden automatisch verwaltet. Die Umstellung ist ohne Datenverlust möglich.

Headless Commerce SDK

Das Headless SDK ermöglicht Server-to-Server Event-Tracking für Shops mit Headless-Architektur.

Wann brauchst du das SDK?

Wenn dein Storefront nicht auf Shopifys Standard-Theme basiert, sondern eine Headless-Architektur nutzt (Hydrogen, Next.js, Gatsby, Custom React/Vue), läuft das Shopify Web Pixel nicht im Browser. Das SDK übernimmt die Event-Übermittlung direkt vom Server.

Das SDK ist für Browser-basiertes Tracking aus deinem eigenen Storefront. Wenn du Events vom Server senden möchtest, ist die Public REST API der bessere Weg — siehe Sektion „Public REST API“ weiter unten.

Voraussetzungen

• Scale-Plan oder höher (das SDK ist im Enterprise-Plan ebenfalls enthalten)
• Ein API-Key, den du in der App unter /app/settings/headless erzeugst
• Schreibrechte für den verknüpften Shop — der Key landet nur einmal im Klartext im Browser, bei späteren Aufrufen liegt nur der Hash in der DB

Schritt 1: API-Key erzeugen

1. Öffne im ShopiPixel-Dashboard /app/settings/headless
2. Klicke auf „API-Key generieren“ und vergib eine sprechende Bezeichnung (z.B. „Hydrogen Production“)
3. Kopiere den angezeigten Key sofort — er wird nur einmal im Klartext gezeigt

Schritt 2: Snippet einbinden

Lade das SDK asynchron und initialisiere es mit deinem API-Key. Das SDK puffert Events in einer Queue, bis es initialisiert ist — frühe Aufrufe gehen damit nicht verloren.

<script src="https://app.shopipixel.de/api/sdk/js" defer></script>
<script>
  window.ShopiPixel = window.ShopiPixel || {};
  ShopiPixel.queue = ShopiPixel.queue || [];
  ShopiPixel.track = function(e, d) { ShopiPixel.queue.push([e, d]); };
  document.addEventListener('DOMContentLoaded', function() {
    ShopiPixel.init('sp_xxxxxxxxxxxx');
  });
</script>

Schritt 3: Events senden

Verwende die Helper-Methoden für die Standard-Events oder die generische track()-Funktion für eigene Event-Namen.

• ShopiPixel.trackPageView()
• ShopiPixel.trackViewContent({ ... })
• ShopiPixel.trackAddToCart({ ... })
• ShopiPixel.trackInitiateCheckout({ ... })
• ShopiPixel.trackPurchase({ ... })
• ShopiPixel.trackSearch({ ... })
• Für ViewCategory, CompleteRegistration oder Custom Events: ShopiPixel.track('ViewCategory', { categoryId: 'shoes' })

Public REST API

Die Public REST API ist die offizielle Server-zu-Server-Schnittstelle von ShopiPixel. Sie erlaubt dir, Events direkt aus deinen eigenen Systemen zu senden, vergangene Events abzurufen und aggregierte Statistiken zu lesen — ohne Umweg über Browser oder Webhooks.

Für wen ist die API?

Die API richtet sich an Enterprise-Kunden, die Server-Integrationen mit eigenen Backends, ERP- oder CRM-Systemen aufbauen, Conversion-Daten in Data-Warehouses spiegeln oder programmgesteuert Reports generieren möchten.

Schritt 1: API-Key erzeugen

1. Öffne im ShopiPixel-Dashboard /app/settings/api
2. Wähle die benötigten Berechtigungen aus (events:read, events:write, stats:read — standardmäßig sind alle drei vorausgewählt)
3. Optional: Ablaufdatum setzen, um Keys mit begrenzter Gültigkeit zu erzeugen
4. Klicke auf „Key erzeugen“ und kopiere den angezeigten Key sofort — er wird nur einmal im Klartext angezeigt

Schritt 2: Authentifizierung

Sende den API-Key bei jedem Request als Bearer-Token im Authorization-Header.

Authorization: Bearer sp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Verfügbare Endpoints

GET /api/v1/events — Events lesen

Liefert deine Events mit Cursor-Pagination zurück. Klartext-PII (E-Mail, Telefon, Vor-/Nachname) und Click-IDs werden bewusst nicht zurückgegeben — nur Event-Metadaten und das customData-Objekt, das du selbst beim POST mitgeschickt hast.

Query-Parameter

curl -X GET "https://app.shopipixel.de/api/v1/events?limit=50&eventName=Purchase" \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx"

const response = await fetch(
  "https://app.shopipixel.de/api/v1/events?limit=50&eventName=Purchase",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sp_xxxxxxxxxxxx",
    },
  },
);

if (!response.ok) {
  throw new Error(`API error: ${response.status} ${response.statusText}`);
}

const { data, pagination } = await response.json();
console.log(`${data.length} Events geladen, hasMore=${pagination.hasMore}`);

import requests

response = requests.get(
    "https://app.shopipixel.de/api/v1/events",
    params={"limit": 50, "eventName": "Purchase"},
    headers={"Authorization": "Bearer sp_xxxxxxxxxxxx"},
)
response.raise_for_status()

payload = response.json()
print(f"{len(payload['data'])} Events geladen, hasMore={payload['pagination']['hasMore']}")

<?php
$ch = curl_init("https://app.shopipixel.de/api/v1/events?limit=50&eventName=Purchase");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new Exception("API error: HTTP $httpCode");
}

$payload = json_decode($response, true);
echo count($payload["data"]) . " Events geladen, hasMore=" . var_export($payload["pagination"]["hasMore"], true);

Response-Beispiel

{
  "data": [
    {
      "eventId": "purchase_1730000000_abc",
      "eventName": "Purchase",
      "timestamp": "2026-05-08T10:30:00.000Z",
      "source": "API",
      "orderId": "ORDER-123",
      "isRecurring": false,
      "isTest": false,
      "platforms": { "meta": true, "ga4": true },
      "customData": {
        "value": 49.99,
        "currency": "EUR",
        "orderId": "ORDER-123"
      }
    }
  ],
  "pagination": { "nextCursor": "cm123abc", "hasMore": true }
}

Hinweis: Klartext-PII (E-Mail, Telefon, Vor-/Nachname) und Click-IDs (fbp, fbc, gclid usw.) werden nicht zurückgegeben — Datenminimierung nach Art. 5 Abs. 1 Buchst. c DSGVO. Das customData-Objekt wird unverändert zurückgegeben (1:1 wie beim POST mitgesendet) — sende daher beim POST keine Endkunden-PII in customData (z.B. keine E-Mail, kein Klarname). Geschäftsdaten wie value, currency, orderId, contentIds, numItems sind die korrekten Felder.

POST /api/v1/events — Events erstellen

Sende ein einzelnes Event oder bis zu 100 Events in einem Bulk-Request. Bei Bulk-Requests werden erfolgreiche und fehlgeschlagene Events einzeln in der Response gemeldet (Partial Success).

Einzelnes Event

curl -X POST https://app.shopipixel.de/api/v1/events \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "Purchase",
    "eventId": "purchase_1730000000_abc",
    "eventTime": 1730000000,
    "userData": {
      "email": "kunde@example.com",
      "phone": "+493099999999"
    },
    "customData": {
      "currency": "EUR",
      "value": 49.99,
      "orderId": "ORDER-123",
      "contents": [
        { "id": "prod-1", "quantity": 1, "itemPrice": 49.99 }
      ]
    }
  }'

const event = {
  eventName: "Purchase",
  eventId: `purchase_${Date.now()}_${crypto.randomUUID().slice(0, 8)}`,
  eventTime: Math.floor(Date.now() / 1000),
  userData: {
    email: "kunde@example.com",
    phone: "+493099999999",
  },
  customData: {
    currency: "EUR",
    value: 49.99,
    orderId: "ORDER-123",
    contents: [{ id: "prod-1", quantity: 1, itemPrice: 49.99 }],
  },
};

const response = await fetch("https://app.shopipixel.de/api/v1/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sp_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(event),
});

const result = await response.json();
console.log(`Event ${result.eventId} verarbeitet (duplicate=${result.duplicate})`);

import requests
import time
import uuid

event = {
    "eventName": "Purchase",
    "eventId": f"purchase_{int(time.time())}_{uuid.uuid4().hex[:8]}",
    "eventTime": int(time.time()),
    "userData": {
        "email": "kunde@example.com",
        "phone": "+493099999999",
    },
    "customData": {
        "currency": "EUR",
        "value": 49.99,
        "orderId": "ORDER-123",
        "contents": [{"id": "prod-1", "quantity": 1, "itemPrice": 49.99}],
    },
}

response = requests.post(
    "https://app.shopipixel.de/api/v1/events",
    json=event,
    headers={
        "Authorization": "Bearer sp_xxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
)
response.raise_for_status()

result = response.json()
print(f"Event {result['eventId']} verarbeitet (duplicate={result['duplicate']})")

<?php
$event = [
    "eventName" => "Purchase",
    "eventId" => "purchase_" . time() . "_" . bin2hex(random_bytes(4)),
    "eventTime" => time(),
    "userData" => [
        "email" => "kunde@example.com",
        "phone" => "+493099999999",
    ],
    "customData" => [
        "currency" => "EUR",
        "value" => 49.99,
        "orderId" => "ORDER-123",
        "contents" => [
            ["id" => "prod-1", "quantity" => 1, "itemPrice" => 49.99],
        ],
    ],
];

$ch = curl_init("https://app.shopipixel.de/api/v1/events");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($event));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
    "Content-Type: application/json",
]);

$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);

echo "Event {$result["eventId"]} verarbeitet (duplicate=" . var_export($result["duplicate"], true) . ")";

Bulk-Insert (max. 100 Events)

Schicke ein Array von Events. Optimal sind ~50 Events pro Request — größer geht, aber die Latenz pro Request steigt linear.

curl -X POST https://app.shopipixel.de/api/v1/events \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    { "eventName": "PageView",         "eventId": "pv_001",  "eventTime": 1730000000 },
    { "eventName": "ViewContent",      "eventId": "vc_001",  "eventTime": 1730000010, "customData": { "contentIds": ["prod-1"] } },
    { "eventName": "AddToCart",        "eventId": "atc_001", "eventTime": 1730000020, "customData": { "value": 49.99, "currency": "EUR", "contentIds": ["prod-1"] } },
    { "eventName": "InitiateCheckout", "eventId": "ic_001",  "eventTime": 1730000030, "customData": { "value": 49.99, "currency": "EUR" } },
    { "eventName": "Purchase",         "eventId": "p_001",   "eventTime": 1730000040, "customData": { "value": 49.99, "currency": "EUR", "orderId": "ORDER-123" } }
  ]'

const events = [
  { eventName: "PageView",         eventId: "pv_001",  eventTime: 1730000000 },
  { eventName: "ViewContent",      eventId: "vc_001",  eventTime: 1730000010, customData: { contentIds: ["prod-1"] } },
  { eventName: "AddToCart",        eventId: "atc_001", eventTime: 1730000020, customData: { value: 49.99, currency: "EUR", contentIds: ["prod-1"] } },
  { eventName: "InitiateCheckout", eventId: "ic_001",  eventTime: 1730000030, customData: { value: 49.99, currency: "EUR" } },
  { eventName: "Purchase",         eventId: "p_001",   eventTime: 1730000040, customData: { value: 49.99, currency: "EUR", orderId: "ORDER-123" } },
];

const response = await fetch("https://app.shopipixel.de/api/v1/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sp_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(events),
});

const { successCount, failedCount, results } = await response.json();
console.log(`${successCount}/${events.length} Events erfolgreich, ${failedCount} fehlgeschlagen`);

// Partial-Success-Handling
for (const result of results) {
  if (!result.success) {
    console.warn(`Event ${result.eventId} failed: ${result.error}`);
  }
}

import requests

events = [
    {"eventName": "PageView",         "eventId": "pv_001",  "eventTime": 1730000000},
    {"eventName": "ViewContent",      "eventId": "vc_001",  "eventTime": 1730000010, "customData": {"contentIds": ["prod-1"]}},
    {"eventName": "AddToCart",        "eventId": "atc_001", "eventTime": 1730000020, "customData": {"value": 49.99, "currency": "EUR", "contentIds": ["prod-1"]}},
    {"eventName": "InitiateCheckout", "eventId": "ic_001",  "eventTime": 1730000030, "customData": {"value": 49.99, "currency": "EUR"}},
    {"eventName": "Purchase",         "eventId": "p_001",   "eventTime": 1730000040, "customData": {"value": 49.99, "currency": "EUR", "orderId": "ORDER-123"}},
]

response = requests.post(
    "https://app.shopipixel.de/api/v1/events",
    json=events,
    headers={
        "Authorization": "Bearer sp_xxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
)
response.raise_for_status()
payload = response.json()

print(f"{payload['successCount']}/{len(events)} Events erfolgreich, {payload['failedCount']} fehlgeschlagen")

for result in payload["results"]:
    if not result["success"]:
        print(f"WARN: Event {result['eventId']} failed: {result['error']}")

<?php
$events = [
    ["eventName" => "PageView",         "eventId" => "pv_001",  "eventTime" => 1730000000],
    ["eventName" => "ViewContent",      "eventId" => "vc_001",  "eventTime" => 1730000010, "customData" => ["contentIds" => ["prod-1"]]],
    ["eventName" => "AddToCart",        "eventId" => "atc_001", "eventTime" => 1730000020, "customData" => ["value" => 49.99, "currency" => "EUR", "contentIds" => ["prod-1"]]],
    ["eventName" => "InitiateCheckout", "eventId" => "ic_001",  "eventTime" => 1730000030, "customData" => ["value" => 49.99, "currency" => "EUR"]],
    ["eventName" => "Purchase",         "eventId" => "p_001",   "eventTime" => 1730000040, "customData" => ["value" => 49.99, "currency" => "EUR", "orderId" => "ORDER-123"]],
];

$ch = curl_init("https://app.shopipixel.de/api/v1/events");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($events));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
    "Content-Type: application/json",
]);

$response = curl_exec($ch);
curl_close($ch);
$payload = json_decode($response, true);

echo "{$payload["successCount"]}/" . count($events) . " Events erfolgreich, {$payload["failedCount"]} fehlgeschlagen\n";

foreach ($payload["results"] as $result) {
    if (!$result["success"]) {
        echo "WARN: Event {$result["eventId"]} failed: {$result["error"]}\n";
    }
}

Bei Bulk-Requests wird jedes Event einzeln verarbeitet. Erfolgreiche und fehlgeschlagene Events werden im results-Array gemeldet.

{
  "successCount": 4,
  "failedCount": 1,
  "results": [
    { "eventId": "pv_001",  "success": true,  "duplicate": false, "platforms": { "queued": ["meta", "ga4"], "skipped": [] } },
    { "eventId": "vc_001",  "success": true,  "duplicate": true },
    { "eventId": "atc_001", "success": true,  "duplicate": false, "platforms": { "queued": ["meta", "ga4"], "skipped": [] } },
    { "eventId": "ic_001",  "success": true,  "duplicate": false, "platforms": { "queued": ["meta", "ga4"], "skipped": [] } },
    { "eventId": "p_001",   "success": false, "error": "event_not_found" }
  ]
}

Maximal 100 Events pro Request. Bei größeren Mengen mehrere Requests aufsplitten.

Event-Schema

Jedes Event hat drei Pflichtfelder und drei optionale Felder.

• eventName (Pflicht) — Standard-Event-Name (z.B. „Purchase“) oder Name eines vordefinierten Custom Events
• eventId (Pflicht) — Eindeutige ID pro Event — verwende einen stabilen, geschäftsbezogenen Wert (z.B. „purchase_<orderId>“) für Idempotenz
• eventTime (Pflicht) — Unix-Timestamp in Sekunden, im Fenster [now-86400, now+300] — älter als 24h oder weiter als 5min in der Zukunft → Event wird abgelehnt
• sourceUrl (Optional) — Vollständige URL der Seite, auf der das Event ausgelöst wurde
• userData (Optional) — Kontaktdaten des Endkunden (email, phone, firstName, lastName, …) — Server hashed plattformspezifisch, Klartext verlässt den Server nie
• customData (Optional) — Geschäftsdaten zum Event (currency, value, orderId, contentIds, contents, …)

Response-Flags

Die GET-Response enthält pro Event zwei Klassifizierungs-Flags:

• isRecurring — true bei wiederkehrenden Bestellungen aus Subscription-Apps (Recharge, Bold, Loop, Shopify Subscriptions). Hilfreich für die Trennung von Erst- und Folge-Käufen in Auswertungen.
• isTest — true bei Test-Bestellungen aus Bogus Gateway oder Shopify Payments Test Mode. Test-Käufe inkrementieren keinen Order-Counter und triggern kein Plan-Overage.

Standard-Events

Diese acht Event-Namen sind in ShopiPixel vordefiniert und werden direkt von allen unterstützten Plattformen erkannt:

PageView, ViewContent, ViewCategory, AddToCart, InitiateCheckout, Purchase, Search, CompleteRegistration

Custom Events

Eigene Event-Namen können vorab im Wizard /app/event-triggers/events angelegt werden. Sobald ein Custom Event aktiv ist, kannst du es per /api/v1/events auslösen.

• Maximal 20 Custom Events pro Shop
• Event-Namen alphanumerisch (inkl. Underscore), maximal 64 Zeichen
• Snapchat erlaubt plattformseitig maximal 5 Custom Events

Details siehe Sektion „Custom Events“ weiter oben. Custom Events

GET /api/v1/stats — Statistiken abrufen

Liefert aggregierte Kennzahlen für einen Zeitraum: Umsatz, Conversion-Rate, Conversions pro Plattform und Erfolgsraten der Event-Zustellung. Das Ergebnis ist immer in Shop-Currency normalisiert (Multi-Currency wird zu tagesaktuellen Wechselkursen konvertiert).

Query-Parameter

Hinweis: Bei granularity=hour ist der maximale Zeitraum auf 7 Tage begrenzt — stündliche Aggregate über längere Zeiträume liefern zu viele Datenpunkte für effizientes Reporting.

curl -X GET "https://app.shopipixel.de/api/v1/stats?granularity=day&from=2026-04-01&to=2026-05-01" \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx"

const params = new URLSearchParams({
  granularity: "day",
  from: "2026-04-01",
  to: "2026-05-01",
});

const response = await fetch(
  `https://app.shopipixel.de/api/v1/stats?${params}`,
  {
    method: "GET",
    headers: { "Authorization": "Bearer sp_xxxxxxxxxxxx" },
  },
);

const { summary, timeline, platforms } = await response.json();

console.log(`Umsatz: ${summary.totalRevenue} ${summary.currency}`);
console.log(`Conversions: ${summary.totalConversions}`);
console.log(`Conversion-Rate: ${(summary.conversionRate * 100).toFixed(2)}%`);

import requests

response = requests.get(
    "https://app.shopipixel.de/api/v1/stats",
    params={"granularity": "day", "from": "2026-04-01", "to": "2026-05-01"},
    headers={"Authorization": "Bearer sp_xxxxxxxxxxxx"},
)
response.raise_for_status()

payload = response.json()
summary = payload["summary"]

print(f"Umsatz: {summary['totalRevenue']} {summary['currency']}")
print(f"Conversions: {summary['totalConversions']}")
print(f"Conversion-Rate: {summary['conversionRate'] * 100:.2f}%")

<?php
$query = http_build_query([
    "granularity" => "day",
    "from" => "2026-04-01",
    "to" => "2026-05-01",
]);

$ch = curl_init("https://app.shopipixel.de/api/v1/stats?$query");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
]);

$response = curl_exec($ch);
curl_close($ch);
$payload = json_decode($response, true);
$summary = $payload["summary"];

echo "Umsatz: {$summary["totalRevenue"]} {$summary["currency"]}\n";
echo "Conversions: {$summary["totalConversions"]}\n";
echo "Conversion-Rate: " . number_format($summary["conversionRate"] * 100, 2) . "%\n";

Response-Beispiel

{
  "summary": {
    "totalRevenue": 12450.99,
    "currency": "EUR",
    "totalEvents": 18342,
    "totalConversions": 234,
    "conversionRate": 0.0128,
    "averageOrderValue": 53.21
  },
  "timeline": [
    {
      "date": "2026-05-08",
      "pageViews": 1234,
      "purchases": 23,
      "revenue": 1234.56,
      "currency": "EUR"
    }
  ],
  "platforms": {
    "meta": { "eventsSent": 18342, "successRate": 0.987 }
  }
}

Multi-Currency-Hinweis: Wenn dein Shop Bestellungen in mehreren Währungen erfasst, werden alle Beträge per ECB-Tageskurs in die Shop-Currency konvertiert. Die Response enthält das Feld currency mit der Ziel-Currency.

Rate-Limits

Jeder API-Key hat ein eigenes Rate-Limit-Budget. Server-Caching und Bulk-Operationen helfen, das Budget effizient zu nutzen.

• 1.000 Requests pro Stunde pro API-Key
• Jede Response enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset
• Bei überschrittenem Limit antwortet der Server mit HTTP 429 und einem Retry-After-Header in Sekunden

Häufige Fehler

401 unauthorized

Authorization-Header fehlt, ist falsch formatiert oder enthält einen ungültigen, abgelaufenen oder widerrufenen Key. Aus Sicherheitsgründen wird nicht zwischen den Fällen unterschieden.

403 Permission … required

Der Key hat nicht die nötige Berechtigung für diesen Endpoint. In /app/settings/api die Berechtigungen anpassen oder einen neuen Key erzeugen.

403 Enterprise plan required

Der Shop ist nicht im Enterprise-Plan oder die Subscription ist nicht aktiv. Im Billing-Bereich Plan-Status prüfen.

413 Request body too large

Der Request-Body überschreitet 512 KB. Bei großen Bulk-Requests in mehrere kleinere aufsplitten — empfohlen sind ~50 Events pro Request.

429 Rate limit exceeded

Rate-Limit überschritten. Warte die im Retry-After-Header genannte Zeit ab und sende den Request erneut. Exponential Backoff bei wiederholten 429 nutzen.

Web Pixel & Cookies

Was ist das Web Pixel?

Das ShopiPixel Web Pixel ist eine Shopify-zertifizierte Browser-Extension, die automatisch bei der App-Installation aktiviert wird. Es läuft in Shopifys Strict Sandbox — der höchsten Sicherheitsstufe.

Installation prüfen

Shopify Admin → Einstellungen → Kundenereignisse → ShopiPixel = „Verbunden“

Welche Cookies werden gesetzt

Die folgenden Cookies werden nur mit Einwilligung deiner Kunden gesetzt:

Welche Daten erfasst das Web Pixel

Nur mit gültiger Einwilligung:

• Click-IDs aus Werbe-URLs
• Anonyme Browser-Kennung
• Browser-Typ
• Session-Kennung
• Einwilligungs-Status

Welche Daten werden NICHT erfasst

• Keine IP-Adressen
• Keine personenbezogenen Daten ohne Einwilligung
• Kein Browsing-Verhalten auf anderen Websites
• Kein Fingerprinting

Bekannte Einschränkungen

Datenschutz & DSGVO

Verantwortlichkeit

• Du als Shop-Betreiber bist Verantwortlicher für die Datenverarbeitung (Art. 4 Nr. 7 DSGVO).
• ShopiPixel ist dein Auftragsverarbeiter (Art. 28 DSGVO).
• Ein Auftragsverarbeitungsvertrag (AVV) wird bei Installation der App akzeptiert.

Verarbeitete Daten

Rechtsgrundlagen

• Einwilligung (Art. 6 Abs. 1 lit. a DSGVO, §25 TDDDG) für Browser-Cookies und Pixel-Tracking
• Berechtigtes Interesse (Art. 6 Abs. 1 lit. f DSGVO) für Webhook-basierte Verarbeitung von Bestelldaten zur Conversion-Messung
• Vertragserfüllung (Art. 6 Abs. 1 lit. b DSGVO) für die App-Nutzung selbst

Datenweitergabe

• Events werden an die von dir konfigurierten Werbeplattformen gesendet (Meta, Google, TikTok etc.)
• Dabei können Daten in Drittländer (USA) übermittelt werden — Grundlage: EU-US Data Privacy Framework bzw. Standardvertragsklauseln der jeweiligen Plattform
• ShopiPixel selbst gibt keine Daten an Dritte weiter

Server-Standort

Deutschland — alle Daten werden ausschließlich auf deutschen Servern verarbeitet und gespeichert.

Betroffenenrechte

Deine Kunden haben das Recht auf:

• Auskunft (Art. 15 DSGVO)
• Löschung (Art. 17 DSGVO)
• Berichtigung (Art. 16 DSGVO)
• Einschränkung der Verarbeitung (Art. 18 DSGVO)
• Datenübertragbarkeit (Art. 20 DSGVO)
• Widerspruch (Art. 21 DSGVO)

DSGVO-Anfragen von Endkunden werden automatisch über Shopify-Webhooks verarbeitet. Wenn ein Kunde Auskunft, Löschung oder Datenexport anfordert, leitet Shopify die Anfrage an ShopiPixel weiter — Löschungen werden automatisch an alle verbundenen Plattformen weitergegeben.

Textbaustein für deine Datenschutzerklärung

Den folgenden Text kannst du in deine Datenschutzerklärung übernehmen und an deine Gegebenheiten anpassen:

Weitere Hilfe

Hier findest du Links zu allen Hilfe-Seiten und Ressourcen: