Gift Card Hero REST API¶

Mit der REST API verwalten Sie Geschenkgutscheine per Programm aus externen Systemen, zum Beispiel aus CRM-Systemen, Analyse-Dashboards, Loyalty-Plattformen, Fulfillment-Diensten und mehr.

REST-API-Konfiguration

Basis-URL¶

Alle API-Anfragen verwenden die folgende Basis-URL:

https://gifthero.syncu.be/api/external

Authentifizierung¶

Jede Anfrage muss ein Bearer-Token im Header Authorization enthalten:

Authorization: Bearer YOUR_API_TOKEN

Um Ihr API-Token zu erhalten, gehen Sie in der linken Navigation zu For developers, setzen Sie das Häkchen bei Enable REST API und speichern Sie. Klicken Sie auf Send me access token. Das Token wird an die auf der Seite angezeigte E-Mail-Adresse Ihres Shop-Kontakts gesendet.

Das Token läuft nicht ab, bis Sie es ersetzen oder widerrufen. Behandeln Sie es wie ein Passwort: Speichern Sie es in den geheimen Einstellungen Ihrer Integration und fügen Sie es nicht in Chats, Tickets oder geteilte Dokumente ein.

Verwalten Ihres API-Tokens¶

Immer nur ein Token. Ihr Shop hat ein einziges API-Token. Jedes System, das die API aufruft, also ein POS, ein CRM oder der Dienst eines Partners, verwendet dasselbe Token.

Ein neues Token ersetzt das alte. Jeder Klick auf Send me access token erzeugt ein neues Token, und das bisherige funktioniert sofort nicht mehr. Aktualisieren Sie jede Integration sofort mit dem neuen Token. Wenn Sie das Token nur wieder nachschlagen müssen, suchen Sie die frühere E-Mail, statt ein neues Token zu senden.

Token widerrufen. Wenn ein Token möglicherweise kompromittiert wurde oder ein Partner, der es hatte, nicht mehr mit Ihnen arbeitet, klicken Sie auf der Seite For developers auf Revoke access token und bestätigen Sie. Das Token funktioniert sofort nicht mehr, und es wird kein neues ausgegeben. Wenn Sie so weit sind, klicken Sie auf Send me access token, um ein neues zu erhalten.

REST API ausschalten. Wenn Sie Enable REST API ausschalten und speichern, wird das Token ebenfalls widerrufen. Nachdem Sie die API wieder einschalten, senden Sie sich ein neues Token.

Was Ihre Integration sieht. Eine Anfrage mit einem ersetzten oder widerrufenen Token wird mit 401 beantwortet:

{
  "error": {
    "statusCode": 401,
    "name": "UnauthorizedError",
    "message": "Error verifying token : The token has been revoked or replaced."
  }
}

Die Lösung ist immer dieselbe: Tragen Sie das aktuelle Token im Header Authorization ein.

Token, die vor der Einführung von Token-IDs ausgestellt wurden, funktionieren weiter, bis Sie zum ersten Mal ein neues Token senden oder das Token widerrufen.

Weitere Authentifizierungsfehler:

Status	Bedeutung
`401`	Der Header `Authorization` fehlt oder ist nicht vom Typ `Bearer`, oder das Token ist nicht gültig
`402`	Der Shop hat keinen aktiven Gift-Card-Hero-Tarif

Endpunkte¶

Geschenkgutscheine auflisten¶

GET /gift-cards

Parameter:

Parameter	Typ	Beschreibung
`status`	string	Nach Status des Geschenkgutscheins filtern
`limit`	integer	Maximale Anzahl Ergebnisse (max. 250)
`since_id`	string	Ergebnisse nach dieser Geschenkgutschein-ID zurückgeben
`fields`	string	Kommagetrennte Liste der Felder, die enthalten sein sollen

Die Anfrage wird an Shopifys Geschenkgutschein-Liste weitergeleitet, daher gelten deren eigene Parameter. Jeder Gutschein in der Antwort enthält ein Objekt recipient (id, email, name) oder null. Ein Feld code wird mitgeliefert, wenn Gift Card Hero den vollständigen Code gespeichert hat (siehe Wichtige Hinweise).

Eine HEAD /gift-cards-Anfrage gibt 200 ohne Inhalt zurück. Manche HTTP-Clients nutzen sie als Vorabprüfung.

Geschenkgutscheine mit Transaktionen auflisten¶

GET /gift-cards/transactions

Gibt Geschenkgutscheine vom neuesten zum ältesten zurück, jeweils mit bis zu ihren 50 neuesten Transaktionen. Unterstützt cursorbasierte Paginierung.

Paginierung:

Parameter	Typ	Beschreibung
`limit`	integer	Geschenkgutscheine pro Seite (Standard 50)
`page_info`	string	Cursor für die nächste Ergebnisseite

Filter:

Filter	Typ	Beschreibung
`query`	string	Suchanfrage in Shopifys Suchsyntax für Geschenkgutscheine
`balance_status`	string	Einer von: `full`, `partial`, `empty`, `full_or_partial`
`created_at`	string	Nach Erstellungsdatum filtern
`expires_on`	string	Nach Ablaufdatum filtern
`source`	string	Einer von: `manual`, `purchased`, `api_client`
`status`	string	Einer von: `disabled`, `enabled`, `expired`, `expiring`
`initial_value`	string	Nach Anfangswert filtern
`id`	string	Nach Geschenkgutschein-ID filtern

Alle Filter werden mit UND verknüpft, wenn Sie sie kombinieren.

Antwort:

Jeder Geschenkgutschein hat id, balance, currency, initial_value, created_at, updated_at, disabled_at, customer_id, recipient, note, expires_on, template_suffix, last_characters, order_id, transactions und issued_by. Die Antwort enthält nicht den Geschenkgutschein-Code. Jede Transaktion hat id, amount (bei einer Belastung negativ), processed_at, note, pos_user und pos_order_name.

Transaktions-IDs:

transactions[].id ist die numerische Shopify-ID der Geschenkgutschein-Transaktion, also die Zahl am Ende ihrer GID gid://shopify/GiftCardDebitTransaction/… oder gid://shopify/GiftCardCreditTransaction/…. Frühere Versionen der API gaben hier null zurück.

POS-Felder:

Geschenkgutscheine, die über das Gift-Card-Hero-POS ausgestellt oder eingelöst wurden, enthalten den Kassierer, der die Aktion ausgeführt hat. Diese Felder werden zur Standardantwort hinzugefügt:

Feld	Typ	Beschreibung
`transactions[].pos_user`	object or null	`{ "username": "woodgrove", "name": "Woodgrove" }` für eine Belastung am POS, sonst `null`
`transactions[].pos_order_name`	string or null	Bestellname, der am POS für diese Belastung eingegeben wurde, falls vorhanden, sonst `null`
`issued_by`	object or null	`{ "username", "name", "issued_at" }` für einen am POS ausgestellten Gutschein, sonst `null`

Das POS-Aktivitätsprotokoll speichert keine Shopify-Transaktions-IDs. Eine Belastung wird deshalb anhand von Karte, Betrag und Zeitpunkt einer POS-Einlösung zugeordnet. Die Einlösung muss einige Sekunden vor bis eine Minute nach der Transaktion protokolliert sein. Online-Zahlungen, Änderungen im Shopify-Admin und Belastungen ohne passenden POS-Eintrag erhalten null. name ist null, wenn der POS-Benutzer inzwischen gelöscht wurde.

Einen einzelnen Geschenkgutschein abrufen¶

GET /gift-cards/{gift_card_id}

Gibt die Details eines einzelnen Geschenkgutscheins anhand seiner ID zurück, mit seinem recipient und, falls Gift Card Hero ihn gespeichert hat, seinem code.

Geschenkgutschein erstellen¶

POST /gift-cards

Anfragekörper:

{
  "note": "Loyalty reward",
  "initial_value": "50.00",
  "code": "ABCD-EFGH-IJKL-MNOP",
  "template_suffix": "custom"
}

Feld	Typ	Pflicht	Beschreibung
`note`	string	Nein	Interne Notiz zum Geschenkgutschein
`initial_value`	string	Ja	Anfangsguthaben
`code`	string	Nein	Eigener Geschenkgutschein-Code (muss eindeutig sein; wird automatisch erzeugt, wenn er fehlt)
`template_suffix`	string	Nein	Shopify-Template-Suffix
`customer_id`	integer	Nein	Shopify-Kunde, dem der Gutschein gehört
`email`	string	Nein	E-Mail-Adresse des Kunden, verwendet, wenn `customer_id` nicht gesendet wird. Gift Card Hero findet den Kunden oder legt einen an, der mit `gifthero:import` markiert wird

Der Körper wird an Shopifys Geschenkgutschein-Endpunkt weitergeleitet, der weitere Felder akzeptiert, etwa expires_on. Die Antwort ist der Shopify-Geschenkgutschein einschließlich des vollständigen code.

Wichtig: Speichern Sie den vollständigen Code aus der Antwort beim Erstellen, wenn Sie ihn später benötigen. Spätere Antworten enthalten den vollständigen code nur für Gutscheine, die Gift Card Hero gespeichert hat. Andernfalls werden nur die letzten 4 Zeichen (last_characters) zurückgegeben.

Guthaben des Geschenkgutscheins aktualisieren¶

PUT /gift-cards/{gift_card_id}/balance

Anfragekörper:

{
  "balance": "100.00"
}

Setzt das Guthaben des Geschenkgutscheins auf den angegebenen Wert. Ein Wert mit führendem Vorzeichen, etwa "+25.00" oder "-10.00", wird dagegen als Anpassung auf das aktuelle Guthaben angewendet. Ändert sich das Guthaben nicht, wird das aktuelle Guthaben zurückgegeben und nichts erfasst. Wenn im Shop Increase limit eingeschaltet ist, kann eine Aufladung über das übliche Shopify-Limit für Geschenkgutscheine hinausgehen.

Das ist eine Guthabenkorrektur: Es wird keine Benachrichtigung an den Kunden gesendet, und keine Filiale wird erfasst. Wenn ein Kunde den Gutschein an einer Kasse ausgibt, verwenden Sie stattdessen Einen Geschenkgutschein einlösen.

Einen Geschenkgutschein einlösen¶

POST /gift-cards/{gift_card_id}/redeem

Belastet (löst ein) einen Geschenkgutschein über eine POS- oder Kassen-App eines Drittanbieters, außerhalb des Shopify-Checkouts. Der Gutscheininhaber erhält die Einlösungsbenachrichtigung Ihres Shops (E-Mail oder SMS) mit dem Filialnamen. Stattdessen oder zusätzlich erhält der Käufer sie, wenn es unter Who gets notified in Ihren Einstellungen für Redemption notifications so festgelegt ist. Die Einlösung erscheint mit ihrer Filiale in den Berichten von Gift Card Hero. Verwenden Sie diese Methode anstelle des direkten Aufrufs von Shopifys giftCardDebit. Eine direkte Belastung sendet keine Filiale und keine Benachrichtigung.

Einlösen vs. Guthaben aktualisieren: Verwenden Sie Guthaben des Geschenkgutscheins aktualisieren, um das Guthaben ohne Benachrichtigung auf einen Wert zu setzen. Verwenden Sie Einlösen, wenn ein Kunde den Gutschein ausgibt und Sie die Benachrichtigung und die Filiale erfassen möchten.

Anfragekörper:

{
  "amount": "1500.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "note": "Table 12"
}

Feld	Typ	Pflicht	Beschreibung
`amount`	string	Ja	Einzulösender Betrag. Muss größer als 0 und nicht größer als das Guthaben des Gutscheins sein, in der Währung des Gutscheins, mit bis zu 2 Dezimalstellen
`branch`	string	Ja	Name der Filiale oder des Standorts. Wird in der Einlösungs-E-Mail und SMS angezeigt (wenn Include the store location in den Einlösungsbenachrichtigungen eingeschaltet ist) sowie in den Berichten
`reference`	string	Ja	Ihre eindeutige ID für diese Einlösung, bis zu 255 Zeichen. Siehe Wiederholungen und Duplikate
`note`	string	Nein	Wird in die Geschenkgutschein-Transaktion in Shopify geschrieben. Gift Card Hero hängt `[ref:<reference>]` an die Notiz an, damit Sie jede API-Einlösung im Shopify-Admin ihrer Referenz zuordnen können

Antwort (200):

{
  "id": 661944893757,
  "last_characters": "7nsf",
  "amount": "1500.00",
  "currency": "KES",
  "balance_before": "5090.00",
  "balance": "3590.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "processed_at": "2026-10-12T10:30:00Z",
  "notification": "queued",
  "duplicate": false
}

Feld	Beschreibung
`notification`	`queued`: Die Einlösungsbenachrichtigung wurde an die Einstellungen für Einlösungsbenachrichtigungen Ihres Shops übergeben, die entscheiden, ob sie gesendet wird (bei jeder Einlösung oder nur wenn der Gutschein aufgebraucht ist). `disabled`: Einlösungsbenachrichtigungen sind für Ihren Shop ausgeschaltet
`duplicate`	`true`, wenn diese `reference` bereits verarbeitet wurde und die Antwort das ursprüngliche Ergebnis ist

Fehler:

Fehler verwenden das übliche Format: {"error": {"statusCode": 422, "name": "...", "message": "..."}}.

Status	Bedeutung	Was zu tun ist
`400`	`amount`, `branch` oder `reference` fehlt oder ist ungültig	Anfragekörper korrigieren
`401`	Das Token fehlt, ist ungültig, widerrufen oder durch ein neueres ersetzt	Prüfen Sie den Header `Authorization`. Wenn das Token widerrufen oder ersetzt wurde, fordern Sie ein neues an
`403`	Der App fehlt ein Zugriffsbereich in Ihrem Shop	Der Shop-Inhaber muss die aktualisierten Berechtigungen der App im Shopify-Admin genehmigen
`404`	Geschenkgutschein nicht gefunden	Prüfen Sie die Geschenkgutschein-ID
`409`	Die `reference` wurde bereits für einen anderen Gutschein oder Betrag verwendet, oder eine Anfrage mit dieser `reference` wird noch verarbeitet	Verwenden Sie für eine neue Einlösung eine neue `reference`. Wird eine Anfrage noch verarbeitet, warten Sie einige Sekunden und wiederholen Sie sie mit derselben `reference`
`422`	Der Gutschein ist deaktiviert oder abgelaufen, oder der Betrag liegt über dem Guthaben. Die `message` nennt die Ursache. Das Guthaben bleibt unverändert	Beheben Sie die Ursache. Die `reference` ist nicht verbraucht, wiederholen Sie die Anfrage mit derselben
`429`	Shopify begrenzt die Anfragen für Ihren Shop (Rate Limit)	Warten Sie und wiederholen Sie die Anfrage mit derselben `reference`
`500`	Das Ergebnis konnte bei Shopify nicht bestätigt werden	Wiederholen Sie die Anfrage mit derselben `reference`: Der Gutschein wird nicht doppelt belastet

Eine fehlgeschlagene Anfrage (404 oder 422) verbraucht die reference nicht.

Wiederholungen und Duplikate¶

Erzeugen Sie für jede Einlösung eine reference und verwenden Sie sie nur erneut, wenn Sie genau diese Einlösung wiederholen. Wenn eine Anfrage in den Timeout läuft oder im Netzwerk fehlschlägt, wiederholen Sie sie mit derselben reference. Das ist immer sicher: Der Gutschein wird nie doppelt belastet, und Sie erhalten das ursprüngliche Ergebnis mit "duplicate": true zurück.

Geschenkgutschein aktualisieren¶

PUT /gift-cards/{gift_card_id}

Nur die folgenden Felder können aktualisiert werden:

Feld	Typ	Beschreibung
`expires_on`	string	Ablaufdatum
`note`	string	Interne Notiz
`template_suffix`	string	Shopify-Template-Suffix
`customer_id`	integer	Shopify-Kunde, dem der Gutschein gehört. Sie können stattdessen `email` senden, wie beim Erstellen eines Gutscheins

Die Antwort enthält den code, wenn Gift Card Hero ihn gespeichert hat.

Geschenkgutschein deaktivieren¶

POST /gift-cards/{gift_card_id}/disable

Deaktiviert den Geschenkgutschein dauerhaft. Diese Aktion kann nicht rückgängig gemacht werden. Gibt den deaktivierten Geschenkgutschein zurück.

Geschenkgutscheine suchen¶

GET /gift-cards/search

Parameter:

Parameter	Typ	Beschreibung
`order`	string	Sortierreihenfolge
`query`	string	Suchanfrage, zum Beispiel `last_characters:mnop`. Verwenden Sie `recipient:name@example.com`, um Gutscheine zu finden, die an einen Empfänger gesendet wurden
`limit`	integer	Maximale Anzahl Ergebnisse
`fields`	string	Kommagetrennte Liste der Felder, die enthalten sein sollen

Indizierte Felder (für Suchanfragen verfügbar):

created_at, updated_at, disabled_at, balance, initial_value, amount_spent, last_characters

Geschenkgutschein-Codes einer Bestellung zuweisen¶

POST /gift-cards/assign-to-order

Weist einer Shopify-Bestellung Ihre eigenen Geschenkgutschein-Codes zu, für Shops, die Codes außerhalb der App erzeugen. Das funktioniert nur, wenn Skip gift codes generation in den Einstellungen für Regular products as gift cards eingeschaltet ist. Andernfalls wird 400 zurückgegeben. Ebenfalls 400, wenn orderId nicht numerisch ist oder wenn ein Code bereits in Ihrem Shop existiert, und 404, wenn die Bestellung nicht gefunden wird.

Unterstützt die Zuweisung eines einzelnen Codes und mehrerer Codes.

Einzelner Code:

{
  "orderId": "1234567890",
  "giftCode": "ABCD-EFGH-IJKL-MNOP"
}

Mehrere Codes:

{
  "orderId": "1234567890",
  "giftCodes": [
    { "lineItemId": "111", "code": "ABCD-EFGH-IJKL-MNOP" },
    { "lineItemId": "222", "code": "QRST-UVWX-YZ12-3456" }
  ]
}

Antwort:

{
  "scheduled": true
}

scheduled ist false, wenn die Bestellung keine Geschenkgutscheine zur Verarbeitung enthält.

Paginierung¶

Der Transaktions-Endpunkt verwendet cursorbasierte Paginierung. Die Antwort enthält einen Header Link mit dem Cursor für die nächste Seite:

Link: <https://gifthero.syncu.be/api/external/gift-cards/transactions?page_info=CURSOR>; rel="next"

Auf der letzten Seite fehlt der Header. Lesen Sie den Wert page_info aus dem Header Link und übergeben Sie ihn in Ihrer nächsten Anfrage als Query-Parameter, mit denselben Filtern. Die URL der nächsten Seite enthält sie bereits.

Wichtige Hinweise¶

Eindeutigkeit der Codes: Beim Erstellen von Geschenkgutscheinen mit eigenen Codes muss jeder Code eindeutig sein. Die API gibt einen Fehler zurück, wenn ein doppelter Code gesendet wird.
Sichtbarkeit der Codes: Die Antwort beim Erstellen enthält den vollständigen Code. In späteren Antworten erscheint ein Feld code nur für Gutscheine, deren vollständigen Code Gift Card Hero gespeichert hat (Gutscheine, die es erzeugt hat, und Codes, die Sie zugewiesen haben). Andernfalls werden nur die letzten 4 Zeichen (last_characters) zurückgegeben. Der Transaktions-Endpunkt gibt nie Codes zurück.
Wiederholung von Einlösungen: Senden Sie beim Einlösen eines Geschenkgutscheins immer eine eindeutige reference und wiederholen Sie die Anfrage nach einem Timeout mit derselben reference. Siehe Wiederholungen und Duplikate.
Rate Limits: Anfragen werden an Shopify weitergeleitet, daher gelten die Limits Ihres Shops bei Shopify. Wenn Sie eine 429-Antwort erhalten, warten Sie und wiederholen Sie die Anfrage.
Postman-Collection: Sie umfasst die Geschenkgutschein-Endpunkte außer /gift-cards/transactions und /gift-cards/assign-to-order.

Postman-Collection¶

Laden Sie die Postman-Collection herunter, um die API schnell zu erkunden:

Postman-Collection herunterladen