Conversietracking voor Lightspeed eCom-webshops

Conversietracking voor Lightspeed betekent dat je elke betaalde bestelling in je Lightspeed eCom-webshop rapporteert aan advertentieplatforms zoals Meta en TikTok, zodat ze de juiste advertenties kunnen toeschrijven en je campagnes kunnen optimaliseren. De betrouwbare manier is om elke aankoop op de server te versturen vanuit de bestelgegevens van Lightspeed, en een korte snippet aan de bedankpagina toe te voegen die de bestelling koppelt aan de advertentieklik.

Deze gids behandelt op welk Lightspeed-product het van toepassing is, hoe bestellingen ROASaurus bereiken, wat er uit elke bestelling wordt gelezen, hoe aankopen Meta en TikTok bereiken, de installatie, het testen en de beperkingen die je moet kennen.

Welk Lightspeed-product behandelt deze gids?

Lightspeed verkoopt meer dan één ecommerceproduct, dus controleer eerst het jouwe. ROASaurus koppelt met Lightspeed eCom (C-Series), het webshopplatform waarvan de back-office Settings › Website Settings › Web Extras heeft. De API draait op twee clusters:

Elk API-adres bevat ook een taalcode van twee letters, bijvoorbeeld /nl/ of /en/. ROASaurus vraagt ernaar als de taal van de webshop en gebruikt nl wanneer je het leeg laat.

Lightspeed biedt ook eCom (E-Series) aan. Lightspeed beschrijft de overstap naar E-Series als een upgrade naar een apart product, dat momenteel aan bepaalde Noord-Amerikaanse handelaren wordt aangeboden. De Lightspeed-connector van ROASaurus leest bestellingen alleen via de C-Series API, dus hij dekt E-Series-webshops niet.

Waarom ontbreken Lightspeed-aankopen in Meta en TikTok?

Een pixel in de browser rapporteert een aankoop alleen wanneer de browser van de shopper de bedankpagina laadt en het pixelscript draait. Dat mislukt in verschillende veelvoorkomende situaties:

• Een shopper betaalt via een redirect, bijvoorbeeld met iDEAL of PayPal, en sluit het tabblad voordat de bedankpagina laadt.
• Een adblocker of een privacyinstelling van de browser blokkeert het pixelscript.
• De bezoeker weigert marketingcookies, dus de pixel mag niet laden.
• De bestelling wordt later betaald, bijvoorbeeld via bankoverschrijving, wanneer er geen browser aan te pas komt.
• Safari beperkt hoe lang cookies die door scripts worden gezet blijven bestaan, dus de browser kan een oudere advertentieklik vergeten.

Hoe bereiken Lightspeed-bestellingen ROASaurus?

Wanneer je op Create webhook drukt, registreert ROASaurus in Lightspeed een webhook voor de groep orders en de actie updated, in JSON-formaat. Vanaf dan roept Lightspeed ROASaurus aan wanneer een bestelling verandert.

Waarom ROASaurus de bestelling opnieuw leest

Lightspeed voegt alleen een header x-signature toe aan een webhook als een app die heeft aangemaakt. Een webhook die met een gewone API-sleutel is aangemaakt, zoals hier, is niet ondertekend. Daarom bevat het webhook-adres een token dat uniek is voor je webshop, en vertrouwt ROASaurus de payload niet. Het leest de bestelling en de producten uit de Lightspeed-API en controleert zelf de betaalstatus.

De controle van 5 minuten

Elke 5 minuten vraagt ROASaurus Lightspeed ook om bestellingen die sinds de laatste controle zijn bijgewerkt, met 30 minuten overlap, en legt het de betaalde bestellingen vast die het nog niet heeft. Omdat deze controle de updatetijd gebruikt, wordt een bestelling die dagen na het plaatsen is betaald opgepikt, ook als de webhooklevering is mislukt. Bestellingen die ROASaurus al heeft, worden genegeerd, dus de webhook en de controle maken nooit twee aankopen aan.

Aan de kant van Lightspeed moet een webhook binnen 5 seconden een 2xx-antwoord krijgen. Mislukte leveringen worden opnieuw geprobeerd, tot in totaal 10 pogingen, en een webhook waarvan de foutenratio 50 uur lang boven 50% blijft, wordt uitgeschakeld. De controle van 5 minuten houdt bestellingen binnenkomen tijdens zo'n gat.

Wat leest ROASaurus uit een Lightspeed-bestelling?

De aankoopwaarde bevat btw

De priceIncl van Lightspeed is de bestelprijs inclusief belasting, en dat is de waarde die ROASaurus verstuurt. Je advertentieplatforms rapporteren dus omzet inclusief btw. Hier is het effect bij 21% btw:

Een break-even-ROAS gebruikt omzet zonder btw. Deel de ROAS van het platform door 1 plus je btw-tarief voordat je de twee vergelijkt.

Hoe wordt een Lightspeed-bestelling gekoppeld aan de advertentieklik?

Om een advertentie de bestelling toe te schrijven, heeft het platform de click-id's van de bezoeker die heeft besteld nodig: de Meta-click-id en browser-id (fbc, fbp), de TikTok-click-id (ttclid) en de TikTok-cookie (ttp). Het ROASaurus-script slaat ze voor elke bezoeker op wanneer die vanuit een advertentie binnenkomt. ROASaurus krijgt die bezoeker-id niet uit de Lightspeed-bestelling, dus het koppelt elke bestelling op een andere manier aan een bezoeker. Het probeert drie methoden, in deze volgorde:

De snippet geeft ook het bestelbedrag, de valuta en het e-mailadres van de klant door. ROASaurus slaat een hash van dat e-mailadres op bij de bezoeker, wat helpt om de volgende bestelling van dezelfde shopper te koppelen. ROASaurus wacht even voordat het elke aankoop verstuurt, zodat het bedankevent als eerste kan binnenkomen, en probeert de koppeling op het moment van verzenden opnieuw.

Lightspeed variables used by the ROASaurus snippet (Tracking box)

order.information.number      order id and event id order-<number>
order.information.price_incl  value
order.information.currency    currency
order.customer.email          email, hashed on the visitor

De pagina Orders toont in de kolom Matched by hoe elke bestelling is gekoppeld: thank_you, email, ip of not matched. Een bestelling die niet is gekoppeld, gaat nog steeds met zijn bestelgegevens naar je advertentieplatforms, maar zonder click-id's, en de attributie van ROASaurus toont hem als direct of onbekend.

Lightspeed-aankopen naar Meta en TikTok versturen

Elke betaalde bestelling wordt één serverevent per gekoppeld platform: een Purchase voor de Conversions API van Meta en een CompletePayment voor de Events API van TikTok, beide met de event-id order-ORD01042. TikTok toont CompletePayment in zijn rapporten nu als Purchase. Wanneer je de optie aanvinkt om ook de browserpixel te laden, laat de snippet op de bedankpagina dezelfde events in de browser afgaan met dezelfde event-id. Meta en TikTok houden dan één kopie.

Dezelfde bestellingen gaan naar Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn en de andere advertentieplatforms wanneer je die koppelt. Aankoopconversies voor Google Ads worden alleen vanuit de Shopify-checkout verstuurd, dus ROASaurus verstuurt ze niet vanuit Lightspeed. Voor de kant van Meta in de installatie, zie de gids over de Meta Conversions API.

Zo stel je conversietracking voor Lightspeed in

1. Voeg de webshop toe in ROASaurus

   Ga naar Add a store, kies Lightspeed eCom en voer het adres van je webshop in. Het tabblad Connection toont dan je scripttag en de snippet voor de bedankpagina.

2. Voeg het script toe aan elke pagina

   Ga in de back-office van Lightspeed naar Settings › Website Settings › Web Extras › Custom JavaScript en plak de scripttag. Lightspeed voert deze code uit op alle pagina's.

3. Voeg de snippet voor de bedankpagina toe

   Zet op dezelfde pagina, in het gedeelte Tracking, Status aan en plak de snippet. Lightspeed voert hem uit op de Thank You-pagina na een bestelling.

4. Maak een API-sleutel aan

   Ga naar Settings › Store Settings › Developers › New API key. Zet de sleutel aan, vink leestoegang tot bestellingen aan, sla op en selecteer Show om het secret te zien.

5. Koppel de API

   Voer op het tabblad Connection de sleutel, het secret, de regio en de taal van de webshop in. Sla op, druk op Test connection en daarna op Create webhook.

6. Koppel je advertentieplatforms

   Gebruik op Tracking & platforms Connect with Facebook of Add pixel voor Meta, en Add pixel voor TikTok met de pixelcode en een Events API-toegangstoken. Vink de optie aan om ook de browserpixel te laden.

API key          (Settings › Store Settings › Developers)
API secret       (select Show next to the key)
Region           eu  →  api.webshopapp.com
                 us  →  api.shoplightspeed.com
Shop language    nl, en, de ...  (the code in your API addresses)

Toestemming

Buiten Shopify leest het ROASaurus-script de keuze van de bezoeker uit gangbare toestemmingstools: Cookiebot, OneTrust, IAB TCF-banners en Google consent mode. Bij een andere cookiebanner roep je tlq('consent', true) aan wanneer de bezoeker marketingcookies accepteert en tlq('consent', false) wanneer die ze weigert. Totdat de bezoeker accepteert, heeft die geen bezoeker-id of click-id's en gaan er geen browserpixels af. De betaalde bestelling wordt nog steeds vanaf de server verstuurd, met gehashte klantgegevens uit de bestelling en het IP-adres en de browser van de bestelling. De helppagina over toestemming legt de details uit.

Hoe test je conversietracking voor Lightspeed?

• Open je webshop met ?roasaurus=connected in het adres. Een melding bevestigt dat het script draait. ?roasaurus=debug logt wat het naar de browserconsole stuurt.
• Onder Collected events in de Event log moeten paginaweergaven een bezoeker-id tonen.
• Plaats een bestelling en zorg dat de betaalstatus paid is. Onder Collected events zou de Event log dan een Purchase moeten tonen met je bestelnummer in de data. Ontbreekt die, controleer dan of Status aan staat in het gedeelte Tracking.
• Op het tabblad Connection toont Last order received de bestelling en Last sync de laatste controle van 5 minuten, met eventuele foutmeldingen van Lightspeed.
• Onder Server deliveries in de Event log krijgt elk gekoppeld platform een regel met de status sent en het antwoord van het platform.

Om het event in Meta te zien, plak je de code uit Events Manager › Test events in het veld Test event code van je Meta-pixel in ROASaurus en verwijder je die als je klaar bent. De pixelinstellingen van TikTok in ROASaurus hebben hetzelfde veld.

Beperkingen en randgevallen

• Alleen C-Series. Lightspeed eCom E-Series-webshops kunnen deze connector niet gebruiken.
• Alleen betaalde bestellingen. Een gedeeltelijk betaalde bestelling wordt verstuurd zodra de betaalstatus verandert in paid.
• Late betalingen en de limiet van 7 dagen van Meta. Meta accepteert serverevents tot 7 dagen na de eventtijd. ROASaurus gebruikt de aanmaaktijd van de bestelling, dus een bestelling die meer dan 7 dagen na plaatsing wordt betaald, wordt door Meta geweigerd.
• Browseraankopen vóór de betaling. De snippet op de bedankpagina draait wanneer de bestelling wordt geplaatst, dus de browserpixels rapporteren een bestelling per bankoverschrijving voordat die is betaald. Komt de betaling meer dan 48 uur later, dan kunnen Meta en TikTok de browser- en serverkopie niet samenvoegen.
• Annuleringen en terugbetalingen worden niet verstuurd. Zodra een aankoop is verstuurd, blijft hij in het advertentieplatform staan.
• Alleen paginaweergaven, zonder code. Productweergaven en toevoegingen aan de winkelwagen worden alleen op Shopify automatisch gedetecteerd. Op Lightspeed kan een ontwikkelaar ze versturen met een tlq-trackaanroep.
• API-limieten. Lightspeed staat 300 verzoeken per 5 minuten, 3,000 per uur en 12,000 per dag per API-sleutel toe. Als een andere tool dezelfde sleutel gebruikt, delen ze deze limieten. Lightspeed vraagt je contact met hen op te nemen voor een tweede sleutel.

De integratiepagina voor Lightspeed toont de gegevens van de koppeling op één plek, en de helppagina voor andere webshops vergelijkt Lightspeed met de andere platforms waarmee ROASaurus koppelt.

Bronnen

1. Lightspeed eCom (C-Series) Help Center: Adding a web tracking code
2. Lightspeed eCom (C-Series) Help Center: Creating API keys
3. Lightspeed eCom developers: Webhooks
4. Lightspeed eCom developers: Order
5. Lightspeed eCom developers: Rate limiting

In ROASaurus

• Lightspeed-integratie
• Help: Wix, Lightspeed en andere webshops
• Server-side tracking
• Meta-integratie

Lees verder