Shopify Integrationsleitfaden

Tajo verbindet Shopify an zwei Stellen mit Brevo. Die Tajo-Shopify-App macht aus Shopify-Webhooks Schreibvorgänge in Brevo, sobald sie eintreffen. Sync-Regeln, die ein Agent baut und ein Mensch freigibt, bringen Datensätze nach Zeitplan nach Brevo. Diese Seite behandelt beides und danach die Shopify-Tools, die Tajo über MCP bereitstellt.

Voraussetzungen

Bevor du mit der Integration beginnst, brauchst du:

• Shopify-Store in einem beliebigen Tarif (Basic, Shopify, Advanced oder Plus)
• Tajo-Konto (Tajo befindet sich im Early Access)
• Brevo-Konto als Ziel der Synchronisierung
• Admin-Zugriff auf deinen Shopify-Store

Schritt 1: Shopify-Store verbinden

Tajo befindet sich im Early Access. Die Shopify-App ist nicht im Shopify App Store gelistet, und es gibt keinen Self-Service-Installationslink. Kontaktiere das Team, um loszulegen. Sobald dein Tajo-Workspace bereit ist:

1. Öffne in Tajo Connections.
2. Gib die myshopify.com-Domain deines Stores ein und wähle Connect Shopify. Shopify zeigt die Scopes, die Tajo anfordert, und leitet dich zurück zu Tajo, sobald du sie genehmigst.
3. Wofür jeder Scope dient und was Tajo zurück nach Shopify schreibt, findest du unter Shopify-Berechtigungen erklärt.

Schritt 2: Was die Tajo-Shopify-App an Brevo sendet

Die App prüft jeden Shopify-Webhook, speichert ihn, stellt ihn in die Warteschlange und verarbeitet ihn sofort. Bei Kunden- und Produktthemen wartet sie vorher etwa vier Sekunden. Es gibt kein Batch-Fenster. Ein fehlgeschlagener Job wird mit Backoff wiederholt.

Webhook-Themen

Die Tajo-Shopify-App abonniert diese Shopify-Webhook-Themen:

Die obligatorischen Datenschutz-Webhooks von Shopify (Kundendatenanfrage, Kundendaten löschen, Shop-Daten löschen) werden ebenfalls verarbeitet. Die App abonniert carts/* nicht. Abgebrochene Warenkörbe kommen aus den checkouts/*-Themen.

Was in Brevo ankommt:

Die App fügt deinem Theme keine Schaltfläche „Notify me“ hinzu. Eine Anfrage für die Benachrichtigung bei Wiederverfügbarkeit muss aus deiner Storefront kommen, zum Beispiel über eine Schaltfläche, die du hinzufügst.

Bestehende Daten

Bei der Installation importiert die App deine bestehenden Kund:innen als Brevo-Kontakte. Eine vollständige historische Synchronisierung startest du auf der Sync-Seite der App. In bezahlten Tarifen importiert sie außerdem Produkte, Kollektionen, Unternehmen und Bestellungen.

Schritt 3: Eine Sync-Regel mit dem Agenten bauen

Eine Sync-Regel ist eine deklarative Definition einer Synchronisierung: eine Quellressource, eine Brevo-Aktion, eine Feldzuordnung und ein Filter. Du schreibst sie nicht von Hand. Du beschreibst sie, ein Agent baut sie, und ein Mensch gibt sie frei.

1. Öffne in Tajo Agents und bitte den Brevo Integration Architect in Alltagssprache um die Synchronisierung. Zum Beispiel: „Sende Shopify-Kund:innen, die E-Mail-Marketing akzeptiert haben, als Kontakte an Brevo.“
2. Der Agent untersucht den Shopify-Connector. Seine Stichprobe liefert Feldnamen und Typen, nie Kundenwerte.
3. Er schlägt eine Regel mit Feldzuordnung und Filter vor, validiert dann die Feldzuordnung gegen die Brevo-Aktion und führt einen Probelauf des Entwurfs durch. Keiner der beiden Schritte liest Kundendatensätze.
4. Er speichert die Regel als Entwurf. Du kannst auch mit einem Template unter Connections > Syncs and mappings > New sync from template beginnen.
5. Request publish approval führt eine Vorschau gegen deinen Store aus. Sie liest höchstens 10 Datensätze, schreibt nichts nach Brevo und bewegt den Cursor nicht. Sie hält nur Zahlen fest: abgerufene, geeignete, zugeordnete und vom Filter abgelehnte Datensätze sowie Zuordnungsfehler. Schlägt die Vorschau fehl, wird keine Freigabe erstellt.
6. Ein Mensch genehmigt die Anfrage auf der Seite Approvals mit einer schriftlichen Begründung. Die Freigabe ist an einen SHA-256-Digest der Regel gebunden und läuft nach 30 Minuten ab. Die Seite der Regel zeigt dann Publish approved version.

Wird eine veröffentlichte Regel bearbeitet, geht sie zurück in den Entwurf. Sie durchläuft Vorschau und Freigabe erneut, bevor sie wieder läuft.

Eine echte Regel

Das ist das Template Shopify customers -> Brevo contacts, wie Tajo es definiert:

sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",

Der Filter ist die Einwilligungsprüfung. Tajo leitet beide Werte aus Shopifys email_marketing_consent.state oder dem älteren Flag accepts_marketing ab. Eine Regel, die Kontakte nach Brevo schreibt, kann ohne ihn nicht veröffentlicht werden. Das andere Shopify-Template, Shopify orders → Brevo orders, erfasst Bestellungen in Brevo für Käufer:innen, die beim Checkout Marketing akzeptiert haben.

Wann eine Regel läuft

• Kontakt-Sync-Regeln laufen standardmäßig alle 15 Minuten. Jeder Lauf startet am Cursor der Regel.
• Die Seite einer aktiven Regel hat eine Schaltfläche Test run (1 batch).
• Eine aktive, veröffentlichte Regel Shopify orders → Brevo orders läuft ebenfalls alle 15 Minuten. Ihr erster geplanter Lauf beginnt einige Minuten vor diesem Moment und sendet keine älteren Bestellungen. Jeder weitere Lauf sendet die Bestellungen, die seit dem vorherigen Lauf aktualisiert wurden.
• Frühere Bestellungen gelangen nur nach Brevo, wenn du die Regel selbst ausführst: mit Test run (1 batch) oder indem du den Agenten Sync Operator bittest, sie auszuführen.
• Eine Bestellregel läuft nur dann nach Zeitplan, wenn sie den Opt-in-Filter des Templates für die Marketing-Einwilligung der Käufer:innen behält. Eine Regel mit bearbeitetem Filter läuft nur, wenn du sie startest.
• Nach fünf fehlgeschlagenen Läufen in Folge pausiert die Regel sich selbst, und ihre Seite zeigt den letzten Fehler. Behebe die Ursache und veröffentliche dann neu.

Jeder Lauf steht im Laufverlauf der Regel, mit gelesenen, geschriebenen und fehlgeschlagenen Datensätzen und seiner Dauer.

Was der Shopify-Connector liest und schreibt

Sync-Regeln schreiben nur ins Ziel, hier Brevo. Sie schreiben nie nach Shopify.

Die Tajo-Shopify-App fordert 12 Scopes an und macht eine kurze Liste von Schreibvorgängen nach Shopify, etwa Opt-outs bei der Einwilligung und Treue-Tags. Shopify-Berechtigungen erklärt listet jeden Scope und jeden Schreibvorgang auf, mit dem jeweiligen Auslöser.

Agents und MCP-Hosts erreichen den Store über den Shopify-Connector:

Der Connector deklariert außerdem eine Bestandsanpassung. Sie braucht den Scope write_inventory, den die Tajo-Shopify-App nicht anfordert.

Schritt 4: Die Shopify-Tools über MCP nutzen

Tajo stellt den Shopify-Connector als MCP-Server unter https://alto.tajo.io/mcp/connectors/shopify bereit. Füge ihn zu Claude Code hinzu:

claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify

Der Host erkennt den OAuth-Server von Tajo und öffnet die Tajo-Anmeldung. Der Zugriff ist auf Early-Access-Konten beschränkt. Der Server stellt 12 Tools bereit:

Fehlerbehebung

• Kontakte erscheinen nicht in Brevo: siehe Kontakte fehlen in Brevo.
• Eine Regel läuft nicht oder hat sich selbst pausiert: siehe Daten werden nicht synchronisiert.

Nächste Schritte

• Shopify-Datensynchronisation verstehen, wie sich Sync-Regeln verhalten
• Shopify-Berechtigungen erklärt, jeder Scope und jeder Schreibvorgang
• Shopify + Brevo, der Integrationsleitfaden
• Kontaktiere das Team, um loszulegen