Gift Card Hero REST API¶

Met de REST API beheer je cadeaubonnen vanuit externe systemen, zoals CRM's, analysedashboards, loyaltyplatforms, fulfilmentdiensten en meer.

REST API-configuratie

Basis-URL¶

Alle API-verzoeken gebruiken de volgende basis-URL:

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

Authenticatie¶

Elk verzoek moet een Bearer-token bevatten in de header Authorization:

Authorization: Bearer YOUR_API_TOKEN

Om je API-token te verkrijgen, ga je in het linkermenu naar For developers, vink je Enable REST API aan en sla je op. Klik op Send me access token. Het token wordt gestuurd naar het contactadres van de winkel dat op de pagina staat.

Het token verloopt niet totdat je het vervangt of intrekt. Behandel het als een wachtwoord: bewaar het in de geheime instellingen van je integratie, en plak het niet in chats, tickets of gedeelde documenten.

Je API-token beheren¶

Eén token tegelijk. Je winkel heeft één API-token. Elk systeem dat de API aanroept, zoals een kassasysteem, een CRM of de dienst van een partner, gebruikt datzelfde token.

Een nieuw token vervangt het oude. Elke klik op Send me access token geeft een nieuw token uit, en het vorige token werkt meteen niet meer. Werk elke integratie direct bij met het nieuwe token. Als je het token alleen wilt opzoeken, zoek dan de eerdere e-mail op in plaats van een nieuw token te versturen.

Een token intrekken. Als een token mogelijk is gelekt, of een partner die het had niet meer met je werkt, klik je op de pagina For developers op Revoke access token en bevestig je. Het token werkt dan meteen niet meer, en er wordt geen nieuw token uitgegeven. Wanneer je klaar bent, klik je op Send me access token om een nieuw token uit te geven.

De REST API uitschakelen. Als je Enable REST API uitzet en opslaat, wordt ook het token ingetrokken. Nadat je de API weer aanzet, stuur je jezelf een nieuw token.

Wat je integratie ziet. Een verzoek met een vervangen of ingetrokken token krijgt een 401-antwoord:

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

De oplossing is altijd hetzelfde: zet het huidige token in de header Authorization.

Tokens die zijn uitgegeven voordat token-ID's werden ingevoerd, blijven werken tot de eerste keer dat je een nieuw token verstuurt of het token intrekt.

Andere authenticatiefouten:

Status	Betekenis
`401`	De header `Authorization` ontbreekt of is niet van het type `Bearer`, of het token is niet geldig
`402`	De winkel heeft geen actief Gift Card Hero-abonnement

Endpoints¶

Cadeaubonnen weergeven¶

GET /gift-cards

Parameters:

Parameter	Type	Beschrijving
`status`	string	Filter op de status van de cadeaubon
`limit`	integer	Maximaal aantal resultaten (maximaal 250)
`since_id`	string	Geef resultaten terug na dit cadeaubon-ID
`fields`	string	Door komma's gescheiden lijst van velden om op te nemen

Het verzoek wordt doorgegeven aan de cadeaubonlijst van Shopify, dus de parameters van Shopify zelf gelden ervoor. Elke bon in het antwoord bevat een object recipient (id, email, name) of null. Een veld code wordt opgenomen wanneer Gift Card Hero de volledige code heeft opgeslagen (zie Belangrijke opmerkingen).

Een HEAD /gift-cards-verzoek geeft 200 terug zonder body. Sommige HTTP-clients gebruiken dit als preflight-controle.

Cadeaubonnen met transacties weergeven¶

GET /gift-cards/transactions

Geeft cadeaubonnen terug, nieuwste eerst, elk met maximaal de 50 meest recente transacties. Ondersteunt paginering op basis van een cursor.

Paginering:

Parameter	Type	Beschrijving
`limit`	integer	Cadeaubonnen per pagina (standaard 50)
`page_info`	string	Cursor voor de volgende pagina met resultaten

Filters:

Filter	Type	Beschrijving
`query`	string	Zoekopdracht, in de zoeksyntaxis voor cadeaubonnen van Shopify
`balance_status`	string	Een van: `full`, `partial`, `empty`, `full_or_partial`
`created_at`	string	Filter op aanmaakdatum
`expires_on`	string	Filter op vervaldatum
`source`	string	Een van: `manual`, `purchased`, `api_client`
`status`	string	Een van: `disabled`, `enabled`, `expired`, `expiring`
`initial_value`	string	Filter op beginwaarde
`id`	string	Filter op cadeaubon-ID

Alle filters werken met AND-logica wanneer je ze combineert.

Antwoord:

Elke cadeaubon heeft id, balance, currency, initial_value, created_at, updated_at, disabled_at, customer_id, recipient, note, expires_on, template_suffix, last_characters, order_id, transactions en issued_by. Het antwoord bevat de cadeaubooncode niet. Elke transactie heeft id, amount (negatief bij een afschrijving), processed_at, note, pos_user en pos_order_name.

Transactie-ID's:

transactions[].id is het numerieke Shopify-ID van de cadeaubontransactie: het getal aan het einde van de GID gid://shopify/GiftCardDebitTransaction/… of gid://shopify/GiftCardCreditTransaction/…. Eerdere versies van de API gaven hier null terug.

POS-velden:

Cadeaubonnen die via het Gift Card Hero POS zijn uitgegeven of ingewisseld, bevatten de kassamedewerker die dat deed. Deze velden worden aan het standaardantwoord toegevoegd:

Veld	Type	Beschrijving
`transactions[].pos_user`	object of null	`{ "username": "woodgrove", "name": "Woodgrove" }` voor een afschrijving in het POS; anders `null`
`transactions[].pos_order_name`	string of null	Ordernaam die voor die afschrijving in het POS is ingevoerd, indien aanwezig; anders `null`
`issued_by`	object of null	`{ "username", "name", "issued_at" }` voor een bon die in het POS is uitgegeven; anders `null`

Het POS-activiteitenlogboek slaat geen Shopify-transactie-ID's op. Daarom wordt een afschrijving gekoppeld aan een POS-inwisseling op basis van kaart, bedrag en tijd (de inwisseling moet enkele seconden vóór tot één minuut na de transactie zijn vastgelegd). Online betalingen, wijzigingen in de Shopify-admin en afschrijvingen zonder bijbehorend POS-record krijgen null. name is null als de POS-gebruiker inmiddels is verwijderd.

Eén cadeaubon ophalen¶

GET /gift-cards/{gift_card_id}

Geeft de details van één cadeaubon op basis van zijn ID, met de recipient en, wanneer Gift Card Hero die heeft, de code.

Een cadeaubon aanmaken¶

POST /gift-cards

Request-body:

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

Veld	Type	Verplicht	Beschrijving
`note`	string	Nee	Interne notitie voor de cadeaubon
`initial_value`	string	Ja	Startsaldo
`code`	string	Nee	Eigen cadeaubooncode (moet uniek zijn; wordt automatisch gegenereerd als je hem weglaat)
`template_suffix`	string	Nee	Shopify-templatesuffix
`customer_id`	integer	Nee	Shopify-klant die de bon bezit
`email`	string	Nee	E-mailadres van de klant, gebruikt wanneer `customer_id` niet is meegestuurd. Gift Card Hero zoekt de klant, of maakt er een aan met de tag `gifthero:import`

De body wordt doorgegeven aan het cadeaubonendpoint van Shopify, dat extra velden accepteert, zoals expires_on. Het antwoord is de cadeaubon van Shopify, inclusief de volledige code.

Belangrijk: Bewaar de volledige code uit het antwoord op het aanmaken als je die later nodig hebt. Latere antwoorden bevatten de volledige code alleen voor bonnen waarvan Gift Card Hero de code heeft opgeslagen. Anders worden alleen de laatste 4 tekens (last_characters) teruggegeven.

Saldo van een cadeaubon bijwerken¶

PUT /gift-cards/{gift_card_id}/balance

Request-body:

{
  "balance": "100.00"
}

Stelt het saldo van de cadeaubon in op de opgegeven waarde. Een waarde met een voorafgaand teken, zoals "+25.00" of "-10.00", wordt als aanpassing op het huidige saldo toegepast. Als het saldo niet verandert, wordt het huidige saldo teruggegeven en wordt er niets vastgelegd. Wanneer Increase limit in je winkel aanstaat, kan een bijstorting boven de standaardlimiet van Shopify voor cadeaubonnen uitkomen.

Dit is een saldocorrectie: er wordt geen melding naar de klant verstuurd en er wordt geen filiaal vastgelegd. Wanneer een klant de bon bij een kassa uitgeeft, gebruik je in plaats daarvan Een cadeaubon inwisselen.

Een cadeaubon inwisselen¶

POST /gift-cards/{gift_card_id}/redeem

Schrijft een bedrag af van een cadeaubon (inwisselen) vanuit een POS- of kassa-app van een derde partij, buiten het Shopify-afrekenen om. De houder van de bon ontvangt de inwisselingsmelding van je winkel (e-mail of sms) met de naam van het filiaal, of in plaats daarvan de koper, of beiden, afhankelijk van wat Who gets notified in je instellingen voor inwisselingsmeldingen aangeeft. De inwisseling verschijnt met het filiaal in de rapporten van Gift Card Hero. Gebruik deze methode in plaats van rechtstreeks giftCardDebit van Shopify aan te roepen. Een rechtstreekse afschrijving stuurt geen filiaal en geen melding.

Inwisselen vs. saldo bijwerken: gebruik Update gift card balance om het saldo op een waarde te zetten zonder iemand te informeren. Gebruik Redeem wanneer een klant de bon uitgeeft en je de melding en het filiaal wilt laten vastleggen.

Request-body:

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

Veld	Type	Verplicht	Beschrijving
`amount`	string	Ja	Te inwisselen bedrag. Moet groter zijn dan 0 en niet meer dan het saldo van de bon, in de valuta van de bon, met maximaal 2 decimalen
`branch`	string	Ja	Naam van het filiaal of de locatie. Wordt getoond in de inwisselingsmail en sms (wanneer Include the store location aan staat in de inwisselingsmeldingen) en in rapporten
`reference`	string	Ja	Je unieke ID voor deze inwisseling, maximaal 255 tekens. Zie Herhalingen en dubbele verzoeken
`note`	string	Nee	Wordt naar de cadeaubontransactie in Shopify geschreven. Gift Card Hero voegt `[ref:<reference>]` aan de notitie toe, zodat je elke inwisseling via de API kunt koppelen aan zijn referentie in de Shopify-admin

Antwoord (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
}

Veld	Beschrijving
`notification`	`queued`: de inwisselingsmelding is doorgegeven aan de instellingen voor inwisselingsmeldingen van je winkel, die bepalen of hij wordt verstuurd (bij elke inwisseling, of alleen wanneer de bon helemaal op is). `disabled`: inwisselingsmeldingen zijn uitgeschakeld voor je winkel
`duplicate`	`true` wanneer deze `reference` al is verwerkt en het antwoord het oorspronkelijke resultaat is

Fouten:

Fouten gebruiken het gebruikelijke formaat: {"error": {"statusCode": 422, "name": "...", "message": "..."}}.

Status	Betekenis	Wat te doen
`400`	`amount`, `branch` of `reference` ontbreekt of is ongeldig	Corrigeer de request-body
`401`	Het token ontbreekt, is ongeldig, ingetrokken of vervangen door een nieuwer token	Controleer de header `Authorization`. Als het token is ingetrokken of vervangen, vraag dan een nieuw token aan
`403`	De app mist een toegangsbereik in je winkel	De eigenaar van de winkel moet de bijgewerkte rechten van de app goedkeuren in de Shopify-admin
`404`	Cadeaubon niet gevonden	Controleer het cadeaubon-ID
`409`	De `reference` is al gebruikt voor een andere bon of een ander bedrag, of een verzoek met deze `reference` wordt nog verwerkt	Gebruik voor een nieuwe inwisseling een nieuwe `reference`. Als een verzoek nog wordt verwerkt, wacht je enkele seconden en probeer je het opnieuw met dezelfde `reference`
`422`	De bon is uitgeschakeld of verlopen, of het bedrag is hoger dan het saldo. Het veld `message` vermeldt welke. Het saldo is niet veranderd	Los de oorzaak op. De `reference` is niet opgebruikt, dus probeer het opnieuw met dezelfde
`429`	Shopify beperkt het aantal verzoeken voor je winkel	Wacht even en probeer het opnieuw met dezelfde `reference`
`500`	De uitkomst kon niet bij Shopify worden bevestigd	Probeer het opnieuw met dezelfde `reference`: de bon wordt niet dubbel afgeschreven

Een mislukt verzoek (404 of 422) gebruikt de reference niet op.

Herhalingen en dubbele verzoeken¶

Genereer één reference per inwisseling, en gebruik die alleen opnieuw wanneer je diezelfde inwisseling opnieuw probeert. Als een verzoek een time-out krijgt of op het netwerk mislukt, probeer het opnieuw met dezelfde reference. Dit is altijd veilig: de bon wordt nooit dubbel afgeschreven, en je krijgt het oorspronkelijke resultaat terug met "duplicate": true.

Een cadeaubon bijwerken¶

PUT /gift-cards/{gift_card_id}

Alleen de volgende velden kunnen worden bijgewerkt:

Veld	Type	Beschrijving
`expires_on`	string	Vervaldatum
`note`	string	Interne notitie
`template_suffix`	string	Shopify-templatesuffix
`customer_id`	integer	Shopify-klant die de bon bezit. Je kunt in plaats daarvan `email` meesturen, zoals bij het aanmaken van een bon

Het antwoord bevat de code wanneer Gift Card Hero die heeft opgeslagen.

Een cadeaubon uitschakelen¶

POST /gift-cards/{gift_card_id}/disable

Schakelt de cadeaubon permanent uit. Deze actie kan niet ongedaan worden gemaakt. Geeft de uitgeschakelde cadeaubon terug.

Cadeaubonnen zoeken¶

GET /gift-cards/search

Parameters:

Parameter	Type	Beschrijving
`order`	string	Sorteervolgorde
`query`	string	Zoekopdracht, bijvoorbeeld `last_characters:mnop`. Gebruik `recipient:name@example.com` om bonnen te vinden die naar een ontvanger zijn gestuurd
`limit`	integer	Maximaal aantal resultaten
`fields`	string	Door komma's gescheiden lijst van velden om op te nemen

Geïndexeerde velden (beschikbaar voor zoekopdrachten):

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

Cadeaubooncodes aan een order toewijzen¶

POST /gift-cards/assign-to-order

Wijst je eigen cadeaubooncodes toe aan een Shopify-order, voor winkels die codes buiten de app genereren. Dit werkt alleen wanneer Skip gift codes generation aanstaat in de instellingen van Regular products as gift cards. Anders geeft het 400 terug. Het geeft ook 400 terug als orderId niet numeriek is of als een code al in je winkel bestaat, en 404 als de order niet wordt gevonden.

Ondersteunt het toewijzen van één of meerdere codes.

Eén code:

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

Meerdere codes:

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

Antwoord:

{
  "scheduled": true
}

scheduled is false wanneer de order geen cadeaubonnen heeft om te verwerken.

Paginering¶

Het transactie-endpoint gebruikt paginering op basis van een cursor. Het antwoord bevat een header Link met de cursor voor de volgende pagina:

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

De header ontbreekt op de laatste pagina. Haal de waarde page_info uit de header Link en geef die als queryparameter mee in je volgende verzoek, met dezelfde filters. De URL van de volgende pagina bevat ze al.

Belangrijke opmerkingen¶

Uniciteit van codes: wanneer je cadeaubonnen met eigen codes aanmaakt, moet elke code uniek zijn. De API geeft een fout als een dubbele code wordt ingediend.
Zichtbaarheid van codes: het antwoord op het aanmaken bevat de volledige code. In latere antwoorden verschijnt een veld code alleen voor bonnen waarvan Gift Card Hero de volledige code heeft opgeslagen (bonnen die het zelf heeft gegenereerd en codes die jij hebt toegewezen). Anders wordt alleen de laatste 4 tekens (last_characters) teruggegeven. Het transactie-endpoint geeft nooit codes terug.
Herhalingen bij inwisselingen: stuur altijd een unieke reference mee bij het inwisselen van een cadeaubon, en probeer het opnieuw met dezelfde reference na een time-out. Zie Herhalingen en dubbele verzoeken.
Limieten voor aantal verzoeken: verzoeken worden doorgegeven aan Shopify, dus de limieten van Shopify voor je winkel gelden. Als je een 429-antwoord krijgt, wacht je even en probeer je het opnieuw.
Postman-collectie: dekt de cadeaubon-endpoints, behalve /gift-cards/transactions en /gift-cards/assign-to-order.

Postman-collectie¶

Download de Postman-collectie om de API snel te verkennen:

Download Postman Collection