Combora — Gebruikershandleiding

1Wat Combora is

Combora maakt bundels en automatische aanbiedingen in je Shopify-winkel: het groepeert producten, past de juiste korting toe in de winkelwagen en bij het afrekenen, en toont de aanbieding in je thema via kant-en-klare blokken. Jij configureert de aanbieding in het admin, en de korting wordt berekend door een Shopify Function binnen het afrekenproces zelf — de in rekening gebrachte prijs is die welke het platform zelf berekent, niet een script in de browser.

Er zijn 8 bundeltypes. Deze tabel helpt je kiezen:

Twijfel je tussen types, dan heeft de app zelf een gids: onder Bundel maken opent de link "Weet je het niet zeker?" een wizard, en elk type heeft een paneel "Bekijk hoe het werkt" met voorbeelden.

2Aan de slag

2.1 Wat de app aanmaakt bij installatie

Het installeren van Combora verandert niets zichtbaars in je winkel. Op de achtergrond bereidt de app de datastructuren voor waarin je bundels gepubliceerd worden (metaobjects en metafields met het voorvoegsel combora — het technische detail staat in de bijlage voor ontwikkelaars) plus één automatische korting genaamd "Combora" onder Kortingen, die elke prijs toepast. Verwijder of bewerk deze niet handmatig: de app onderhoudt hem zelf.

2.2 Zet de cadeau-engine aan (app-embed)

Ga je Cadeau bij aankoop gebruiken (of combo's met een cadeau), zet dan de app-embed Combora Gift aan: Onlinewinkel → Aanpassen → Themainstellingen → App-embeds → Combora Gift. Dit is het onderdeel dat het cadeau automatisch toevoegt aan en verwijdert uit de winkelwagen. Zonder deze embed zou de cadeaukorting nog steeds correct zijn, maar het cadeauproduct zou zichzelf niet toevoegen.

2.3 Voeg de blokken toe aan je thema

Elk bundeltype wordt op de winkelvloer getoond via een themablok. Je voegt ze eenmalig toe onder Onlinewinkel → Aanpassen, in het bijpassende template:

Je hoeft dit niet uit je hoofd te leren: elke bundeleditor heeft een kaart "Waar dit verschijnt" die het juiste blok noemt, plus een link "Voorbeeld in je live thema" die de themaeditor opent met dat blok al klaar om in het juiste template ingevoegd te worden.

3Rondleiding door de app

De app staat onder Apps → Combora. Het menu heeft zes onderdelen — Home, Bundels, Inzichten, Abonnementen, Help en Instellingen — plus de supportchat, die op elk scherm aanwezig is:

Home

Het welkomstscherm en de polsslag van je installatie. Zolang je nog aan het instellen bent, toont het een checklist in drie stappen — maak je eerste bundel, publiceer hem en (als je aanbieding een cadeau bij aankoop is) zet de cadeau-engine aan in je thema. De checklist is niet decoratief: elke stap vinkt zichzelf alleen af als het daadwerkelijk in je winkel is gebeurd, de actieknop staat alleen bij de stap die aan de beurt is, en als je later alles depubliceert, komt de checklist terug en weerspiegelt hij de werkelijkheid. Eenmaal compleet, viert Home dit met een directe link om je winkel te bekijken (je kunt de melding altijd wegklikken).

Onder de checklist: je meest recente bundels met hun status, een aandachtsbalk als een bundel aandacht nodig heeft (bijvoorbeeld omdat je een product hebt gearchiveerd waar de bundel uit bestond — de app detecteert dat zelf en markeert het zonder iets te depubliceren), en een strook met je huidige abonnement.

Bundels

De lijst van al je bundels: zoeken op naam, filteren op status (Gepubliceerd / Concept), acties per rij (dupliceren, publiceren/naar concept verplaatsen, verwijderen) en meervoudige selectie met bulkacties. Alles wordt hiervandaan aangemaakt met Bundel maken.

Inzichten

Prestatiegegevens van je bundels over echte bestellingen: toegeschreven omzet, % van de bestellingen met een bundel, geleverde besparing, gemiddelde bestelwaarde en een tijdgrafiek. Detail in hoofdstuk 17.

Abonnementen

Je huidige abonnement en de upgrademogelijkheden. Het Gratis-abonnement staat 3 gepubliceerde bundels tegelijk toe; de betaalde abonnementen kennen geen limiet (hoofdstuk 18).

Help

Veelgestelde vragen en uitleg van de begrippen (arbitrage tussen bundels, cadeaus, blokken).

Diagnose (een tabblad binnen Help)

Het gezondheids- en supportpaneel staat als een tabblad binnen Help (kiezer "Gidsen | Diagnose" bovenaan): live controles van de hele installatie, het gebeurtenislogboek en het supportrapport dat je kopieert wanneer er iets misgaat (hoofdstuk 19).

Supportchat (zwevende bubbel)

Rechtsonder op elk scherm staat een chatbubbel 💬 om rechtstreeks met support te praten: gesprekken per onderwerp, geschiedenis, en een melding of support beschikbaar is of afwezig. Alleen wat jij schrijft wordt gedeeld — nooit de gegevens van je klanten.

Instellingen

App-taal (7 talen), Widgetontwerp (het winkelbrede stijlsjabloon — hoofdstuk 13), handmatige kortingssynchronisatie en ontwikkelaarstoegang.

4Opbouw van de editor

Elk type deelt dezelfde editor; alleen het onderdeel producten en prijzen verandert. Een gloednieuwe bundel ziet er zo uit:

4.1 Basisgegevens

Bundelnaam

Intern. Alleen jij ziet dit; het is er zodat je de bundel terugvindt in je lijst.

Titel op de winkelvloer

Wat de klant ziet als naam van de aanbieding in de winkelwagen en bij het afrekenen. Vertaalbaar. Het is ook de tekst van de kortingsregel (afgekapt tot 100 tekens).

Badgetekst

Een optionele korte badge ("Beste waarde") die je thema als uitlichting kan tonen.

4.2 Planning

Optionele start- en einddatum. Leeg = de aanbieding gaat live bij publicatie en verloopt nooit. Een gepubliceerde bundel buiten zijn venster stopt automatisch met de korting toepassen en past hem opnieuw toe zodra hij weer binnen het venster valt, zonder dat jij iets hoeft te doen.

4.3 Producten

Afhankelijk van het type kies je specifieke producten (en, binnen elk product, kun je alleen bepaalde varianten aanvinken) of een collectie. De reikwijdte "elk product in de winkel" bestaat alleen bij cadeau bij aankoop, als voorwaarde. De kiezer is Shopify's standaardkiezer:

4.4 Prijs

Elk type heeft zijn eigen onderdeel (percentage, bedrag, vaste prijs, staffels, beloning…). Het staat gedocumenteerd in het hoofdstuk van elk type. In alle gevallen wordt de in rekening gebrachte prijs door Shopify bij het afrekenen berekend op basis van de gepubliceerde configuratie: wat de blokken tonen is informatief.

4.5 Abonnementen

Standaard kan een klant een bundelartikel niet als abonnement kopen (dit beschermt het afrekenproces tegen abonnementsprijzen die vermengd raken met bundelkortingen). Bij de types waar het zin heeft (mix & match, stel je eigen box samen en cadeau bij aankoop) is er een geavanceerde opt-in, "Abonnementen toestaan in deze bundel (geavanceerd)"; als je die aanzet, toont de editor een melding die eraan herinnert wat dit inhoudt.

4.6 De rechterkolom (en twee onderdelen in de hoofdtekst)

Naast Opslaan (en Opslaan als concept bij een nog niet gepubliceerde bundel), met de balk Niet-opgeslagen wijzigingen / Opslaan / Verwerpen bovenaan, organiseert de editor de rest zo:

Status + actie (kolom)

Publiceren (of Bundel bijwerken als al gepubliceerd) en Naar concept verplaatsen. Publiceren zet de aanbieding live; naar concept verplaatsen trekt hem terug, met behoud van de hele configuratie.

Testmodus (hoofdtekst)

Vink "Publiceren in testmodus" aan om de bundel uit te proberen zonder hem aan je klanten te tonen. De widgets verschijnen alleen in de themaeditor — open daar het productsjabloon en de bundel staat precies waar hij komt. In je winkel verschijnen ze nooit, ook niet via de voorbeeldlink van een conceptthema. Zolang de bundel in testmodus staat, wordt de korting alleen berekend voor klanten met de tag combora-test; voor iedereen anders bestaat de bundel eigenlijk niet. Om het hele afrekenproces te doorlopen, voeg je die tag toe aan je eigen testklant (Admin → Klanten) en log je als die klant in op de winkelvloer. Vink het vakje uit en druk op Bundel bijwerken en de bundel gaat live, van toepassing op iedereen die aan de voorwaarden voldoet. In de lijst krijgt een bundel in testmodus de badge Testmodus.

Zichtbaarheid in de catalogus (hoofdtekst)

Alleen vaste bundels: of het hoofdproduct van de bundel in je catalogus verschijnt of niet (hoofdstuk 5).

Vóór het publiceren (kolom)

De checklist die publiceren blokkeert totdat de essentiële zaken klaar zijn (titel, producten, prijs…).

Wat je klant ziet (kolom)

Zolang de aanbieding nog iets mist, legt deze kaart uit wat ontbreekt en toont een voorbeeld van de inhoud. Zodra de aanbieding compleet is, maakt de kaart plaats voor het echte widgetvoorbeeld onder Voorbeeld bekijken. Het uiteindelijke uiterlijk hangt af van je thema.

Voorbeeldstijl (kolom, alleen bij al aangemaakte bundels)

Noemt het actieve widgetontwerp van deze bundel en biedt Voorbeeld bekijken (de widget op volledig formaat in een venster) en Ontwerp aanpassen (de ontwerpstudio van deze bundel: presets, volgorde van elementen en styling per element — hoofdstuk 13). Bij een gloednieuwe bundel verschijnt dit na de eerste opslag.

Waar dit verschijnt (kolom)

Het themablok dat dit type weergeeft en de directe link naar de themaeditor.

Een bundel met planning toont ook zijn vensterbadge (Gepland / Actief / Beëindigd) en de knop Planning verwijderen om terug te gaan naar "actief bij publicatie".

4.7 Meldingen die de editor kan tonen

• Overlap: als de producten van de bundel al in andere gepubliceerde bundels zitten, verschijnt een banner met de waarschuwing: "Bij het afrekenen geldt alleen de beste aanbieding per regel: bundels stapelen niet". Dit is geen fout — het is informatie (zie hoofdstuk 14).
• Geen besparing / prijs 0: bij een vaste bundel met een bundelprijs markeert de editor het vóór publicatie als de gekozen prijs niets bespaart (of 0 is).
• Lege pool: een collectie zonder in aanmerking komende producten wordt getoond als opmerking in het voorbeeld en, als je probeert te publiceren, als fout met uitleg.

4.8 Een gepubliceerde bundel bewerken

Wanneer je een gepubliceerde bundel bewerkt, worden je wijzigingen opgeslagen zonder je winkelvloer te bereiken. De editor toont je wijziging, je klanten blijven de gepubliceerde versie tegen de gepubliceerde prijs zien, en de bundel is in je lijst gemarkeerd als Niet-gepubliceerde wijzigingen. Druk op “Bundel bijwerken” om ze te publiceren, of verwerp ze via de melding in de editor. Zo kun je wijzigingen rustig voorbereiden. "Naar concept verplaatsen" haalt de aanbieding meteen van de winkelvloer; opnieuw publiceren herstelt hem precies zoals hij was.

5Vaste bundel

Een vaste set producten die als één geheel wordt verkocht. Het is het enige type dat ook een met één klik koopbaar product in je catalogus aanmaakt: een "hoofd"-product (een native Shopify-bundel) waarvan de onderdelen zich automatisch ontvouwen bij het afrekenen.

5.1 Configuratie

1. Producten: voeg de onderdelen toe (specifieke varianten) en hoeveel van elk. Maximaal 30 onderdelen per bundel.
2. Prijs — twee elkaar uitsluitende modi:
   • Vaste bundelprijs: je typt de totaalprijs in (bijv. $1,299.00). De besparing wordt berekend ten opzichte van de som van de onderdelen.
   • Korting toepassen: een percentage of een bedrag korting op de som van de onderdelen.
3. Zichtbaarheid in de catalogus: vaste bundels zijn echte Shopify-producten, dus jij bepaalt of de bundel ook in je catalogus verschijnt of alleen via de widget bereikbaar is:
   • Verborgen — alleen via de widget (standaard): de bundel verschijnt niet in collecties, in de zoekfunctie van de winkelvloer, of in aanbevelingen. De productpagina blijft actief zodat de knop van de widget werkt.
   • Zichtbaar — een normaal catalogusproduct: het verschijnt in collecties en zoekresultaten zoals elk ander product.
4. Publiceren. Bij publicatie maakt Combora het hoofdproduct in je catalogus aan (of werkt het bij) — en als de bundel nog geen afbeelding heeft, kopieert het die van het eerste onderdeel, in BEIDE zichtbaarheidsmodi (een verborgen bundel is nog steeds te zien in de winkelwagen, bij het afrekenen en in de bestelmails). Het overschrijft nooit een afbeelding die jij hebt ingesteld; wijzig hem wanneer je wilt onder Admin → Producten.

5.2 Wat je klant ziet

5.3 Details en limieten van dit type

• Onderdelen moeten varianten met voorraad zijn; het hoofdproduct erft de beschikbaarheid.
• Het hoofdproduct beheert zichzelf: de bundel naar concept verplaatsen of verwijderen trekt hem terug van de winkelvloer (geverifieerd tijdens het schrijven van deze handleiding). Verwijder het niet handmatig.
• Standaard is het hoofdproduct verborgen voor de catalogus. Voordat deze optie bestond, verscheen het in /collections/all als een kaart zonder afbeelding; al gepubliceerde bundels werden automatisch omgezet naar "Verborgen". Geef je de voorkeur aan het oude gedrag, zet het dan om naar Zichtbaar.
• Maximaal 30 onderdelen. De vaste prijs wordt met exacte afronding over de onderdelen verdeeld (de som van de delen is altijd gelijk aan het totaal).
• De vaste bundel is ook van toepassing als de klant de onderdelen afzonderlijk toevoegt in exact de juiste aantallen — het afrekenproces groepeert en verrekent ze op precies dezelfde manier.

6Mix & match

De klant kiest minimaal N artikelen uit een groep en de hele groep komt met korting eruit.

6.1 Configuratie

1. Producten: de in aanmerking komende groep kan bestaan uit specifieke producten — waarbij je, als je wilt, binnen de kiezer alleen bepaalde varianten van elk aanvinkt — of een collectie (die zichzelf bijwerkt).
2. Aantal: het minimumaantal artikelen om in aanmerking te komen, en optioneel een maximum (boven het maximum worden de extra artikelen tegen de volle prijs betaald).
3. Korting: een percentage of een bedrag, toegepast op elk in aanmerking komend artikel in de winkelwagen zodra het minimum is bereikt.

6.2 Wat je klant ziet

6.3 Details van dit type

• Een winkelwagen onder het minimum wordt niet geblokkeerd: de klant betaalt de volle prijs totdat hij in aanmerking komt.
• Met een ingesteld maximum stopt de kiezer met het accepteren van vinkjes zodra het plafond is bereikt, en in de winkelwagen krijgen alleen de eerste eenheden tot het maximum korting.
• Aantallen tellen per eenheid: 3 eenheden van hetzelfde in aanmerking komende product komen ook in aanmerking voor een minimum van 3.

7Volumekorting

Prijsstaffels op basis van aantal: "koop minstens 2 → 10%, minstens 4 → 20%". De staffel wordt per product bepaald: het aantal van elk in aanmerking komend product in de winkelwagen bepaalt zijn eigen staffel, en de bereikte staffel geldt voor de eenheden van dat product. Voorbeeld met "4+ → 20%": 4 eenheden van hetzelfde board → 20% korting op alle 4; maar 2 eenheden van het ene board + 2 van een ander → elk product valt in de staffel 2+ (10%), niet in 4+. Aantallen van verschillende producten tellen niet bij elkaar op.

7.1 Configuratie

1. Producten: specifieke producten of een collectie (net als bij mix). Wil je alleen bepaalde varianten van een product, vink ze dan aan in de kiezer wanneer je het kiest.
2. Staffels: elke staffel is "Koop minstens N" + een korting (percentage of bedrag). Voeg er zoveel toe als nodig met "Staffel toevoegen" (tot 50).

7.2 Wat je klant ziet

7.3 Details van dit type

• Alleen de hoogste bereikte staffel geldt (staffels tellen niet bij elkaar op).
• Staffels kunnen waardetypes combineren (sommige %, sommige bedrag).
• Een vast kortingsbedrag wordt proportioneel en exact over de regels verdeeld.

8Koop X krijg Y (BOGO)

Koop X eenheden en de volgende Y eenheden komen met een beloning. De beloning kan gratis (100%) zijn, een percentage, een kortingsbedrag of een vaste prijs per eenheid.

8.1 Configuratie

8.2 Wat je klant ziet

8.3 Details van dit type

• De aanbieding herhaalt zich in hele blokken: met "2+1" zijn 6 eenheden = 2 gratis; 5 eenheden = 1 gratis.
• Het themablok dat het weergeeft is Combora volume table (het presenteert "koop X krijg Y" als een besparingstabel).
• De beloning "vaste prijs" rekent precies die prijs voor elke beloonde eenheid.

9Cadeau bij aankoop (GWP)

Voegt automatisch een cadeauproduct (voor $0.00) toe zodra de winkelwagen aan de voorwaarde voldoet, en verwijdert het als er niet meer aan wordt voldaan. Het is het meest geautomatiseerde type: de app-embed Combora Gift beheert het cadeau zonder dat de klant iets hoeft te doen.

9.1 Configuratie

1. Het cadeau: een specifieke variant die wordt toegevoegd zodra de klant in aanmerking komt.
2. Voorwaarde om te ontgrendelen — vier opties:
   • Op basis van minimale besteding: de winkelwagen bereikt een bedrag (bijv. $1,000).
   • Op basis van aantal artikelen: bereikt N eenheden.
   • Besteding en aantal (beide): beide zijn vereist.
   • Door een combinatie van producten mee te dragen: een specifieke lijst artikelen (van 2 tot 5; één eenheid van elk) die allemaal in de winkelwagen moeten zitten.
3. Wat meetelt voor de voorwaarde: elk product in de winkel, specifieke producten, of collecties.

9.2 Wat je klant ziet

De balk heeft vier toestanden en benoemt het cadeau en wat meetelt vanaf de lege winkelwagen: voordat de klant begint noemt hij de regel ("besteed $1,000 aan dat board en krijg de skiwax gratis"), halverwege zegt hij wat er nog ontbreekt, bij het overschrijden van de drempel kondigt hij het cadeau bij naam aan, en haalt de klant het cadeau er handmatig uit, dan zegt hij dat in plaats van op "wordt toegepast" te blijven staan. Tellen er meer dan drie producten mee, dan zegt de balk in aanmerking komende producten en voegt hij een uitklapper "Welke producten tellen mee?" toe die ze opsomt.

9.3 Details en beveiligingen van dit type

• Het cadeau zelf telt niet mee voor de kwalificerende besteding.
• De drempel wordt gemeten op de catalogusprijs van wat meetelt, niet op wat de klant uiteindelijk betaalt: een andere aanbieding die diezelfde regels verlaagt, knabbelt er dus nooit aan. De balk, het automatische cadeau en het afrekenen lezen hetzelfde getal.
• Als de klant het cadeau handmatig verwijdert, respecteert de app dat en voegt het niet opnieuw toe in die sessie; de balk in de winkelwagen zegt dat expliciet ("Cadeau verwijderd") in plaats van te blijven "toepassen".
• Als je de aanbieding intrekt (naar concept, einde van het venster) terwijl er nog open winkelwagens zijn die al het cadeau bevatten, verwijdert de engine die weesregel uit zichzelf zodra de winkelwagen weer verandert — het wordt nooit in rekening gebracht.
• Als het cadeau geen voorraad meer heeft, voegt de aanbieding het simpelweg niet toe (het blokkeert de aankoop niet).
• Bescherming tegen onterecht in rekening brengen: een validatie bij het afrekenen voorkomt dat er wordt betaald voor een cadeau dat als cadeau is gemarkeerd maar met een prijs is binnengekomen — de klant betaalt nooit per ongeluk voor een artikel dat als cadeau is aangeduid. De validatie treedt alleen op bij het afrekenen, nooit tijdens het browsen.
• Wanneer "wat meetelt" collecties is, lost de app de producten van de collectie op bij publicatie (en ververst ze elke nacht, of meteen als je opnieuw publiceert — de twee snelheden uit hoofdstuk 4.3), zodat de voortgangsbalk en het automatische cadeau net zo werken als bij specifieke producten. De ene uitzondering: een enorme collectie (meer dan ~150 producten) kan niet vanuit de browser worden voorspeld — de balk wordt voor die aanbieding niet getoond, maar het cadeau en de prijs blijven correct (de server bepaalt ze).
• Een cadeau waarvan "wat meetelt" elk product in de winkel is, kan met het blok Combora gift offer op elke productpagina worden geadverteerd: als je die reikwijdte kiest, toont de editor het selectievakje "Toon dit cadeau-aanbod op elke productpagina". Uit (de standaard), dan wordt de aanbieding alleen in de winkelwagen getoond — de voortgangsbalk en het automatische cadeau werken hetzelfde; aan, dan wordt hij ook geadverteerd met een kaart op elke productpagina (de aanbieding heeft geen specifieke producten om aan te vinken, dus het blok leest hem uit de gepubliceerde index van de winkel). De bewuste uitzondering blijft de eigen pagina van het cadeauproduct: een prijs is geen lokmiddel.

10Stel je eigen box samen

De klant vult een box van vaste grootte (bijv. 3 artikelen) met wat hij kiest uit een groep. Elke complete box wordt met korting of tegen een gesloten boxprijs in rekening gebracht.

10.1 Configuratie

10.2 Wat je klant ziet

Het gebruikt hetzelfde blok Combora mix & match en dezelfde kiezer met een teller als in hoofdstuk 6: "selecteer 3", een voortgangsteller, een CTA met het aantal. Het verschil zit in de rekensom: hier worden boxen per complete box in rekening gebracht — bij een box van 3 zijn zes artikelen twee boxen; zeven artikelen zijn twee boxen plus één artikel tegen de volle prijs.

10.3 Details van dit type

• In aanmerking komende groep: specifieke producten (met hun varianten, als je er slechts enkele aanvinkt) of een collectie (de visuele kiezer verschijnt bij elke reikwijdte, net als bij mix — bij collecties wordt de lijst op het moment van publicatie berekend en elke nacht ververst).
• De boxprijs wordt exact over de artikelen verdeeld; bij valuta's zonder decimalen (JPY) of met drie decimalen (BHD) respecteert de verdeling de valuta.
• Het ondersteunt de opt-in voor abonnementen (hoofdstuk 4.5).

11Aanvullende producten (vaak samen gekocht)

Een hoofdproduct stelt aanvullende producten voor; als de klant de hele set neemt, krijgt hij korting. Het is de klassieke "vaak samen gekocht" op de productpagina.

11.1 Configuratie

11.2 Wat je klant ziet

11.3 Details van dit type

• De korting geldt zodra het hoofdproduct en minstens één aanvulling in de winkelwagen zitten; hij dekt de regels van de set.
• Het blok kan ook aan het winkelwagentemplate worden toegevoegd als laatste cross-sell-zetje.
• Aanvullingen zonder voorraad verschijnen uitgeschakeld met hun melding, en worden nooit vooraf aangevinkt.

12Combo

Het geavanceerde type: het stapelt twee of meer sub-aanbiedingen (van elk van de andere types) in één bundel. Het belangrijkste verschil met het publiceren van aparte bundels: binnen een combo tellen de sub-aanbiedingen op — de klant kan tegelijk de volumekorting en het cadeau krijgen.

12.1 Configuratie

Elke rij vouwt ter plekke open met het pijltje, en de sub-aanbieding wordt inline bewerkt: zijn eigen producten, zijn eigen staffels of beloning. Elke sub-aanbieding beïnvloedt alleen zijn eigen producten.

12.2 Wat je klant ziet

Een combo wordt in het blok Combora bundle niet als kaart gepromoot: dat blok somt vaste bundels op, die één prijs en één knop hebben, en een combo heeft geen van beide. Elke sub-aanbieding wordt in plaats daarvan gepromoot door zijn eigen blok — de volumetabel voor een volume-sub-aanbieding, de cadeaubalk voor een cadeau-sub-aanbieding — en de combo laat zijn volle effect zien in de winkelwagen, waar elk deel met zijn eigen badge werkt: de volumekorting op zijn regels en het automatisch toegevoegde cadeau voor $0.00.

Gemeten in de demowinkel op een combo die "2 of meer van dit board → 15% korting" stapelt op "een gratis muts zodra je $900.00 aan dat board hebt": twee boards gaan van $1,040.00 naar $850.00 — de 15% en de muts voor $0.00 — en drie gaan van $1,540.00 naar $1,275.00. Twee losse bundels zouden beide nooit op dezelfde regel doen; binnen een combo tellen de sub-aanbiedingen op (hoofdstuk 14).

12.3 Details van dit type

• Sub-aanbiedingen tellen op binnen de combo, maar de combo strijdt als geheel tegen de andere bundels volgens de regel van de beste aanbieding per regel.
• Het cadeau in een GWP-sub-aanbieding gebruikt dezelfde automatische toevoeg-engine als het cadeautype.
• Groottelimiet: de platgeslagen productset van de combo mag niet meer dan 50 items bevatten (de editor toont het: "Uses X of 50").
• De editor heeft een venster "Hoe combo's werken" met een begeleid voorbeeld, en elke sub-aanbieding definieert "Producten waarop deze aanbieding van toepassing is" — een sub-aanbieding zonder specifieke producten toont een waarschuwing omdat hij niets kan beprijzen.
• Een BOGO-sub-aanbieding binnen een combo biedt een percentage- of bedragbeloning (de "vaste prijs per eenheid" is exclusief voor de zelfstandige BOGO).

13De widget vormgeven

De blokken van Combora worden geleverd met een uiterlijk dat bij elk thema past, maar je kunt ze vanuit de app ontwerpen, zonder CSS aan te raken: kies een stijl, wijzig de volgorde en verberg elementen, en pas kleuren, groottes en vormen per element aan. Dit alles met een voorbeeld dat dezelfde rendering-engine als je winkelvloer gebruikt, dus wat je ziet is wat wordt gepubliceerd.

13.1 Twee plekken waar je ontwerpt

Een bundel waar nog niets aan is veranderd, toont de melding "Deze bundel volgt het widgetsjabloon van je winkel". Zodra je daar een preset kiest, gaat die bundel zijn eigen weg.

13.2 De stijlen (presets)

Winkelsjabloon

Alleen in het ontwerp van een bundel: volgt wat je in Instellingen hebt gedefinieerd. Dit is de beginwaarde. Is er nog geen sjabloon, dan gelden de instellingen van het blok in de themaeditor.

Themaeditor

De eigen instellingen van het blok in je themaeditor winnen (accent, hoeken, stijlmodus). Dit is het klassieke gedrag, het gedrag dat je had vóór de studio bestond.

Combora

Combora's verzorgde uiterlijk: een kaart met een eigen achtergrond, randen en schaduwen. Consistent in elk thema.

Zoals het thema

Minimale decoratie: de typografie en kleuren van je thema domineren. Voor thema's met een sterk eigen karakter.

Ongestyled

Schone markup, geen decoratie, zodat je ontwikkelaar zijn eigen CSS kan schrijven (themaeditor → aangepaste CSS). De haakjes zijn de klasse .combora-w en de variabelen --combora-*.

Aangepast

Opent de bedieningselementen hieronder: layout, algemene stijl en fijnafstemming per element.

13.3 Layout: volgorde wijzigen en verbergen

Met de preset Aangepast verschijnt Layout: een lijst van de elementen van de widget die je kunt slepen (of verplaatsen met de pijltjes) om hun volgorde te wijzigen, plus een oogicoon om de optionele elementen te verbergen.

De elementen hangen af van het bundeltype, omdat elk type een andere widget tekent:

13.4 Algemene stijl en fijnafstemming

Algemene stijl verandert de hele widget in één keer: accentkleur, achtergrond van de kaart, tekstkleur, hoeken (scherp / zacht / rond), schaduw (geen / zacht / gemiddeld) en dichtheid.

Fijnafstemming per element opent elk element afzonderlijk — titel, prijs, besparing, badge, knop, kaart, thumbnails, labels — met wat voor elk zinvol is: grootte, gewicht, kleur, hoofdletters, opvulling, vorm, randkleur, kleur van de doorgestreepte prijs… Elke instelling heeft een "Terug naar thema" om alleen die aanpassing ongedaan te maken, en onderaan staat "Alle aanpassingen resetten".

• Definieer je de Besparing niet, dan volgt hij de stijl van de Badge.
• De tekstkleur van de knop kan niet gekozen worden: hij wordt automatisch afgeleid op basis van contrast met de achtergrond die je kiest, zodat hij nooit onleesbaar kan worden.
• Waarden zijn begrensd tot verstandige bereiken: je kunt geen grootte invoeren die de widget op mobiel kapotmaakt.

13.5 Het voorbeeld (en wat het NIET is)

Rechts staat een paneel met het label "Alleen voorbeeld". Het verschil is belangrijk:

• Links = jouw ontwerp. Wat je daar aanpast wordt opgeslagen en gaat naar de winkelvloer.
• Rechts = de lens. Voorbeeldachtergrond (licht / donker / een aangepaste kleur), basis- tekstgrootte, sleufbreedte (een smalle productkolom versus een brede sectie) en een benadering van je typografie. Het is er om te controleren of je ontwerp overeind blijft op verschillende plekken. Het verandert niets in je winkel of in je ontwerp.

En in de kolom van de bundeleditor vertelt de kaart "Voorbeeldstijl" welk ontwerp actief is ("Actief ontwerp: Combora") en biedt hij twee knoppen: Voorbeeld bekijken, die de widget op volledig formaat in een venster opent ("Zo ziet het eruit in je winkel"), en Ontwerp aanpassen, die naar de studio van deze bundel gaat. De echte typografie en achtergrond komen uit je thema, dus kijk voor de definitieve goedkeuring naar de widget in de themaeditor.

14Bundels onderling combineren

Je kunt zoveel bundels publiceren als je abonnement toestaat, zelfs over dezelfde producten. De regels voor samenleven liggen vast en zijn voorspelbaar:

1. De beste aanbieding per regel. Voor elk winkelwagenartikel past Shopify de aanbieding toe die dat artikel het meest verlaagt. Twee bundels tellen nooit op bij dezelfde regel.
2. Verschillende bundels kunnen in dezelfde winkelwagen samengaan — elk op zijn eigen regels. Een mixkorting op de boards en een cadeau op basis van besteding kunnen tegelijk gelden omdat ze op verschillende regels werken.
3. Bij gelijkspel wint de oudste bundel (degene die je het eerst hebt aangemaakt).
4. De uitzondering is de combo: zijn sub-aanbiedingen tellen onderling wél op (hoofdstuk 12).

En kortingen die niet van Combora zijn? De regel hierboven geldt voor Combora-pakketten onderling. Bij kortingen van derden beslist Shopify, en we hebben het in een live winkel geverifieerd: twee productkortingen (een Combora-pakket en een eigen automatische korting of productcode) tellen nooit op bij hetzelfde artikel — Shopify past alleen de grootste van de twee toe, ook als beide als combineerbaar zijn gemarkeerd; ze kunnen naast elkaar bestaan op verschillende regels van dezelfde bestelling. Een bestelkorting (zeg een code van −10% op de hele bestelling) wordt daarna wél afgetrokken, bovenop de al verlaagde prijzen — het standaardgedrag van Shopify met elke app.

Een echt numeriek voorbeeld (geverifieerd in de winkel)

In de demowinkel hoort één product bewust bij twee bundels: het board dat onderdeel is van de vaste bundel, is ook het onderwerp van de volumebundel. Alleen krijgt het het volumeniveau dat zijn aantal oplevert; samen met het andere onderdeel van de vaste bundel, in de exacte aantallen, wordt ook de vaste bundel kandidaat en houdt de regel de beste van de twee. Hetzelfde product, twee bundels, één prijs per regel — nooit allebei.

15Bulkaanmaak

Vanuit de galerij Bundel maken zijn er twee stromen om veel bundels tegelijk aan te maken. Beide maken concepten aan: niets bereikt de winkelvloer totdat je beoordeelt en publiceert.

15.1 Genereren vanuit een collectie

1. Kies de collectie.
2. Kies het sjabloon: "Eén multipack per product" (een vaste bundel van N eenheden voor elk product) of "Eén bundel voor de hele collectie".
3. Stel het aantal en de korting in, en druk op Concepten aanmaken.

Wat elk sjabloon werkelijk aanmaakt

Eén multipack per product loopt de collectie door en maakt één concept-vaste-bundel per product aan: N eenheden van de eerste variant van dat product (volgorde op positie), met de door jou gekozen korting toegepast op de som. Elk concept is een normale vaste bundel — open hem om de variant te wijzigen, over te stappen op een vaste bundelprijs, een badge toe te voegen… — en wanneer je hem publiceert, wordt hij zijn eigen met één klik koopbare product, zoals elke vaste bundel (hoofdstuk 5).

Eén bundel voor de hele collectie maakt precies één concept aan van het flexibele type dat je kiest (volume, mix & match, stel je box samen of koop X krijg Y) waarvan de pool van in aanmerking komende producten de collectie zelf is. Het lidmaatschap volgt je catalogus: de pool wordt opgelost wanneer je publiceert en elke nacht ververst (of meteen bij opnieuw publiceren), zodat producten die je later aan de collectie toevoegt vanzelf bij de aanbieding gaan horen zonder dat je de bundel aanraakt.

Producten worden overgeslagen, en de resultaatbanner meldt het, wanneer ze niet Actief zijn in je catalogus, wanneer ze geen koopbare variant hebben — en wanneer ze zelf Combora-packproducten zijn: een gegenereerd pack nestelt nooit een ander pack.

Uitgewerkte voorbeelden

Hetzelfde scherm, zeven configuraties, en precies wat elke configuratie oplevert:

15.2 Importeren vanuit een CSV

Voor grote catalogi of voor migratie vanuit een andere app. De pagina bevat de volledige formaatreferentie, een downloadbaar sjabloon met één voorbeeld per type en een exportknop (hij downloadt al je bundels in hetzelfde formaat, klaar om opnieuw te importeren in een andere winkel).

• Importeerbare types: fixed, volume, mix_and_match, build_a_box, bogo (de types met een cadeau, een anker of sub-aanbiedingen worden in de editor aangemaakt).
• Verwijzingen op basis van product- of collectie-handle, of Shopify GID.
• In components (alleen vast): handle:quantity gescheiden door |.
• Tot 200 rijen per import; een groter bestand wordt afgekapt en dat wordt gemeld.

16Dagelijks beheer

16.1 De lijst

Zoeken op naam, filteren op status en, per rij: Dupliceren (maakt een conceptkopie), Publiceren / Naar concept verplaatsen en Verwijderen. De datum bij elke rij is de laatste update (hover voor de tooltip).

16.2 Bulkacties

16.3 De levenscyclus van een bundel

Concept

Onzichtbaar voor de winkelvloer. Onbeperkt te bewerken.

Gepubliceerd

De aanbieding is actief (binnen zijn planningsvenster). Bewerken verandert niets live totdat je op Bundel bijwerken drukt.

Naar concept verplaatsen

Trekt de aanbieding onmiddellijk terug; de configuratie blijft intact zodat je opnieuw kunt publiceren.

Verwijderen

Verwijdert de bundel en trekt zijn korting in (en het hoofdproduct, als het een vaste bundel was). Kan niet ongedaan worden gemaakt. De analytics van eerdere bestellingen blijft bewaard.

16.4 Wat Combora zelf doet, terwijl jij slaapt

Vier automatische processen houden je winkel up-to-date zonder dat jij iets hoeft te doen. Je hoeft ze niet te configureren of in de gaten te houden — ze staan hier gedocumenteerd zodat je weet waarom dingen zichzelf herstellen:

17Inzichten

Verkoop je in meerdere valuta's, dan staat er een valutakiezer naast de cijfers: de bedragen worden getoond in de gekozen valuta (de besteltellers zijn globaal).

Onder de cijfers staan drie grafieken voor de gekozen periode, allemaal met één punt per dag en een tooltip:

• Bestellingen met een bundel over tijd — staven, met de waarde afgedrukt boven de staven die gegevens hebben.
• Toegeschreven omzet per dag — een lijn, om de trend te zien.
• Geleverde besparing per dag — staven: hoeveel korting je bundels elke dag hebben gegeven.

18Instellingen en abonnementen

18.1 Instellingen

• App-taal: 7 talen (Engels, Spaans, Frans, Duits, Italiaans, Portugees, Nederlands). Dit beïnvloedt het admin; wat je klant ziet, volgt de taal van je thema/markt.
• Widgetontwerp: Widgetsjabloon bewerken opent de winkelbrede ontwerpstudio — de stijl die elke bundel erft (hoofdstuk 13). Hier opslaan synchroniseert de gepubliceerde bundels opnieuw.
• Kortingen synchroniseren: je hoeft er niet op te drukken — alles synchroniseert vanzelf zodra je publiceert. Het is er als vangnet: als een bundel ooit stopte met korting geven, regenereert dit de Shopify-korting op basis van al je gepubliceerde bundels. Het is veilig om zo vaak als je wilt te gebruiken, en als er niets te herstellen was, wordt dat gemeld: Alles was al up-to-date.
• Ontwikkelaarstoegang: de publieke gegevens die je thema kan lezen (bijlage 22). De contractdocumentatie is open op elk abonnement.

18.2 Abonnementen

Vaste prijzen: we nemen nooit een percentage van je omzet, en de prijs hangt niet af van je Shopify-abonnement — een Basic-winkel en een Plus-winkel betalen hetzelfde.

• Gratis ($0/maand): tot 3 gepubliceerde bundels tegelijk (concepten tellen niet mee) met alle 8 types inbegrepen. Probeer je de 4e te publiceren, dan blokkeert de app dit met de bijpassende melding: verplaats een andere naar concept of upgrade. Bij het Gratis-abonnement tonen de blokken een discrete Powered by Combora-badge.
• Pro ($14.99/maand): onbeperkt gepubliceerde bundels en geen badge.
• Plus ($39.99/maand): alles van Pro, plus prioriteitssupport, bulk-CSV import/export (tot 200 bundels per bestand) en directe integratieondersteuning voor je ontwikkelaar (headless winkels en aangepaste thema's).

Facturering verloopt via Shopify (Managed Pricing) — het wordt beheerd en opgezegd vanuit de pagina Abonnementen zelf. De betaalde abonnementen bevatten een gratis proefperiode van 7 dagen, en als je opzegt, behoud je het abonnement tot het einde van de al betaalde cyclus. Founding-winkels (de eerste 100 installaties) behouden het volledige product voor altijd gratis.

19Diagnose en support

Diagnose (het tweede tabblad van Help) is je eerste halte wanneer iets niet klopt — en wat support zal vragen als je een ticket opent. Combora legt automatisch, per winkel, alles vast wat onderhuids faalt (op de server en in je online winkel), zelfs als de klant er nooit iets van merkt, en dit paneel legt het binnen handbereik. Het slaat helemaal geen klantgegevens op.

19.1 Gezondheidscontroles

De live status van wat support als eerste vraagt, geverifieerd tegen Shopify bij elk laden:

19.2 Gebeurtenislogboek

Elke regel is iets dat gebeurde en werd vastgelegd: een fout tijdens het publiceren, een cadeau dat Shopify weigerde toe te voegen (met de exacte reden), een korting die botste met een andere, een webhook die mislukte… Filter op niveau (Info = verwacht maar relevant, zoals de abonnementslimiet; Waarschuwing; Fout) en op gebied (publiceren, kortingen, abonnement en facturering, winkelvloer, synchronisatie…). Een leeg logboek is een goed teken: het vult zich alleen als er iets misgaat. Gebeurtenissen worden 30 dagen bewaard.

19.3 Het supportrapport

Eén document met alles wat nodig is om je winkel in één keer te diagnosticeren: de gezondheidscontroles, je abonnement en configuratie (zonder gevoelige gegevens), de publicatiestatus van elke bundel en de recentste gebeurtenissen. Neem je contact op met support, druk dan op Rapport kopiëren (of Downloaden als bestand) en voeg het toe aan het ticket — daarmee ziet degene die je helpt precies wat er is gebeurd, zonder screenshots of toegang te hoeven vragen.

• Het rapport bevat geen klantgegevens en geen sleutels: alleen gezondheid, bundelconfiguratie en technische gebeurtenissen.
• Werkt de kopieerknop niet in je browser, dan blijft de tekst geselecteerd — druk op Ctrl+C (Cmd+C op een Mac) — of gebruik de download.

20Limieten en belangrijke regels

De enige referentie voor limieten, geverifieerd tegen de code van de app:

Geldregels (altijd exact)

• Percentages ronden de korting naar beneden af (er wordt nooit afgerond in het voordeel van meer in rekening brengen).
• Bedragen en vaste prijzen worden met een exact restbedrag over de regels verdeeld: de som van de delen is altijd gelijk aan het totaal.
• Decimalen hangen af van de valuta van je winkel (JPY zonder, BHD met drie…) — twee decimalen worden nooit aangenomen.
• De in rekening gebrachte prijs wordt door Shopify bij het afrekenen berekend op basis van de gepubliceerde configuratie. Wat de themablokken tonen is informatief.

Meerdere valuta's (Shopify Markets)

Verkoop je in meerdere valuta's, dan is er niets voor jou te configureren: je bepaalt prijzen, drempels en kortingen in de valuta van je winkel, en Combora doet de rest. Een klant die in een andere valuta koopt, ziet de widgetbedragen omgerekend naar de zijne (de cadeaudrempel, de bundelprijs, de besparing van elke staffel), en bij het afrekenen wordt de korting omgerekend tegen de actuele wisselkoers van Shopify — dezelfde die je productprijzen omrekent. De gouden regel blijft gelden: wat de klant geadverteerd ziet, is precies wat het afrekenen hem in rekening brengt, in zijn valuta.

Overige regels

• Abonnementen worden op bundelregels geblokkeerd tenzij je expliciet opt-int (hoofdstuk 4.5).
• Een GWP-cadeau wordt niet geadverteerd op de eigen pagina van het cadeauproduct (een prijs is geen lokmiddel).
• Bundels die buiten hun planningsvenster gepubliceerd zijn, passen geen korting toe (ze reactiveren zichzelf).

21Problemen oplossen

Ik zie de aanbieding niet op mijn winkelvloer

① Staat de bundel op Gepubliceerd (geen concept) en binnen zijn datumvenster? ② Heb je het juiste blok aan het template toegevoegd (de kaart Waar dit verschijnt in de editor)? ③ Heb je een gepubliceerde bundel bewerkt, heb je dan op Bundel bijwerken gedrukt?

Het cadeau voegt zichzelf niet toe

① Is de app-embed Combora Gift ingeschakeld? ② Voldoet de winkelwagen aan de voorwaarde, waarbij alleen meetelt wat in aanmerking komt (het cadeau telt niet mee)? ③ Heeft de klant het handmatig verwijderd in deze sessie? ④ Is het cadeau op voorraad?

De korting in de winkelwagen is niet wat ik verwachtte

Denk aan de regel: alleen de beste aanbieding per regel. Strijden twee bundels om hetzelfde artikel, dan wint degene die het meest korting geeft (en bij gelijkspel de oudste). Optellen gebeurt alleen binnen een combo.

De app zegt: Je hebt nog een andere automatische korting actief

Dit is informatie, geen fout. Het betekent dat je je eigen automatische productkortingen hebt in Shopify. Komen een Combora-bundel en een van die kortingen op hetzelfde product terecht, dan past Shopify alleen de betere van de twee toe — twee productkortingen stapelen op hetzelfde artikel vereist Shopify Plus. Dat is een regel van Shopify, niet van Combora. Je bundels combineren wel met je bestel- en verzendkortingen, en met productkortingen die op andere producten terechtkomen. De melding noemt de specifieke overlappende korting zodat je weet welke je moet bekijken.

Ik heb gepubliceerd en er staat abonnementslimiet

Het Gratis-abonnement staat 3 gepubliceerde bundels tegelijk toe. Verplaats een andere naar concept of upgrade.

De cadeau-voortgangsbalk verschijnt niet

Hij wordt gerenderd in het winkelwagentemplate (het blok Combora gift progress) en alleen voor aanbiedingen waarvan het criterium in de browser kan worden geëvalueerd. Met collecties als wat meetelt werkt het ook, omdat de app de producten van de collectie oplost wanneer je publiceert; de enige uitzondering is een zeer grote collectie (meer dan ~150 producten), waarbij de balk niet wordt getoond, ook al werkt het cadeau nog steeds.

De selectievakjes-kiezer verschijnt niet in mix / box

De kiezer verschijnt bij elke reikwijdte: bij specifieke varianten toont hij precies die selectievakjes, en bij producten of een collectie wordt de lijst berekend wanneer je publiceert (en elke nacht ververst, of meteen als je opnieuw publiceert). Is hij toch leeg, dan heeft de in aanmerking komende groep geen koopbare producten — controleer de opmerking in het voorbeeld in de editor. In beide gevallen kan de klant producten toevoegen zoals gewoonlijk en gaat de korting in bij het kwalificeren.

Fouten bij het importeren van een CSV

Elke mislukte rij wordt vermeld met zijn reden. Herstel die rijen en voer ze opnieuw uit met alleen die rijen — de goede rijen waren al aangemaakt.

Ik vermoed dat een korting verweesd is achtergebleven

Instellingen → Kortingen synchroniseren herstelt de status. Bewerk de Combora-korting nooit handmatig in Shopify's sectie Kortingen.

22Bijlage voor ontwikkelaars: het publieke contract

Combora publiceert de gegevens van je bundels in je winkel als metaobjects en metafields onder de naamruimte combora, publiek leesbaar vanaf de winkelvloer. Elke ontwikkelaar kan een volledig aangepaste UI bouwen door deze gegevens vanuit Liquid of de Storefront API te lezen — zonder een enkele API van de app aan te roepen. Dit contract is versiegebonden en alleen additief (huidige versie: public.v1): bestaande velden worden nooit hernoemd of van type veranderd.

22.1 Wat wordt aangemaakt bij installatie

De installatie voorziet in de definities (de schema's) — zichtbaar onder Instellingen → Metafields en metaobjects en onder Inhoud → Metaobjects:

• Metaobjects: combora_bundle (de bundel), combora_component (elke onderdeelregel) en combora_tier (elke volume-/drempelstaffel). Alledrie met PUBLIC_READ-toegang vanaf de winkelvloer, publiceerbaar en vertaalbaar.
• Shop-metafields: combora.index en combora.manifest (JSON, publiek leesbaar), en combora.all_pdp_gwps (list.metaobject_reference → combora_bundle): de winkelbrede cadeaus die ervoor kozen op elke productpagina geadverteerd te worden.
• Productmetafield: combora.bundles (list.metaobject_reference → combora_bundle) — de omgekeerde index product → zijn bundels.

22.2 Wat er gebeurt bij publiceren / bijwerken / intrekken

22.3 combora_bundle veld voor veld

22.4 De descriptor eligible

De in aanmerking komende pool van de bundel, met dezelfde vorm bij elk type:

{ "mode": "all" | "products" | "collections" | "variants",
  "variants":   ["gid://shopify/ProductVariant/…"],
  "products":   ["gid://shopify/Product/…"],
  "collections":["gid://shopify/Collection/…"],
  "resolved_count": 12, "total_count": 12, "truncated": false }

Alleen de niet-lege lijsten worden opgenomen. De drie resolutiesleutels zijn informatief (bij collectiepools geven ze aan hoeveel leden gematerialiseerd zijn en of de momentopname is afgekapt) — je kunt ze negeren. Let op de conventie: de config van het metaobject gebruikt snake_case (gift_variant, min_qty), terwijl het gwp-object in de index camelCase gebruikt (giftVariant, minQty) — dezelfde gegevens op twee verschillende oppervlakken.

Let op: de kinderen met role:"option" van een collectiepool zijn een momentopname genomen op het moment van publicatie; het live lidmaatschap (en de prijs) wordt altijd door de Function bij het afrekenen opgelost.

22.5 combora.index en combora.manifest

shop.metafields.combora.index — de routeringstabel van gepubliceerde bundels (deze bestaat zodat je nooit hoeft te itereren over metaobjects.combora_bundle.values, wat Liquid stilzwijgend afkapt op 50):

{ "schema": 1, "revision_highwater": 128, "generated_at": "…",
  "bundles": [
    { "id": "f3062319-9d6e-…", "handle": "combora-bundle-f3062319-9d6e-…", "type": "fixed",
      "gid": "gid://shopify/Metaobject/…", "status": "active", "revision": 42 }
  ] }

De id is een tekst-identifier, geen getal. Alleen bundels die gepubliceerd zijn en binnen hun planningsvenster vallen, worden aangekondigd, zodat de index in de pas loopt met de prijs bij het afrekenen. Sommige items dragen extra velden: gwp (de cadeau-aanbieding, alleen bij cadeaubundels), gwps (de cadeau-aanbiedingen van een combo, in volgorde van sub-aanbieding) en test (true als de bundel in testmodus staat: de JS van de winkelvloer slaat hem over op het gepubliceerde thema).

shop.metafields.combora.manifest — de contractbeschrijving die een tool eenmalig leest: contract_version, schema_version, de bundelteller en de GID's van de drie definities. Het kan powered_by_badge: true bevatten, wat de Powered by Combora-badge in de blokken laat oplichten (alleen bij winkels met het Gratis-abonnement; elders wordt het veld weggelaten).

22.6 Het lezen ervan vanuit Liquid

{%- comment -%} Op een productpagina: de bundels voor DIT product {%- endcomment -%}
{%- for bundle in product.metafields.combora.bundles.value -%}
  <h3>{{ bundle.title.value | escape }}</h3>
  {%- if bundle.badge_label.value != blank -%}
    <span class="badge">{{ bundle.badge_label.value | escape }}</span>
  {%- endif -%}
  <ul>
    {%- for component in bundle.components.value -%}
      {%- comment -%} label is optioneel: ontbreekt het, dan valt het terug op de varianttitel en
          daarna op de producttitel. LET OP: als het product NIET gepubliceerd is naar het Online
          Store-kanaal, lost zijn verwijzing niet op in Liquid en geven ALLE fallbacks
          blank terug — beveilig de uiteindelijke naam, anders render je een leeg "1× ". {%- endcomment -%}
      {%- assign name = component.label.value -%}
      {%- if name == blank -%}{%- assign name = component.variant.value.title -%}{%- endif -%}
      {%- if name == blank or name == 'Default Title' -%}{%- assign name = component.variant.value.product.title -%}{%- endif -%}
      {%- if name != blank -%}
        <li>{{ component.quantity.value }}× {{ name | escape }}</li>
      {%- endif -%}
    {%- endfor -%}
  </ul>
{%- endfor -%}

{%- comment -%} Of via directe handle, in elk template {%- endcomment -%}
{%- assign bundle = metaobjects.combora_bundle['combora-bundle-{id}'] -%}

Beide routes zijn begrensde reads (de eigen lijst van het product, of een directe handle) — nooit de globale .values. Twee Liquid-valkuilen die je een middag besparen: (1) een for over een lijst van verwijzingen kapt stilzwijgend af op 50 — de bundels van Combora komen daar nooit aan (de grootste limiet is 50 items in totaal), maar itereer niet over andermans collecties in de veronderstelling dat je alles ziet; (2) de optionele velden (label, badge_label, cta_label) komen vaak leeg binnen — beveilig met != blank zoals hierboven.

22.7 Het lezen ervan vanuit de Storefront API (gelokaliseerd)

query BundleByHandle @inContext(language: FR) {
  metaobject(handle: { type: "combora_bundle", handle: "combora-bundle-{id}" }) {
    title:       field(key: "title")       { value }
    badge_label: field(key: "badge_label") { value }
    components:  field(key: "components") {
      references(first: 25) {
        nodes { ... on Metaobject {
          label:    field(key: "label")    { value }
          quantity: field(key: "quantity") { value }
        } }
      }
    }
  }
}

@inContext geeft de vertalingen terug die de app heeft gezaaid; alles wat niet vertaald is, valt automatisch terug op de basistaal.

22.8 Wat je ermee kunt bouwen

• Een volledig aangepaste bundel-UI in het thema, zonder de blokken van Combora, door titel, badge, onderdelen en besparing uit het metaobject te lezen.
• Een campagnelandingspagina: een pagina die de actieve bundels uit combora.index opsomt en elk ervan via zijn handle rendert.
• Headless / Hydrogen: dezelfde read via de Storefront API met lokalisatie per markt.
• Integraties (feeds, aanbevelingsapps): het manifest vermeldt de contractversie en waar alles zich bevindt.

22.9 Regels voor de ontwikkelaar

• De prijs behoort tot de Function. De velden van het metaobject zijn voor weergave: tel niet de discount_value van een combo op of herbereken prijzen in het thema — het afrekenproces is de autoriteit.
• Alleen additief: nieuwe velden kunnen verschijnen; bestaande veranderen niet. Schrijf reads die onbekende velden tolereren.
• Combo's: groepeer de kinderen op position gedeeld door 1000 (elke sub-aanbieding neemt een band van 1000 in beslag) of op config.of[].index — nooit op role, dat kan herhalen.
• Stijl: bouw je je eigen UI, negeer dan style en schrijf je eigen CSS. Wil je in plaats daarvan het ontwerp respecteren dat de handelaar in de app heeft gekozen, kopieer dan style.vars naar het style-attribuut van je root en style.mode_class als klasse; de preset Ongestyled van de studio bestaat voor precies het tegenovergestelde geval (schone markup, jouw CSS, met .combora-w en de variabelen --combora-* als haakjes).
• Privé ≠ contract: de metafields $app:runtime, $app:fnvars en $app:validation van de korting zijn intern aan de Functions, hebben geen toegang vanaf de winkelvloer, en hun vorm kan zonder kennisgeving veranderen. Bouw er niet op voort.
• Meerdere valuta's (Shopify Markets): elk bedrag in het contract — config.price, threshold, fixed_amount.amount, box_price — staat altijd in de valuta van de winkel, in kleinste munteenheden. Verkoopt je winkel in meerdere valuta's, reken dan om bij het weergeven (in Liquid, vermenigvuldig met cart.currency.rate; in JS, met Shopify.currency.rate) voordat je opmaakt: het ruwe getal renderen met de presentatievaluta van de koper toont een verkeerde prijs. De echte korting bij het afrekenen wordt door de app berekend en is altijd correct — deze regel gaat alleen over wat JOUW widget weergeeft.
• Schrijf niet in de naamruimte combora. Shopify geeft je er schrijftoegang toe (het is jouw winkel), maar de app regenereert het bij elke publicatie en een nachtelijke controle herstelt de velden die het abonnement bepalen. Alles van jou hoort in je eigen naamruimte.
• Deze bijlage is de volledige contractreferentie voor externe ontwikkelaars. Ontbreekt er iets dat je nodig hebt, schrijf ons dan via de chat van de app of naar support en we documenteren het.

23Bijlage voor ontwikkelaars: één widget per type, in Liquid

De vorige bijlage beschrijft wat het contract bevat; deze laat zien hoe je elk bundeltype ermee rendert. Alle code hieronder leest uitsluitend het publieke contract — geen app-API, geen van Combora's eigen blokken — dus je kunt haar in een snippet of een Custom Liquid-blok op het producttemplate plakken en de markup vrij aanpassen. Drie regels gelden voor alles op deze pagina:

• De prijs behoort tot de Function. Alles hier is weergave; het bedrag dat daadwerkelijk in rekening wordt gebracht, berekent Combora's Shopify Function bij het afrekenen. Herbereken nooit een totaal om het als de prijs te presenteren.
• Bedragen zijn kleinste munteenheden in de valuta van de winkel. Vermenigvuldig met cart.currency.rate voordat je opmaakt, anders ziet een klant die in een andere valuta winkelt een verkeerd getal.
• Optionele velden zijn vaak leeg. Beveilig met != blank — ook de onderdeelnaam na zijn fallbacks (zie 22.6).

23.1 Het skelet waar elk voorbeeld in past

Eén kaart per bundel van het huidige product, met titel, badge en de besparing zoals de bundel die uitdrukt (discount_value in basispunten of kleinste munteenheden). Elk type rendert vervolgens zijn eigen body binnen de case:

{%- liquid
  assign bundles = product.metafields.combora.bundles.value
  assign rate = cart.currency.rate | default: 1
-%}

{%- if bundles != blank -%}
  {%- for bundle in bundles -%}
    {%- liquid
      assign type = bundle.bundle_type.value
      assign dv = bundle.discount_value.value
      assign cfg = bundle.config.value
    -%}
    <article class="cx__card">
      <h3>{{ bundle.title.value | escape }}</h3>
      {%- if bundle.badge_label.value != blank -%}
        <span class="cx__badge">{{ bundle.badge_label.value | escape }}</span>
      {%- endif -%}

      {%- comment -%} De besparing, hoe deze bundel die ook uitdrukt {%- endcomment -%}
      {%- if dv.kind == 'percentage' -%}
        <p>Bespaar {{ dv.bps | divided_by: 100 }}%</p>
      {%- elsif dv.kind == 'fixed_amount' -%}
        <p>Bespaar {{ dv.amount | times: rate | money }}</p>
      {%- endif -%}

      {%- case type -%}
        {%- comment -%} één blok per type — hier komen paragrafen 23.2 tot 23.7 {%- endcomment -%}
      {%- endcase -%}
    </article>
  {%- endfor -%}
{%- endif -%}

23.2 Vaste bundel

Som de kinderen met role == 'component' op met de fallback-keten voor de naam, toon de bundelprijs wanneer de bundel de prijsmodus gebruikt (config.price, kleinste munteenheden), en link naar het koopbare hoofdproduct:

{%- when 'fixed' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'component' -%}
        {%- liquid
          assign name = c.label.value
          if name == blank
            assign name = c.variant.value.title
          endif
          if name == blank or name == 'Default Title'
            assign name = c.variant.value.product.title
          endif
        -%}
        {%- if name != blank -%}
          <li>{{ c.quantity.value }}× {{ name | escape }}</li>
        {%- endif -%}
      {%- endif -%}
    {%- endfor -%}
  </ul>
  {%- if cfg.price -%}
    <p class="cx__price">{{ cfg.price | times: rate | money }}</p>
  {%- endif -%}
  {%- if bundle.product.value != blank -%}
    <a href="{{ bundle.product.value.url }}">Koop deze bundel</a>
  {%- endif -%}

Een vaste bundel in prijsmodus draagt config.price en geen discount_value; in kortingsmodus is het andersom — de besparingsregel van het skelet dekt dat tweede geval al.

Bij een product met één variant is de varianttitel Shopify's plaatshouder «Default Title» — de terugvalketen slaat die over en gebruikt de producttitel (daar dient de extra voorwaarde voor).

23.3 Volumekorting

De ladder leeft in tiers (geordend op position), elke staffel met zijn eigen min_qty en discount_value:

{%- when 'volume' -%}
  <table>
    {%- for t in bundle.tiers.value -%}
      {%- assign tv = t.discount_value.value -%}
      <tr>
        <td>Koop {{ t.min_qty.value }}+</td>
        <td>
          {%- if tv.kind == 'percentage' -%}
            {{ tv.bps | divided_by: 100 }}% korting
          {%- else -%}
            {{ tv.amount | times: rate | money }} korting
          {%- endif -%}
        </td>
      </tr>
    {%- endfor -%}
  </table>

23.4 Koop X krijg Y

De regel bestaat uit twee scalars in config; een percentage van 100% (bps == 10000) betekent dat de beloningsartikelen gratis zijn:

{%- when 'bogo' -%}
  <p>Koop {{ cfg.buy_qty }}, krijg {{ cfg.get_qty }}
    {%- if dv.kind == 'percentage' and dv.bps == 10000 %} gratis{% else %} met korting{% endif -%}.</p>

23.5 Mix & match en stel je eigen box samen

Beide zijn "haal een aantal"-aanbiedingen: mix leest min_items van het metaobject, de box leest config.slots (en config.box_price wanneer de box een vaste totaalprijs rekent). De in aanmerking komende pool staat in config.eligible (zie 22.4):

{%- when 'mix_and_match' -%}
  <p>Kies {{ bundle.min_items.value }} of meer uit de selectie.</p>
{%- when 'build_a_box' -%}
  <p>Vul een box van {{ cfg.slots }}.
    {%- if cfg.box_price %} Boxprijs {{ cfg.box_price | times: rate | money }}.{% endif -%}</p>

23.6 Aanvullende producten (FBT)

De onderdelen dragen rollen: de anchor is het hoofdproduct, de suggestion-kinderen zijn de aanvullingen:

{%- when 'fbt' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'suggestion' or c.role.value == 'anchor' -%}
        <li>
          {{ c.variant.value.product.title | default: c.label.value | escape }}
          {%- if c.role.value == 'anchor' %} <em>(dit product)</em>{% endif -%}
        </li>
      {%- endif -%}
    {%- endfor -%}
  </ul>

23.7 Combo

Een combo nest sub-aanbiedingen. Groepeer zijn kinderen op position gedeeld door 1000 (elke sub-aanbieding neemt een band van 1000 in beslag) of loop config.of[] af — groepeer nooit op role, dat zich over sub-aanbiedingen herhaalt:

{%- when 'combo' -%}
  <ol>
    {%- for sub in cfg.of -%}
      <li>{{ sub.type | replace: '_', ' ' }}</li>
    {%- endfor -%}
  </ol>

23.8 Winkelbrede cadeau-aanbiedingen, op elke pagina

Cadeaus die op elke productpagina worden geadverteerd, leven op een shop-metafield, en thema-Liquid lost een lijst van metaobjects op winkelniveau niet op (22.1). Lees in plaats daarvan de JSON-index en los elke bundel op via zijn handle:

{%- assign index = shop.metafields.combora.index.value -%}
{%- if index != blank -%}
  {%- for entry in index.bundles -%}
    {%- if entry.all_pdp and entry.status == 'active' -%}
      {%- assign gift = metaobjects['combora_bundle'][entry.handle] -%}
      {%- if gift != blank -%}
        <aside class="cx__gift">
          <strong>{{ gift.title.value | escape }}</strong>
          {%- assign gcfg = gift.config.value -%}
          {%- if gcfg.threshold -%}
            <span>Besteed {{ gcfg.threshold | times: rate | money }} om het te ontgrendelen.</span>
          {%- endif -%}
        </aside>
      {%- endif -%}
    {%- endif -%}
  {%- endfor -%}
{%- endif -%}

23.9 Het complete snippet

Al het bovenstaande samengevoegd tot één werkend bestand — het skelet, de zes type-body's, de winkelbrede cadeaus en minimale CSS zodat het er direct leesbaar uitziet: download combora-custom-bundle.liquid. Sla het op als snippets/combora-custom-bundle.liquid in je thema en render het vanuit het producttemplate met {% render 'combora-custom-bundle', product: product %}. GWP zit met opzet niet in de case: een cadeau wordt geadverteerd (23.8 of de eigen blokken van de app) en automatisch door de app toegevoegd — er valt voor een productkaart-widget niets te verkopen.

24Geschiedenis van deze editie

Elke stroom in deze handleiding is getest in een echte winkel. Hier is het spoor van wanneer het is geverifieerd en wat daarna is veranderd, zodat je weet hoe actueel is wat je leest.

De screenshots staan in app/combora/public/manual/img/ in de repository: die van de app-interface onder img/<taal>/, één set per taal, en die van de winkelvloer en Shopify-admin in de hoofdmap, omdat die je thema en je admin volgen in plaats van de taal van de app. Ze worden opnieuw gemaakt vanuit de demowinkel; zie docs/manual/CAPTURAS.md voor welke status elk ervan nodig heeft.