Eine Shopify Custom App ist eine App, die nur für einen einzigen Shop entwickelt, nicht im Shopify App Store veröffentlicht und direkt vom Shopbetreiber installiert wird. Sie kommt vor allem bei direkten Integrationen mit ERP-Systemen, Buchhaltungssoftware oder Logistikplattformen zum Einsatz und erfordert einen anderen Ablauf für Token-Abruf und Autorisierung als die Entwicklung einer Standard-Public-App.
Dieser Leitfaden richtet sich an Entwickler, die eine Custom App für ihren eigenen Shop entwickeln möchten, und an technische Teams, die ein SaaS- oder Unternehmenssystem an Shopify anbinden möchten.
Was ist eine Shopify Custom App?
Eine Shopify Custom App ist eine App, die eigens für die Anforderungen eines bestimmten Shops geschrieben wurde, nur in diesem Shop installiert wird und die Public-App-Infrastruktur von Shopify (App Store, OAuth-Autorisierungsablauf) nicht nutzt. Sie ermöglicht programmatischen Zugriff auf die Admin API oder die Storefront API.
Ein häufiger Fehler ist es, die Shopify-App-Typen zu verwechseln. Die folgende Tabelle zeigt, welche Variante Sie in welchem Szenario verwenden sollten:
Typische Einsatzfälle für eine Custom App: ERP-Integration (SAP, Netsis, Logo), Anbindung eines eigenen Logistik- oder Versandsystems, interne Automatisierungs-Workflows und Datensynchronisierung zwischen Handelsplattformen.
Von der privaten App zur benutzerdefinierten App: Shopifys Änderung im Jahr 2023
Seit Januar 2022 lassen sich keine neuen Private Apps mehr erstellen; im Januar 2023 wurden die bestehenden Private Apps automatisch in Custom Apps umgewandelt. Bis dahin konnten Shop-Administratoren einen API-Schlüssel und ein API-Secret erzeugen und damit direkt zugreifen. Im neuen System ist dieser Weg versperrt.
Wichtiger Hinweis: Bestehende Private Apps wurden im Januar 2023 automatisch in Custom Apps umgewandelt; wenn Sie eine neue Integration aufbauen, richten Sie sie direkt als Custom App ein.
Warum diese Änderung? Aus Sicherheitssicht barg das alte Private-App-System erhebliche Risiken bei der Verwaltung von API-Schlüsseln: Es gab keine Schlüsselrotation, die Kontrolle der Scopes war lax, und es gab keinen Mechanismus, um geleakte Zugangsdaten zu erkennen. Das neue Custom-App-System schließt diese Lücken mit HMAC-Verifizierung, eingeschränkten Scopes und Token-Überwachung.
Technische Unterschiede aufgrund der Änderung:
- Alt: Direkte Anfrage mit API-Schlüssel + API-Secret. Neu: per OAuth 2.0 abgerufenes access_token
- Alt: API-Passwort im Header X-Shopify-Access-Token. Neu: OAuth-Token im selben Header
- Alt: Kein Token-Ablauf. Neu: Bei öffentlichen Apps, die nach dem 1. April 2026 erstellt wurden, ist das Offline-Token befristet (Erneuerung per Refresh-Token); Custom Apps können weiterhin unbefristete Offline-Token abrufen. Online-Token 24 Stunden
Shopify Custom App Token-Typen
Bei der Entwicklung von Shopify Custom Apps gibt es zwei API-Oberflächen und entsprechend zwei Token-Typen.
Für die meisten Unternehmensintegrationen brauchen Sie ein Admin-API-Zugriffstoken. Die Storefront API wird für kundenseitige Entwicklungen (Headless Commerce, mobile Apps) genutzt und bietet keinen Zugriff auf die Admin API.
Unterschied zwischen Offline- und Online-Token:
Offline-Token sind für Hintergrundprozesse, Cronjobs und Server-zu-Server-Integrationen gedacht. Bei neuen Apps sind sie befristet (expiring) und werden per Refresh-Token erneuert; richten Sie für Hintergrundjobs eine Erneuerungslogik ein. Online-Token sind für Abläufe mit Benutzersitzung gedacht und verfallen nach 24 Stunden.
Tipp: Verwenden Sie für ERP- oder Buchhaltungsintegrationen immer Offline-Token. Eine Synchronisierung, die um Mitternacht mit einem Online-Token läuft, schlägt unbemerkt fehl, sobald das Token abgelaufen ist.
Warum ist das neue Custom-App-System so komplex?
Wenn wir bei Nodus Works mit SaaS-Plattformen von Drittanbietern oder mit den ERP-Teams von Unternehmen arbeiten, hören wir von der Gegenseite am häufigsten diese Frage: „Wie bekommen wir das Shopify-Token?“
Das neue Custom-App-System von Shopify wurde aus nachvollziehbaren Gründen auf Sicherheit ausgelegt, bringt dadurch aber eine erhebliche Komplexität bei der Einrichtung mit sich. Gerade für Backend- oder Integrationsteams, die zum ersten Mal mit dem Shopify-Ökosystem arbeiten, ist der Ablauf unübersichtlich.
Ursachen für die Komplexität:
1. Zwei verschiedene Wege, ein Token zu erhalten. Die Custom App kann sowohl direkt per Client Credentials Grant im Dev Dashboard als auch über das Dev Dashboard mit OAuth-Flow installiert werden. Beide Wege erfordern unterschiedliche Verfahren für den Token-Abruf. Wenn Sie loslegen, ohne zu wissen, welchen Weg Sie nehmen, kämpfen Sie womöglich stundenlang mit einer halbfertigen Installation.
2. Konfiguration des Dev Dashboards. Wenn Sie sich für den OAuth-Weg entscheiden, müssen Sie im Dev Dashboard eine App anlegen, Callback-URLs definieren und die Scopes angeben. Ein Fehler in einem dieser Schritte führt zu invalid_client- oder redirect_uri_mismatch-Fehlern.
3. Scope-Verwaltung. Die angeforderten Scopes müssen in der .env- oder Konfigurationsdatei und im Dev Dashboard exakt übereinstimmen. Schon eine kleine Abweichung macht das Token ungültig.
4. HMAC-Überprüfung. Shopify erwartet, dass Sie die im Callback zurückgegebenen Parameter anhand der von Shopify erzeugten Signatur prüfen. Überspringen Sie diesen Schritt, entsteht eine Sicherheitslücke; setzen Sie ihn nicht um, kommt es in der Produktion zu Fehlern.
Shopify Admin API-Token erhalten: Zwei Methoden
Methode 1: Direktes Token über das Dev Dashboard
Diese Methode gilt nur, wenn Sie ein Token für Shops in Ihrer eigenen Organisation abrufen.
Schritte:
- Legen Sie im Dev Dashboard eine App an → App-Namen eingeben
- Wählen Sie die erforderlichen Admin-API-Scopes aus (z. B. read_orders, write_products)
- App im Shop installieren → Bestätigen
- Rufen Sie mit Client-ID und Client-Secret über einen Client Credentials Grant ein Access Token ab
- Das Token ist 24 Stunden gültig; erneuern Sie es alle 24 Stunden
Warnung: Der Weg Shopify-Admin → Einstellungen → Apps und Vertriebskanäle → Apps entwickeln ist seit dem 1. Januar 2026 für neue Custom Apps gesperrt und gilt nur noch für Apps, die vor 2026 erstellt wurden. Bei diesen älteren Apps wird das Admin-API-Zugriffstoken nur einmal angezeigt; wenn Sie es verlieren, müssen Sie die App deinstallieren und neu installieren, um ein neues Token zu erhalten.
Einschränkung dieser Methode: Sie funktioniert nur für Shops in derselben Organisation. Wenn Sie dieselbe Integration mit anderen Shops verbinden möchten, müssen Sie zum OAuth-Flow wechseln.
Methode 2: Dev Dashboard und OAuth 2.0-Flow
Dieser Weg ist für SaaS-Produkte, Agenturen und Multi-Store-Integrationen gedacht. Eine im Dev Dashboard erstellte App lässt sich per OAuth-Flow in verschiedenen Shops installieren.
Technischer Ablauf:
1. Der Nutzer wird zur App-Seite im Dev Dashboard weitergeleitet.
2. Der Endpunkt /auth wird mit der Shop-Domain aufgerufen
3. Die Shopify OAuth-Autorisierungsseite wird geöffnet
4. Der Benutzer gibt seine Zustimmung → Shopify leitet ihn mit dem Code zur Callback-URL weiter
5. Der Server überprüft den HMAC
6. Der Token-Endpunkt wird mit Code + client_id + client_secret aufgerufen
7. Das access_token wird zurückgegeben → in der Datenbank gespeichert
Diesen Ablauf von Grund auf selbst umzusetzen ist fehleranfällig, vor allem bei der HMAC-Überprüfung und der Scope-Verwaltung.
Shopify App Token Generator: Unsere Open-Source-Lösung
Um dieses Problem zu lösen, auf das wir in Integrationsprojekten immer wieder gestoßen sind, haben wir bei Nodus Works ein schlankes Tool entwickelt und als Open Source veröffentlicht:
github.com/nodusworkscom/shopify-app-token-generator
Das Tool führt den OAuth-2.0-Flow lokal aus und erzeugt ein Admin-API-Zugriffstoken. Wie lange das Token gilt, hängt vom App-Typ ab: Tokens, die im Dev Dashboard per Client Credentials Grant abgerufen werden, sind 24 Stunden gültig; bei öffentlichen Apps, die am oder nach dem 1. April 2026 erstellt wurden, gilt das Offline-Token 1 Stunde und wird mit einem 90 Tage gültigen Refresh-Token erneuert. Für Custom Apps und Apps, die ein Händler im eigenen Shop erstellt, sind unbefristete Offline-Tokens weiterhin möglich. So haben Sie in wenigen Minuten ein gültiges Token, ohne eine vollständige OAuth-Implementierung schreiben zu müssen.
Wie funktioniert es?
Wenn Sie das Tool starten, läuft auf localhost ein kleiner Express-Server. Sie werden zur OAuth-Autorisierungsseite von Shopify weitergeleitet; nach Ihrer Bestätigung wird der an die Callback-URL zurückgegebene Code automatisch abgefangen, die HMAC-Überprüfung durchgeführt und das access_token im Terminal und im Browser angezeigt.
Installation:
git clone https://github.com/nodusworkscom/shopify-app-token-generator.git
cd shopify-app-token-generator
npm install
cp .env.example .env
Füllen Sie Ihre .env-Datei aus:
SHOPIFY_API_KEY=your_client_id
SHOPIFY_API_SECRET=your_client_secret
SHOP=your-store.myshopify.com
SCOPES=read_products,write_orders,read_customers
npm start
Öffnen Sie im Browser localhost:3000 → klicken Sie auf dem Shopify-Bestätigungsbildschirm auf „Install app“ → das Token erscheint im Terminal und auf dem Bildschirm.
Voraussetzungen:
- Node.js v16 oder höher
- Shopify-Partnerkonto (kostenlos)
- Im Shopify Dev Dashboard erstellte App
- http://localhost:3000/callback als Callback-URL hinterlegt
Wichtig: In den App-Einstellungen im Dev Dashboard müssen die Basis-URL http://localhost:3000 und die Weiterleitungs-URL http://localhost:3000/callback hinterlegt sein. Andernfalls erhalten Sie den Fehler „redirect_uri_mismatch“.
Für mehrere Shops: Sie können den SHOP-Wert in der .env-Datei ändern und den Vorgang für jeden Shop wiederholen. Jedes erzeugte Token gilt nur für diesen Shop.
Das MIT-lizenzierte Tool eignet sich als Ausgangspunkt für Shopify-Integrationsprojekte und als praktische Referenz, um den Ablauf der Token-Erstellung zu verstehen.
Sicherheit und Best Practices für benutzerdefinierte Apps
Token-Sicherheit ist der kritischste Aspekt jeder Integration. Ein Admin-API-Zugriffstoken berechtigt dazu, Bestellungen, Kunden und Produkte in Ihrem Shop zu verwalten.
Token-Speicherung: Speichern Sie das Token als Umgebungsvariable und nehmen Sie es niemals in den Quellcode oder die Versionsverwaltung auf. Vergewissern Sie sich, dass .env in Ihrer .gitignore-Datei steht. Verwenden Sie in der Produktionsumgebung Vault, AWS Secrets Manager oder ein vergleichbares Secret-Management-Tool.
Prinzip der minimalen Scopes: Fordern Sie nicht mehr Scopes an, als die Integration braucht. Für ein System, das nur Bestellungen liest, reicht read_orders; fügen Sie kein write_orders oder read_customers hinzu. Shopify erlaubt zwar, die Scope-Liste nachträglich zu verkleinern, eine Erweiterung erfordert jedoch eine Neuinstallation.
HMAC-Überprüfung: Akzeptieren Sie das Token im OAuth-Callback nicht, ohne die von Shopify gesendete HMAC-Signatur zu überprüfen. Implementierungen, die diesen Schritt überspringen, sind anfällig für Token-Diebstahl. Unser Token-Generator führt diesen Schritt automatisch durch.
Webhook-Sicherheit: Überprüfen Sie auch Shopify-Webhooks mit HMAC. Verarbeiten Sie keine Webhook-Daten, ohne den X-Shopify-Hmac-Sha256-Header zu überprüfen.
Wenn Sie Unterstützung bei Sicherheit und technischer Architektur Ihrer Shopify-Integration brauchen, sehen Sie sich unseren Service für Shopify-Integrationslösungen an.
Häufige Fehler und Lösungen
invalid_client-Fehler: Client-ID oder Client-Secret wurden falsch eingegeben. Gleichen Sie die Zugangsdaten im Dev Dashboard mit der .env-Datei ab.
Fehler „redirect_uri_mismatch“: Die Callback-URL stimmt nicht exakt mit der im Dev Dashboard hinterlegten Weiterleitungs-URL überein. Schon ein abschließender Schrägstrich führt zum Fehler: http://localhost:3000/callback und http://localhost:3000/callback/ gelten als unterschiedlich.
Fehler „invalid_scope“: Einer der angeforderten Scopes ist ungültig oder falsch geschrieben. Orientieren Sie sich an der offiziellen Scope-Dokumentation von Shopify.
Einmalige Token-Anzeige: Wurde das im Admin-Panel abgerufene Token nicht gespeichert, müssen Sie die App deinstallieren und neu installieren. Ein über das Dev Dashboard per OAuth abgerufenes Token lässt sich erneuern, indem Sie den OAuth-Flow erneut durchlaufen.
HMAC-Überprüfung fehlgeschlagen: Das Client Secret ist falsch, oder die Query-String-Parameter wurden verändert. Der Token-Generator führt die Überprüfung automatisch durch; achten Sie bei einer eigenen Implementierung auf die Reihenfolge der Parameter.
Weitere Informationen zu ERP-Verbindungen und Systemintegrationen in Shopify-Integrationsprojekten finden Sie in unserem Leitfaden zur Shopify-ERP-Integration und in unserem Artikel zur Shopify-Integration. Zur Anbindung von Buchhaltungssystemen lesen Sie unseren Artikel zur Shopify-Rechnungs- und Buchhaltungsintegration.
Häufig gestellte Fragen
Was ist der Unterschied zwischen einer Shopify Custom App und einer Private App? Die Private App ist eine ältere Struktur, deren Neuerstellung Shopify im Januar 2022 gesperrt hat und die im Januar 2023 in Custom Apps umgewandelt wurde. Die Custom App ist das neue System, das die Private App ersetzt und eine sicherere Token-Verwaltung bietet. Bestehende Private Apps wurden automatisch in Custom Apps umgewandelt.
Ist das Token einer Custom App unbegrenzt gültig? Bei neuen öffentlichen Apps ist das Offline-Token befristet (expiring) und wird per Refresh-Token erneuert; Token aus dem Client Credentials Grant gelten 24 Stunden. Das Online-Token läuft nach 24 Stunden ab. Verwenden Sie für Hintergrundintegrationen Offline-Token und richten Sie eine Erneuerungslogik ein.
Kann eine Shopify Custom App kostenlos entwickelt werden? Das Shopify-Partnerkonto ist kostenlos. Für die Entwicklung einer Custom App fallen keine zusätzlichen Kosten an; der Shop, den Sie anbinden, muss jedoch einen aktiven Shopify-Tarif haben. Während der Entwicklung können Sie einen kostenlosen Development Store nutzen.
Mit wie vielen Shops kann ich eine Custom App verbinden? Eine im Admin-Panel erstellte Custom App gilt nur für einen einzigen Shop. Um mehrere Shops anzubinden, brauchen Sie eine Lösung über das Dev Dashboard mit OAuth-Flow; dabei wird für jeden Shop ein eigenes Zugriffstoken erzeugt.
Wie wähle ich zwischen der Shopify GraphQL Admin API und der REST API? Shopify entwickelt die GraphQL Admin API aktiv weiter und stellt die REST API schrittweise ein. Wir empfehlen, neue Integrationen auf GraphQL aufzubauen. GraphQL löst das Problem des Overfetching und bietet flexiblere Abfragemöglichkeiten.
Kann ich ohne OAuth-Flow ein Token erhalten? Ja. Eine im Dev Dashboard erstellte App kann für Shops derselben Organisation per Client Credentials Grant ohne OAuth-Weiterleitung ein Token abrufen; das Token ist 24 Stunden gültig. Diese Methode gilt nur für Shops in Ihrer eigenen Organisation; für die Installation in anderen Shops ist OAuth erforderlich.
Wie empfange ich Shopify-Webhooks über eine Custom App? Sobald Sie das Token der Custom App haben, können Sie über die Admin API ein Webhook-Abonnement anlegen. Sie definieren einen Endpunkt und nehmen dort die POST-Anfragen von Shopify entgegen. Prüfen Sie bei jeder Webhook-Anfrage den Header X-Shopify-Hmac-Sha256, bevor Sie sie verarbeiten.
Kann das Token-Generator-Tool in der Produktionsumgebung verwendet werden? Das Tool wurde dafür entwickelt, Tokens zu erzeugen. Sobald Sie ein gültiges Token haben, brauchen Sie das Tool nicht mehr. Ist das Token jedoch befristet (wie bei öffentlichen Apps), müssen Sie die Erneuerungslogik in Ihrem eigenen System umsetzen. Das erzeugte Token können Sie für API-Anfragen in der Produktion verwenden. Ideal ist das Tool zum Lernen, für die schnelle Token-Erstellung und für Integrationstests.
Fazit
Die Entwicklung von Shopify Custom Apps ist gerade mit dem neuen Token-System unnötig kompliziert geworden. Wenn Sie loslegen, ohne zu wissen, welches Token Sie auf welchem Weg abrufen, können Sie Stunden verlieren.
Ein Token direkt im Admin-Panel abzurufen ist nur bei Custom Apps möglich, die vor dem 1. Januar 2026 erstellt wurden; neue Integrationen für einen einzelnen Shop werden im Dev Dashboard erstellt und erhalten ihr Token über OAuth. Wenn Sie mehrere Shops unterstützen oder ein Drittsystem anbinden möchten, führt am OAuth-2.0-Flow kein Weg vorbei.
Das von uns entwickelte Open-Source-Tool shopify-app-token-generator verkürzt den schwierigsten Schritt dieses Prozesses, den OAuth-Flow mit HMAC-Verifizierung, auf wenige Minuten.
Wenn Sie technische Beratung, Architekturdesign oder Entwicklungsunterstützung für Ihr Shopify-Integrationsprojekt benötigen, können Sie unseren technischen Shopify-Support und Wartungsservice nutzen oder sich direkt an uns wenden.
