Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

Shopify

Agenten mit Bestellungen aus einem Shopify-Shop starten und Bestellungen taggen oder Notizen ergänzen lassen.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typshopify
ZugangsdatenEin Kontozugang (Connection) vom Typ shopify mit Client-ID und Client Secret einer App, die du im Shopify Dev Dashboard anlegst
BridgeNicht unterstützt
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jedes passende Event startet alle verknüpften Agenten.
Während der PauseZustellungen erhalten 200 und starten keine Runs. Outbound sendet nichts.

Einrichtung

  1. Öffne im Shopify Dev Dashboard den Bereich Apps, klicke auf Create app, wähle Start from Dev Dashboard und gib der App einen Namen. App und Shop müssen zur selben Organisation in Shopify gehören; siehe Shopify-App und Zugriff.

  2. Lass auf der Seite Versions der App die App URL unverändert und stell die Webhooks API version auf 2026-10. Füge unter Scopes read_orders für Inbound-Verbindungen und write_orders für Outbound-Verbindungen hinzu; ein Write-Scope schließt das Lesen ein. Klicke auf Release.

  3. Webhooks zu Bestellungen enthalten Kundendaten. Öffne in den Settings der App Access requests → Protected customer data → Manage und wähle Customer data, dazu die Felder für Name, E-Mail, Adresse oder Telefon, wenn deine Agenten sie brauchen.

  4. Klicke auf Install app, wähle den Shop und klicke auf Install. Kopiere danach Client ID und Client secret aus den Settings der App.

  5. Klicke in connic unter Projekt-Settings → Connections auf New connection und wähle Shopify. Den Kontozugang kannst du auch im Formular der Verbindung über die Auswahl unter Connection anlegen. Gib einen Name ein, unter Shop domain die Domain des Shops, etwa acme.myshopify.com (der Name des Shops allein reicht auch), dazu Client ID und Client secret, und klicke auf Create connection. connic fordert dabei ein Token bei Shopify an. Falsche Werte oder eine App außerhalb der Organisation des Shops fallen also schon hier auf.

  6. Öffne den Agenten. Klicke im Connector Flow für Events zu Bestellungen auf Add inbound connector oder für Tags und Notizen auf Add outbound connector. Klicke dann auf Create New Connector und wähle Shopify.

  7. Wähle den Modus, Inbound (Order events) oder Outbound (Tags and notes), und unter Connection den Kontozugang. Trag bei Inbound die Topics ein. Klicke auf Create. Bei einer Inbound-Verbindung richtet connic dabei die Webhook-Abonnements für ihre Topics ein. Bei Outbound legst du danach fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.

Konfiguration

Die Felder einer Shopify-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.

FeldTypStatusBeschreibung
typestringRequiredshopify.
modestringRequiredinbound oder outbound. Dashboard: Mode.
connectionstringRequiredInbound und Outbound. Name oder ID eines Shopify-Kontozugangs. Dashboard: Connection.
configobjectOptionalInbound. Einstellungen der Shopify-Verbindung; Outbound-Verbindungen haben keine.
topicsstring[]RequiredInbound. Die Topics zu Bestellungen, die Runs starten: ORDERS_CREATE, ORDERS_PAID, ORDERS_FULFILLED, ORDERS_PARTIALLY_FULFILLED oder ORDERS_CANCELLED. Die REST-Namen von Shopify wie orders/create funktionieren auch. Dashboard: Topics, eines pro Zeile, vorausgefüllt mit ORDERS_CREATE und ORDERS_PAID.

Shop-Domain, Client-ID und Client Secret gehören zum Kontozugang, nicht zur Verbindung.

Erzeugte Werte

connic setzt diese Werte, wenn du die Verbindung speicherst.

WertModiBeschreibung
Webhook-AbonnementsInboundDie Abonnements der App für die Topics der Verbindung im Shop, auf die URL der Verbindung. connic legt sie beim Speichern der Verbindung an, du musst sie also nicht in Shopify einrichten.

Agent-Input

Modi: Inbound

Eine Inbound-Verbindung startet einen Run für jeden verknüpften Agenten, sobald Shopify ein Event zu einer Bestellung für eines ihrer Topics zustellt. Der Run erhält:

payload.json
{
  "topic": "orders/paid",
  "order": "#1001",
  "order_id": 5841234567,
  "conversation_id": "shopify:acme.myshopify.com/5841234567",
  "url": "https://acme.myshopify.com/admin/orders/5841234567",
  "raw": { ... }
}
  • topic ist das Topic, wie Shopify es in der Zustellung nennt, etwa orders/create oder orders/paid.
  • order ist der Name der Bestellung, etwa #1001, und order_id ihre numerische ID.
  • conversation_id bleibt für alle Events einer Bestellung gleich. Soll dein Agent die früheren Events der Bestellung als Verlauf kennen, setze in seiner YAML session.key: input.conversation_id. Von sich aus schaltet die Verbindung keine Sessions ein.
  • url ist der Link zur Bestellung im Shopify-Admin.
  • raw enthält die vollständige Bestellung, so wie Shopify sie sendet, in der Webhook-API-Version der App.

Schickt Shopify eine Zustellung noch einmal, startet kein weiterer Run. Der Inbound-Modus ändert die Bestellung nicht von selbst: Um sie zu taggen oder eine Notiz zu ergänzen, verknüpfst du den Agenten mit einer Outbound-Shopify-Verbindung, die denselben Kontozugang nutzt; siehe Outbound-Zustellung.

Shopify-App und Zugriff

connic greift auf Shopify als die App zu, die du im Shopify Dev Dashboard anlegst und im Shop installierst. App und Shop müssen zur selben Organisation in Shopify gehören. Sonst gibt Shopify der App kein Token, und der Kontozugang lässt sich nicht speichern. Für jeden Aufruf bei Shopify holt sich connic mit Client-ID und Client Secret ein kurzlebiges Token, du musst also kein Access Token kopieren oder rotieren.

Inbound-Verbindungen brauchen den Scope read_orders, Outbound-Verbindungen write_orders, der das Lesen einschließt. Fehlt ein Scope, meldet connic das beim Speichern der Verbindung. Für einen zusätzlichen Scope brauchst du eine neue Version der App, die du per Release veröffentlichst und die im Shop genehmigt wird. Webhooks zu Bestellungen enthalten Kundendaten, deshalb braucht die App außerdem Zugriff auf geschützte Kundendaten, wie in Schritt 3 der Einrichtung.

Shopify-Webhooks

Modi: Inbound

Beim Speichern einer Inbound-Verbindung abonniert connic für die App die Topics der Verbindung im Shop, auf die URL der Verbindung. Änderst du die Topics, passt connic die Abonnements an. Löschst du die Verbindung, entfernt connic sie.

connic prüft die Signatur jeder Zustellung, die Shopify mit dem Client Secret der App erstellt. Nach 8 fehlgeschlagenen Zustellungen in Folge löscht Shopify ein Abonnement. Speicherst du die Verbindung erneut, richtet connic es wieder ein.

Outbound-Zustellung

Modi: Outbound

Eine Outbound-Shopify-Verbindung ändert bei jeder Nutzung eine Bestellung: wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Welche Bestellung, entscheidet die erste zutreffende Regel:

  1. Nennt die Ausgabe oder der Payload eine order_id, etwa 5841234567 oder gid://shopify/Order/5841234567, ändert sie diese Bestellung.
  2. Hat eine Inbound-Shopify-Verbindung mit demselben Kontozugang den Run gestartet, ändert sie die Bestellung, deren Webhook ihn ausgelöst hat.
  3. Sonst schlägt die Zustellung fehl.

Die Änderungen laufen in dieser Reihenfolge: Tags entfernen, Tags hinzufügen, dann die Notiz.

Automatische Ausgabe

Eine automatische Verknüpfung nutzt die finale Ausgabe des Runs. Ein JSON-Objekt kann tags setzen, eine Liste oder einen kommagetrennten String mit Tags zum Hinzufügen, außerdem remove_tags, eine Liste mit Tags zum Entfernen, note, Text, der als neue Zeile an die Notiz der Bestellung angehängt wird, replace_note: true, um die Notiz stattdessen durch note zu ersetzen, und order_id. Klartext wird an die Notiz angehängt.

output.json
{
  "tags": ["prüfen", "großbestellung"],
  "note": "Rechnungs- und Lieferland weichen ab. Zurückhalten, bis der Kunde die Adresse bestätigt."
}

Payload für Agent-Tool und Middleware

Das Modell oder die Middleware übergibt dieselben Felder: tags und remove_tags als Listen, note, replace_note und order_id als String. Mindestens eines der Felder tags, remove_tags und note ist nötig. Andere Felder werden abgelehnt.

connector-payload.json
{
  "remove_tags": ["prüfen"],
  "tags": ["adresse-bestätigt"],
  "order_id": "5841234567"
}

Zustellung und Wiederholungen

Bremst Shopify eine Änderung per Rate Limit aus, wartet connic und stellt erneut zu. Die Runs der Verbindung zeigen jede Zustellung mit dem Fehler oder mit order_id, der url der Bestellung und den Änderungen: tags_added, tags_removed und note (appended oder replaced).

Limits und Fehler

LimitWert
Antwort an Shopifyconnic antwortet sofort und startet die Agenten danach.
Fehlgeschlagene ZustellungenShopify wiederholt eine fehlgeschlagene Zustellung über etwa 4 Stunden und löscht das Abonnement nach 8 Fehlschlägen in Folge. Speicherst du die Verbindung erneut, richtet connic es wieder ein.
API-AnfragenBremst Shopify eine Änderung per Rate Limit aus, wartet connic und stellt erneut zu.

Anfragen mit fehlender oder falscher Signatur erhalten 401. Ein Kontozugang lässt sich nicht speichern, wenn Shopify Client-ID oder Client Secret ablehnt, unter der Shop-Domain keinen Shop findet oder die App nicht zur Organisation des Shops gehört. Eine Verbindung lässt sich nicht speichern, wenn der App der nötige Scope fehlt. Eine Zustellung schlägt fehl, wenn die Ausgabe weder Tags zum Hinzufügen oder Entfernen noch eine Notiz enthält, wenn sie keine Bestellung nennt und keine Shopify-Verbindung mit demselben Kontozugang den Run gestartet hat oder wenn Shopify die Änderung ablehnt, etwa weil die Bestellung nicht existiert.