API

Lies und schreibe Daten zum Treueprogramm über dein eigenes Backend mit der externen GraphQL-API von Gibbond — melde Mitglieder an, vergib und löse Punkte ein und synchronisiere Aktivitäten aus beliebigen Vertriebskanälen.

Auf dieser Seite

⚡

Pro-Plan erforderlich. Die externe API ist im Pro-Plan verfügbar. Führe in Plans & billing im Gibbond-Admin ein Upgrade durch, um sie zu aktivieren.

🚀

Neu bei der API? Der Integrationsleitfaden zeigt konkrete Beispiele zum Kopieren und Einfügen — für Aufrufe vom Backend, die Integration in eine mobile App oder Web-App und das Sammeln von Punkten über einen weiteren Vertriebskanal. Diese Seite enthält die vollständige Schemaspezifikation.

Die API stellt einen einzelnen GraphQL-Endpunkt bereit. Sende eine POST-Anfrage mit einem JSON-Body, der deine query (oder Mutation) und optional variables enthält:

POST https://app.gibbond.com/api/v1/graphql

Alle Zeitstempel sind ISO-8601-Zeichenfolgen und alle IDs Shopify-GIDs (zum Beispiel gid://shopify/Customer/123), sofern nicht anders angegeben. Punkte sind ganze Zahlen.

Authentifizierung

Jede Anfrage enthält einen Berechtigungsnachweis im Authorization-Header. Für unterschiedliche Anwendungsfälle gibt es zwei Arten von Berechtigungsnachweisen.

API-Schlüssel (serverseitig)

API-Schlüssel identifizieren dein Backend. Erstelle sie auf der Seite API keys im Gibbond-Admin. Für jeden Schlüssel wird ein Berechtigungsbereich (READ, WRITE oder ADMIN) festgelegt. Bei der Erstellung wird der Schlüssel nur einmal angezeigt; er sieht so aus: glk_live_…. Übermittle ihn als Bearer-Token:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

⚠️

Nur serverseitig verwenden. Ein API-Schlüssel kann die Daten aller Mitglieder lesen und ändern. Er darf daher niemals in einem Browser, einer mobilen App oder einem anderen Client offengelegt werden, den du nicht kontrollierst. Speichere ihn in einer serverseitigen Umgebungsvariable und rotiere ihn über den Admin, falls er offengelegt wird.

Kundentokens (clientseitig)

Wenn du die API von einer kundenorientierten Oberfläche aus aufrufen möchtest, etwa einem Widget im Onlineshop oder einer mobilen App, erstelle über dein Backend mit der Mutation mintCustomerToken ein Kundentoken und übergib es anschließend an den Client. Kundentokens sind kurzlebig und auf eine einzelne Person beschränkt: Eine damit ausgeführte Anfrage kann nur deren Daten lesen und Aktionen für sie ausführen. Die Abfrage me gibt die dem Token zugeordnete Person zurück. redeemReward funktioniert für diese Person ohne Händlerschlüssel — das Token kann also sicher an den Browser übergeben werden.

Authorization: Bearer <customer token>

Berechtigungsbereiche

Der Berechtigungsbereich eines API-Schlüssels legt fest, welche Vorgänge damit ausgeführt werden dürfen. Die Bereiche bauen aufeinander auf.

Bereich	Berechtigungen
`READ`	Alle Abfragen (Punktestände, Verlauf, Prämien, Stufen und Konfiguration).
`WRITE`	Alle Berechtigungen von `READ` sowie Mutationen zum Anmelden von Mitgliedern, Vergeben positiver Punkte, Einlösen von Prämien, Bestätigen von Punkten und Erstellen von Kundentokens.
`ADMIN`	Alle Berechtigungen von `WRITE` sowie das Zurückbuchen von Punkten (`clawbackPoints`) und negative Anpassungen über `awardPoints` (ein negativer Wert für `points`).

ℹ️

Verwende den niedrigsten erforderlichen Berechtigungsbereich: einen READ-Schlüssel für Analysen, einen WRITE-Schlüssel zum Sammeln und Einlösen von Punkten und ADMIN nur für Erstattungen und Korrekturen.

Ratenbegrenzungen

Für jeden Berechtigungsnachweis (API-Schlüssel oder Kundentoken) gilt ein Limit von 600 Anfragen pro Minute. Bei Überschreitung gibt die API den HTTP-Status 429 und einen Retry-After-Header zurück, der angibt, wie viele Sekunden du bis zum nächsten Versuch warten musst.

Abfragen

Für Abfragen benötigst du mindestens einen Schlüssel mit dem Bereich READ oder ein Kundentoken, das nur die eigenen Kundendaten lesen kann.

Abfrage	Argumente	Rückgabewert / Beschreibung
`me`	—	Die Person, der ein kundengebundenes Token zugeordnet ist. Bei Aufruf mit einem Händler-API-Schlüssel tritt ein Fehler auf.
`customer`	`id: ID!`	Eine Person anhand ihrer GID.
`customers`	`ids: [ID!]!`	Mehrere Personen anhand ihrer GIDs abrufen (Händlerschlüssel, `READ`).
`customerByEmail`	`email: String!`	Eine Person über ihre E-Mail-Adresse suchen (Händlerschlüssel, `READ`).
`rewards`	—	Katalog der im Shop einlösbaren Prämien.
`tiers`	—	VIP-Stufen des Shops (Slug, Name, Schwellenwert, Multiplikator).
`shopConfig`	—	Konfiguration des Treueprogramms: Name, Währung, Punkte pro Währungseinheit, Bestätigungsmodus, Stufen und Prämien.
`pointHistory`	`customerId: ID!`, `limit: Int`	Punkteereignisse einer Person, neueste zuerst.
`activeCodes`	`customerId: ID!`	Noch nicht verwendete Rabattcodes einer Person (Einlösungen und Stufenvorteile).
`referral`	`customerId: ID!`	Empfehlungscode einer Person sowie Anzahl der Eingeladenen, qualifizierten Empfehlungen und vergebenen Prämien.
`totalLiability`	—	Offene Punkteverbindlichkeit des gesamten Shops als Ganzzahl (Händlerschlüssel, `READ`).

Mutationen

Für Mutationen ist ein Schlüssel mit dem Bereich WRITE erforderlich, sofern nicht anders angegeben. Vorgänge mit ADMIN-Berechtigung sind gekennzeichnet.

Mutation	Argumente	Rückgabewert / Beschreibung
`enrollCustomer`	`customerId: ID!`, `email: String`	Eine Person für das Treueprogramm anmelden (`WRITE`). Gibt `CustomerResult` zurück.
`awardPoints`	`customerId: ID!`, `points: Int!`, `reason: String`, `idempotencyKey: String`	Punkte vergeben oder anpassen. Ein negativer Wert für `points` erfordert `ADMIN`; `idempotencyKey` verhindert doppelte Ausführungen bei Wiederholungen. Gibt `PointResult` zurück.
`awardPointsForOrder`	`input: OrderInput!`	Punkte für eine Bestellung über einen anderen Vertriebskanal vergeben; Stufenmultiplikator, Boosts und Meilensteine werden wie üblich berücksichtigt. Dank `orderId` (`WRITE`) lassen sich Wiederholungen sicher ausführen. Gibt `PointResult` zurück.
`redeemReward`	`customerId: ID!`, `rewardId: ID!`	Eine Prämie gegen einen einmalig nutzbaren Rabattcode einlösen (`WRITE` oder ein Kundentoken für die zugehörige Person). Gibt `RedeemResult` zurück.
`confirmPoints`	`customerId: ID!`, `orderId: ID`	Ausstehende Punkte einer Person bestätigen, z. B. nach der Auftragsabwicklung (`WRITE`). Gibt die Anzahl bestätigter Punkte zurück.
`clawbackPoints`	`customerId: ID!`, `orderId: ID!`, `refundAmount: Float!`, `orderTotal: Float!`, `refundId: ID`	Punkte nach einer Erstattung zurückbuchen (`ADMIN`). Gibt die Anzahl der zurückgebuchten Punkte zurück.
`mintCustomerToken`	`customerId: ID!`, `ttlSeconds: Int`	Kurzlebiges, kundengebundenes Token zur clientseitigen Verwendung erstellen (`WRITE` / `ADMIN`). Gibt ein `CustomerToken` mit dem Feld `expiresAt` zurück.

ℹ️

awardPointsForOrder erwartet eine OrderInput mit orderId, customerId, optional customerEmail und orderName sowie einer Liste von lineItems. Jede Position enthält optional productId und collectionIds sowie lineTotal — so gelten Boosts und Ausschlüsse für Produkte und Kollektionen genauso wie bei nativen Shopify-Bestellungen.

Beispielanfrage

Rufe mit einem serverseitigen API-Schlüssel den Punktestand und die Stufe einer Person ab:

curl https://app.gibbond.com/api/v1/graphql \
  -X POST \
  -H "Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id: ID!) { customer(id: $id) { email balance pending lifetime tier { name multiplier } } }",
    "variables": { "id": "gid://shopify/Customer/123456789" }
  }'

Fehlercodes

Fehler folgen der GraphQL-Konvention: Auf oberster Ebene steht ein Array errors, dessen Einträge jeweils einen code in extensions und einen passenden HTTP-Status enthalten.

Code	HTTP	Bedeutung
`UNAUTHENTICATED`	401	Berechtigungsnachweis fehlt, ist ungültig oder abgelaufen.
`FORBIDDEN`	403	Der Berechtigungsnachweis ist gültig, hat aber nicht den erforderlichen Bereich für diesen Vorgang.
`RATE_LIMITED`	429	Ratenlimit überschritten; versuche es nach dem im `Retry-After`-Header angegebenen Zeitraum erneut.
`BAD_USER_INPUT`	400	Ungültige Argumente — fehlerhafte GID, erforderliches Feld fehlt oder Wert liegt außerhalb des zulässigen Bereichs.
`NOT_FOUND`	404	Die angegebene Person, Prämie oder andere Ressource ist nicht vorhanden.