Storefront API¶

De Storefront API biedt een JavaScript-interface (window.GiftHeroAPI) om eigen cadeaubonselectie- en aankoopprocessen op je webshop te bouwen.

Configuratie van de Storefront API

De API inschakelen¶

Ga naar For developers in het linkermenu.
Vink Enable storefront API aan en sla op.

De cadeaubon-interface die de app op je cadeaubon-productpagina genereert, wordt uitgeschakeld, en window.GiftHeroAPI wordt in plaats daarvan geladen. Jij bouwt de interface.

De API leest geen cadeaubonsaldi. Ze verzamelt de keuzes van de koper en voegt de cadeaubon aan de winkelwagen toe.

Headless webshops

Op een headless webshop wordt de API geladen wanneer headless-modus en Enable storefront API allebei aan staan. Zie Headless-integratie.

Initialisatie¶

De API wordt asynchroon geladen. Gift Card Hero vuurt een event op window af zodra hij klaar is. Luister ernaar voordat je methoden aanroept:

window.addEventListener('gift.hero:initalized', function () {
  const api = window.GiftHeroAPI;
  // API is ready to use
});

De eventnaam is gespeld als initalized

De eventnaam bevat een typefout: gift.hero:initalized (zonder tweede "i"). Gebruik hem precies zoals hier staat. Het event wordt op window afgevuurd, niet op document, nadat het Gift Card Hero-webshopscript is geladen. Staat het script niet op de pagina of is de storefront-API uitgeschakeld, dan wordt het event niet afgevuurd.

Wanneer de API start, selecteert hij de eerste variant (of de variant in de URL-parameter ?variant=) en de eerste afbeelding.

Methoden¶

addToCart(quantity?, skipValidation?)¶

Valideert de cadeaubongegevens en voegt de geconfigureerde cadeaubon met Shopify's /cart/add.js aan de winkelwagen toe.

try {
  const result = await window.GiftHeroAPI.addToCart(1);
  // result: { status: 200, data: { ... } }
} catch (e) {
  // e: { status: 400, data: { errors: ['...'] } } when validation fails
}

Parameter	Type	Standaard	Beschrijving
`quantity`	number	1	Aantal cadeaubonnen om toe te voegen
`skipValidation`	boolean	false	De kaart toevoegen, ook als `validate()` fouten meldt

Retourneert: een promise met de Shopify-winkelwagenrespons ({ status, data }). De promise wordt afgewezen met { status: 400, data: { errors } } wanneer de validatie mislukt.

generatePreview()¶

Opent een voorbeeld van hoe de cadeaubon eruitziet voor de ontvanger, met de gegevens die tot nu toe zijn ingevuld.

window.GiftHeroAPI.generatePreview();

getImages()¶

Retourneert een array met afbeeldings-URL's die beschikbaar zijn voor de cadeaubon: je eigen ontwerpen, de geselecteerde ingebouwde ontwerpen en, indien ingeschakeld, de productafbeeldingen.

const images = window.GiftHeroAPI.getImages();
// ['https://cdn.shopify.com/...', 'https://cdn.shopify.com/...']

getOptions()¶

Retourneert de productopties, inclusief de beschikbare bedragen.

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

Retourneert de interfacevertalingen voor de huidige taal, zoals de labels en het validatiebericht.

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

Retourneert de array met productvarianten.

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

Stelt alle cadeaubongegevens in één keer in.

window.GiftHeroAPI.setCardData({
  variantId: 12345678,
  image: 'https://cdn.shopify.com/...',
  message: 'Happy Birthday!',
  from: 'Alice',
  to: 'Bob',
  deliveryDate: new Date('2026-12-25'),
  email: 'recipient@example.com'
});

Veld	Type	Beschrijving
`variantId`	number	De geselecteerde variant-ID
`image`	string	URL van de geselecteerde kaartafbeelding
`message`	string	Bericht op de cadeaubon
`from`	string	Naam van de afzender
`to`	string	Naam van de ontvanger (optioneel)
`deliveryDate`	`Date`	Geplande leverdatum, als JavaScript-`Date`-object (optioneel)
`email`	string	E-mailadres van de ontvanger (optioneel)

Sms-levering is niet beschikbaar via de API, dus er is geen telefoonveld.

Afzonderlijke setters¶

Methode	Parameter	Beschrijving
`setDeliveryDate(date)`	`Date`	Stel de geplande leverdatum in. Geeft een fout als het geen geldig datumobject is
`setEmail(email)`	string	Stel het e-mailadres van de ontvanger in
`setFrom(name)`	string	Stel de naam van de afzender in
`setTo(name)`	string	Stel de naam van de ontvanger in
`setImage(image)`	string	Stel de URL van de geselecteerde kaartafbeelding in
`setMessage(message)`	string	Stel het bericht op de cadeaubon in
`setVariant(variantId)`	number of string	Selecteer een variant
`setProperty(name, value)`	string, string	Voeg een extra line-itemeigenschap toe aan de winkelwagenregel

validate()¶

Controleert de huidige cadeaubongegevens en retourneert { valid, errors }, waarbij errors een array met berichten is, opgebouwd uit je vertalingen.

const { valid, errors } = window.GiftHeroAPI.validate();

Validatieregels:

Als een e-mailadres van de ontvanger is ingesteld, zijn de leverdatum, de naam van de afzender (from) en het bericht verplicht.
Als een leverdatum is ingesteld, zijn het e-mailadres van de ontvanger, de naam van de afzender en het bericht verplicht.
Zonder e-mailadres en zonder leverdatum is niets verplicht.

setCustomAmount(amount)¶

Selecteert een vrij bedrag, in de valuta van je winkel (bijvoorbeeld 75 voor 75,00). Dit werkt alleen als vrije bedragen voor je winkel zijn ingeschakeld. Anders geeft de methode de fout Custom amount is not enabled. De methode controleert je minimum en maximum niet, dus valideer het bedrag zelf.

window.GiftHeroAPI.setCustomAmount(75);

Fysieke cadeaubonnen¶

Als je fysieke cadeaubonnen verkoopt, schakel je de API ermee om via setCardType('physical'). Gebruik setCardType('eGift') om terug te schakelen.

Methode	Beschrijving
`setCardType(type)`	`'eGift'` of `'physical'`. Als je `'physical'` kiest, selecteert hij de eerste fysieke variant en afbeelding
`getPhysicalProduct()`	Het fysieke cadeaubonproduct
`getPhysicalVariants()`	Varianten van het fysieke product
`getPhysicalImages()`	Afbeeldings-URL's van het fysieke product
`setPhysicalVariant(variantId)`	Selecteer een fysieke variant (alleen fysiek type)
`setPhysicalDeliveryAddress(address)`	Stel het bezorgadres in (alleen fysiek type): `firstName`, `lastName`, `address`, `zipCode`, `city`, `country` en optioneel `state`
`isPhysicalCard()`	`true` wanneer het fysieke type is geselecteerd

uploadCustomDesign(file, options?)¶

Uploadt de eigen afbeelding van een koper en retourneert de URL, die je kunt doorgeven aan setImage().

const { url } = await window.GiftHeroAPI.uploadCustomDesign(file);
window.GiftHeroAPI.setImage(url);

Het bestand moet een JPG-, PNG-, GIF- of WebP-afbeelding zijn, standaard maximaal 5 MB. Je kunt de limieten wijzigen met options.maxSize (in bytes) en options.allowedTypes. De methode geeft een fout met een duidelijk bericht wanneer het bestand wordt geweigerd.

React-integratievoorbeeld¶

Een volledig React-integratievoorbeeld is beschikbaar op JSFiddle. Het laat zien hoe je de API initialiseert, een eigen cadeaubonselectie-interface bouwt en de stroom voor toevoegen aan de winkelwagen afhandelt:

Bekijk het React-voorbeeld op JSFiddle