- Lightspeed conversion tracking works best when each paid order is sent from Lightspeed's order data on the server, with a thank-you page snippet that links the order to the ad click.
- ROASaurus connects to Lightspeed eCom (C-Series) through its API on the EU and US clusters; E-Series is a separate product and is not covered.
- One click on Create webhook registers an orders webhook in Lightspeed, and ROASaurus also checks for updated orders every 5 minutes, so late payments are picked up.
- Only orders with the payment status paid are sent, valued at the order price including tax.
- Lightspeed orders include the shopper's IP address and browser, so ROASaurus can still match some orders when the thank-you snippet did not run.
Lightspeed conversion tracking means reporting every paid order in your Lightspeed eCom webshop to ad platforms such as Meta and TikTok, so they can credit the right ads and optimize your campaigns. The reliable way is to send each purchase from Lightspeed's order data on the server, and to add a short snippet to the thank-you page that links the order to the ad click.
This guide covers which Lightspeed product it applies to, how orders reach ROASaurus, what is read from each order, how purchases reach Meta and TikTok, the setup, testing, and the limits you should know.
Which Lightspeed product does this guide cover?
Lightspeed sells more than one ecommerce product, so check yours first. ROASaurus connects to Lightspeed eCom (C-Series), the webshop platform whose back office has Settings › Website Settings › Web Extras. Its API runs on two clusters:
| Cluster | API address | Region in ROASaurus |
|---|---|---|
| EU1 | api.webshopapp.com | eu |
| US1 | api.shoplightspeed.com | us |
Each API address also contains a two-letter language code, for example /nl/ or /en/. ROASaurus asks for it as the shop language and uses nl when you leave it empty.
Lightspeed also offers eCom (E-Series). Lightspeed describes moving to E-Series as an upgrade to a separate product, currently offered to certain North American merchants. The ROASaurus Lightspeed connector reads orders through the C-Series API only, so it does not cover E-Series stores.
Why do Lightspeed purchases go missing in Meta and TikTok?
A pixel in the browser reports a purchase only when the shopper's browser loads the thank-you page and the pixel script runs. That fails in several common situations:
- A shopper pays by redirect, for example with iDEAL or PayPal, and closes the tab before the thank-you page loads.
- An ad blocker or a browser privacy setting blocks the pixel script.
- The visitor declines marketing cookies, so the pixel must not load.
- The order is paid later, for example by bank transfer, when no browser is involved.
- Safari limits how long cookies set by scripts last, so the browser can forget an older ad click.
- Needs the thank-you page to load
- Blocked by ad blockers and some browsers
- Nothing happens when a bank transfer is paid later
- Value and order number only if the page is reached
- Every order with payment status paid
- Sent from server to server, not from the browser
- Late payments arrive with the next order update
- Value, products and customer details from the order
How do Lightspeed orders reach ROASaurus?
When you press Create webhook, ROASaurus registers a webhook in Lightspeed for the group orders and the action updated, in JSON format. From then on, Lightspeed calls ROASaurus when an order changes.
Why ROASaurus reads the order again
Lightspeed adds an x-signature header to a webhook only when an app created it. A webhook created with a plain API key, as here, is unsigned. So the webhook address contains a token unique to your store, and ROASaurus does not trust the payload. It reads the order and its products from the Lightspeed API and checks the payment status itself.
The 5-minute check
Every 5 minutes, ROASaurus also asks Lightspeed for orders updated since its last check, with 30 minutes of overlap, and records the paid orders it does not have yet. Because this check uses the update time, an order paid days after it was placed is picked up even if its webhook delivery failed. Orders ROASaurus already has are ignored, so the webhook and the check never create two purchases.
On Lightspeed's side, a webhook must get a 2xx answer within 5 seconds. Failed deliveries are retried, up to 10 attempts in total, and a webhook whose error ratio stays above 50% for 50 hours is disabled. The 5-minute check keeps orders coming during such a gap.
What does ROASaurus read from a Lightspeed order?
| Lightspeed field | What ROASaurus does with it |
|---|---|
number | The order id, for example ORD01042. It becomes the event id order-ORD01042, because the thank-you page shows the same number. |
paymentStatus | Only paid orders are sent. Not paid, partially paid and cancelled orders are skipped. |
priceIncl | The purchase value, including tax. The currency is the store currency you set in ROASaurus. |
createdAt | The event time |
| Email, phone or mobile, first and last name | Hashed with SHA-256 and sent as customer data |
| Billing city, zip code and country | Hashed and sent as customer data |
remoteIp, userAgent | Sent with the event and used for IP matching |
| Customer id | Hashed and sent as an external id |
| Order products | Variant id (or product id), quantity, price including tax, title and SKU |
The purchase value includes VAT
Lightspeed's priceIncl is the order price including tax, and that is the value ROASaurus sends. Your ad platforms therefore report revenue with VAT included. Here is the effect at 21% VAT:
| Example: 30 orders | Value sent (incl. VAT) | Revenue excl. VAT |
|---|---|---|
| Ad spend | $1,000 | $1,000 |
| Purchase value | $3,630 | 3,630 ÷ 1.21 = $3,000 |
| ROAS | 3.63 | 3.00 |
A break-even ROAS uses revenue without VAT. Divide the platform ROAS by 1 plus your VAT rate before you compare the two.
How is a Lightspeed order linked to the ad click?
To credit an ad, the platform needs the click identifiers of the visitor who ordered: the Meta click id and browser id (fbc, fbp), the TikTok click id (ttclid) and the TikTok cookie (ttp). The ROASaurus script stores them for each visitor when they land from an ad. ROASaurus does not get that visitor id from the Lightspeed order, so it links each order to a visitor in another way. It tries three methods, in this order:
| Method | How it works | What it needs |
|---|---|---|
| 1. Thank-you snippet | The snippet fires a ROASaurus purchase with the order number. ROASaurus finds that event by its event id, order-ORD01042. | The snippet in the Tracking box |
| 2. Earlier email | A hashed email the visitor gave earlier on your site, in a popup form or through an Identify call | A signup form or Identify call |
| 3. IP address and browser | The same IP address and browser seen from 3 hours before to 15 minutes after the order, only when exactly one visitor fits | Nothing extra |
The snippet also passes the order total, currency and customer email. ROASaurus saves a hash of that email on the visitor, which helps to match the same shopper's next order. ROASaurus waits briefly before it sends each purchase, so the thank-you event can arrive first, and it tries the matching again at send time.
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
The Orders page shows how each order was linked, in the Matched by column: thank_you, email, ip or not matched. An order that is not matched still goes to your ad platforms with its order data, but without click identifiers, and ROASaurus attribution shows it as direct or unknown.
Sending Lightspeed purchases to Meta and TikTok
Each paid order becomes one server event per connected platform: a Purchase for Meta's Conversions API and a CompletePayment for TikTok's Events API, both with the event id order-ORD01042. TikTok now shows CompletePayment as Purchase in its reports. When you tick the option to also load the browser pixel, the thank-you snippet fires the same events in the browser with the same event id. Meta and TikTok then keep one copy.
- Event id, event time, value and currency
- Product ids, quantities and prices
- Hashed email, phone, name, city, zip code and country
- IP address and browser
- fbc and fbp when the order is matched
- Event id, event time, value and currency
- Products with id, name, quantity and price
- Hashed email and phone
- IP address and browser
- ttclid and ttp when the order is matched
The same orders go to Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn and the other ad platforms when you connect them. Google Ads purchase conversions are sent from the Shopify checkout only, so ROASaurus does not send them from Lightspeed. For Meta's side of the setup, see the Meta Conversions API guide.
How to set up Lightspeed conversion tracking
- Add the store in ROASaurus
Go to Add a store, pick Lightspeed eCom and enter your shop address. The Connection tab then shows your script tag and the thank-you snippet.
- Add the script to every page
In the Lightspeed back office, go to Settings › Website Settings › Web Extras › Custom JavaScript and paste the script tag. Lightspeed runs this code on all pages.
- Add the thank-you snippet
On the same page, in the Tracking area, turn Status on and paste the snippet. Lightspeed runs it on the Thank You page after an order.
- Create an API key
Go to Settings › Store Settings › Developers › New API key. Switch the key on, tick read access to orders, save, and select Show to see the secret.
- Connect the API
On the Connection tab, enter the key, the secret, the region and the shop language. Save, press Test connection, then Create webhook.
- Connect your ad platforms
On Tracking & platforms, use Connect with Facebook or Add pixel for Meta, and Add pixel for TikTok with the pixel code and an Events API access token. Tick the option to also load the browser pixel.
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)Consent
Outside Shopify, the ROASaurus script reads the visitor's choice from common consent tools: Cookiebot, OneTrust, IAB TCF banners and Google consent mode. With another cookie banner, call tlq('consent', true) when the visitor accepts marketing cookies and tlq('consent', false) when they decline. Until the visitor accepts, they have no visitor id or click ids, and no browser pixels fire. The paid order is still sent from the server with hashed customer data from the order and the order's IP address and browser. The consent help page explains the details.
How do you test Lightspeed conversion tracking?
- Open your shop with
?roasaurus=connectedin the address. An alert confirms that the script runs.?roasaurus=debuglogs what it sends to the browser console. - In the Event log, under Collected events, page views should show a visitor id.
- Place an order and make sure its payment status is paid. Under Collected events, the Event log should then show a Purchase with your order number in its data. If it is missing, check that Status is on in the Tracking area.
- On the Connection tab, Last order received shows the order and Last sync shows the last 5-minute check, with any error from Lightspeed.
- Under Server deliveries in the Event log, each connected platform gets a line with the status sent and the platform's response.
PageView visitor 7d1e04b2Script on every pagePurchase order-ORD01042Thank-you snippet, browser pixels firedwebhook orders updatedOrder ORD01042, payment status paidMeta Purchase sentMatched by thank_youTikTok CompletePayment sentSame event id, deduplicatedTo see the event in Meta, paste the code from Events Manager › Test events into the Test event code field of your Meta pixel in ROASaurus, and remove it when you are done. TikTok's pixel settings in ROASaurus have the same field.
Limits and edge cases
- C-Series only. Lightspeed eCom E-Series stores cannot use this connector.
- Paid orders only. A partially paid order is sent when its payment status changes to paid.
- Late payments and Meta's 7-day limit. Meta accepts server events up to 7 days after the event time. ROASaurus uses the order's creation time, so an order paid more than 7 days after it was placed is rejected by Meta.
- Browser purchases before payment. The thank-you snippet runs when the order is placed, so the browser pixels report a bank transfer order before it is paid. If the payment comes more than 48 hours later, Meta and TikTok cannot merge the browser and server copies.
- Cancellations and refunds are not sent. Once a purchase is sent, it stays in the ad platform.
- Page views only, without code. Product views and adds to cart are detected automatically on Shopify only. On Lightspeed, a developer can send them with a
tlqtrack call. - API limits. Lightspeed allows 300 requests per 5 minutes, 3,000 per hour and 12,000 per day per API key. If another tool uses the same key, they share these limits. Lightspeed asks you to contact them for a second key.
The Lightspeed integration page lists the connection facts in one place, and the help page for other webshops compares Lightspeed with the other platforms ROASaurus connects to.
Sources
- Lightspeed eCom (C-Series) Help Center: Adding a web tracking code
- Lightspeed eCom (C-Series) Help Center: Creating API keys
- Lightspeed eCom developers: Webhooks
- Lightspeed eCom developers: Order
- Lightspeed eCom developers: Rate limiting