Lunio Conversion API overview | Lunio Customer Help Center

To unlock conversion-related features and enhance the conversion data signals used in Lunio's IVT detection, we strongly recommend implementing Lunio's conversion tracking.

You can do this in three ways:

JavaScript snippet — Add Lunio's JavaScript snippet to your website (learn more here)
Conversion API — Send conversion events directly from your server to Lunio
Server-side Google Tag Manager (sGTM) — Use Lunio's sGTM custom template to send conversion events via a server-side GTM container (see the GTM setup guide below)

What is the Lunio Conversion API?

The Lunio Conversion API allows you to send conversion events directly from your server to Lunio, without relying on client-side JavaScript. You can find the full technical API documentation here, which your development team will need when implementing the API directly.

Why use the Conversion API?

Sending conversion events to Lunio provides a more complete picture of user interactions and lets us tailor our models to your data — giving you even better protection. The API offers specific benefits over the JavaScript approach:

Greater data control — Pass detailed conversion parameters securely without relying on client-side scripts
Improved reliability — Server-side events are less likely to be blocked by ad blockers or JavaScript blocking
Protect performance — Avoid extra JavaScript on checkout pages to keep them as light as possible
Send Lunio custom data — Use meta_data to pass order IDs, conversion values, and other custom parameters for more detailed analysis

API reference

Endpoint: POST https://conversions.lunio.ai/api/v1/tracking/conversion

Authentication: Bearer token in the Authorization header

Required headers

Header	Description
`Authorization`	`Bearer YOUR_TOKEN` — your Conversion API token from the Lunio dashboard
`Content-Type`	`application/json`
`X-Forwarded-For`	Your server's public IP address. If multiple IPs are present, the upstream server IP must be the first (left-most) entry. When using sGTM this header is set automatically.

Request body

Field	Required	Description
`config_id`	Yes	The ID of the conversion configuration created in the Lunio dashboard
`user_ip`	Yes	The IP address of the end user making the conversion
`url`	Yes	The URL of the page where the conversion took place
`user_agent`	Yes	The browser user-agent string of the user making the conversion
`meta_data`	No	Key-value pairs for extra info e.g. `{"order_id": "abc123"}`

Responses

Code	Description
`200`	`Conversion accepted`
`400`	`Invalid request` — e.g. `user_ip is required`

Getting started

You'll need to work with your development team to integrate the Conversion API. Here are the steps involved:

In your Lunio account, go to System Settings > Integrations > Conversions
Click Create conversion and configure your conversion event
Copy your API Token and Config ID from the dashboard
Implement server-side code to send conversion events — see the code examples below
Optionally pass meta_data parameters such as order ID or conversion value
Test and verify events are being received correctly

Code examples

cURL

curl --location 'https://conversions.lunio.ai/api/v1/tracking/conversion' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Forwarded-For: YOUR_SERVER_IP' \
  --data '{
    "config_id": "5ac69f20-5601-400f-8103-7272d5c1deb2",
    "user_ip": "1.1.1.1",
    "url": "http://example.com",
    "user_agent": "Mozilla/5.0",
    "meta_data": {"order_id": "abc123"}
  }'

Python

import requests

url = "https://conversions.lunio.ai/api/v1/tracking/conversion"
headers = {
  "Authorization": "Bearer YOUR_TOKEN",
  "Content-Type": "application/json",
  "X-Forwarded-For": "YOUR_SERVER_IP"
}

payload = {
  "config_id": "5ac69f20-5601-400f-8103-7272d5c1deb2",
  "user_ip": "1.1.1.1",
  "url": "http://example.com",
  "user_agent": "Mozilla/5.0",
  "meta_data": {"order_id": "abc123"}
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

JavaScript

fetch("https://conversions.lunio.ai/api/v1/tracking/conversion", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "X-Forwarded-For": "YOUR_SERVER_IP"
  },
  body: JSON.stringify({
    config_id: "5ac69f20-5601-400f-8103-7272d5c1deb2",
    user_ip: "1.1.1.1",
    url: "http://example.com",
    user_agent: "Mozilla/5.0",
    meta_data: { order_id: "abc123" }
  })
})
  .then(response => response.text())
  .then(console.log);

Setting up via Server-side Google Tag Manager (sGTM)

If you use server-side Google Tag Manager, Lunio provides a custom sGTM template that handles the API integration without writing any code.

👉 How to set up the Lunio Conversion API with server-side Google Tag Manager

Need help?

For assistance with the Conversion API or sGTM template, please don't hesitate to reach out to your account manager or email to [email protected].

How to install the Lunio conversion tracking script

What data does Lunio collect?

Lunio Conversion Tracking (GTM Setup Guide)

Setting up the Lunio Conversion API with Server-side Google Tag Manager