Skip to main content

Lomadee Global Pixel

The Lomadee Global Pixel is a complete tracking solution that offers advanced functionality for conversion tracking, events, and real-time user data collection.

When to Use Global Pixel

Use Global Pixel when:
  • You need automatic event tracking (clicks, pageviews)
  • You want to send detailed customer and product data
  • Your platform supports advanced JavaScript
  • You need features like custom metadata
Use PNG Pixel when:
  • You want a simpler implementation
  • Your platform has JavaScript limitations
  • You only need basic conversion tracking

How It Works

The Global Pixel is an asynchronous script that automatically:
  1. Captures parameters from URLs coming from Lomadee shortened links
  2. Tracks events like page views and clicks
  3. Processes conversions when you call the sendOrder() method
  4. Sends data asynchronously to Lomadee servers

Installation

Step 1: Initialize the Pixel

Add this code to your site’s <head>, before the closing </head> tag:
window.lomadeePixel is always a Promise in this installation model. It can be used before or after the external script finishes loading. The initialized instance is also available as window.lomadeePixelInstance after the Promise resolves.
Do not use window.load or DOMContentLoaded to determine whether the pixel is ready. These events describe the page lifecycle, not the asynchronous loading state of pixel.js.

Step 2: Google Tag Manager Implementation (Optional)

If you use GTM:
  1. Create a new Custom HTML tag.
  2. Paste the initialization code from Step 1.
  3. Set the trigger to Initialization – All Pages.
  4. Configure the tag to fire once per page.
  5. Publish the container version.
Existing installations that assign an instance directly to window.lomadeePixel remain supported and do not need to be migrated. The Promise-based contract documented here applies to new installations.

Sending Conversions

When to Send

Call the sendOrder() method only on the purchase confirmation page, after payment is approved. Important: Do not send on checkout or cart pages.

Basic Implementation

On your success/confirmation page, add the conversion code:

Multiple Products Example

Data Structure

string
required
Unique identifier for the order
object
object
required
array
required
Array containing main order values
number
required
Total order value in cents. This is the sum of all subItems values (Items + Shipping + Discounts + other fees)
object
Additional order data

SubItems

The subItems object stores order information such as shipping, items, discounts, and other values not directly related to products. Important notes:
  • The total value of Items must reflect the final price of each product after applying discounts
  • Discounts applied directly to products should be reflected in each item’s price
  • General order discounts (such as coupons or payment method discounts) should be included in subItems using the Discounts key
  • Any other type of discount, such as fees, cashback, etc., should be included in subItems using a key with the discount name and value
Usage example:

Important Notes About Discounts

  1. Product-Specific Discounts: These should be reflected in each product’s price field. For example, if a product has a 10% discount, the price should be 90% of the listPrice.
  2. General Discounts: Discounts applied at checkout (such as coupons or payment method discounts) should be included in subItems with the key “Discount”. This discount should also be applied to the final product value. For example, if a 5% discount is applied for using a specific payment method, it should be applied to the final price of each product in the order.
  3. Commissioning: Lomadee’s commissioning algorithm considers the final value of each product (price), not the total order value after general discounts, for commission calculation. Therefore, it’s crucial that product-specific discounts are correctly reflected in each item’s price. For example, if a 5% discount is applied for using a specific payment method, it should be applied to each item’s price.

Metadata

The metadata field is an array that allows sending custom information for specific contexts. It can be used at different levels of the order structure:
  1. Order level (order.metadata)
  2. Customer level (customer.metadata)
  3. Product level (items[].metadata)
  4. Category level (items[].categories[].metadata)
Each item in the metadata array must follow the key and value structure:

Usage Examples

  1. At order level:
  1. At customer level:
  1. At product level:
  1. At category level:

Important Notes

  • Keys must be strings and are case-sensitive
  • Values can be strings, numbers, or booleans
  • metadata is optional at all levels
  • Use this field to send additional information that may be useful for specific analyses or integrations

Google Tag Manager Implementation

If you’re using GTM, you can implement the conversion tracking using GTM variables and triggers:

Step 1: Create GTM Variables

First, create these variables in GTM: Built-in Variables:
  • Enable “Enhanced Ecommerce” variables
  • Enable “Page URL” and “Page Path”
Custom Variables:

Step 2: Create Conversion Tag

Create a new Custom HTML tag with this code:

Step 3: Configure Trigger

Create a trigger that fires on purchase confirmation: Trigger Type: Custom Event Conditions:
  • Custom Event equals your confirmed purchase event, such as purchase
  • Fire the tag once per order

Step 4: DataLayer Configuration

For better integration, configure your dataLayer on the confirmation page:

Step 5: Advanced GTM Variables

Create these custom JavaScript variables for more complex scenarios: Variable Name: Lomadee Items Array
Variable Name: Lomadee SubItems Array

Step 6: Testing in GTM

Use GTM Preview mode to test:
  1. Enable Preview Mode in GTM
  2. Navigate to confirmation page with test purchase
  3. Check Console for success/error messages
  4. Verify in Network tab that Lomadee requests are sent
  5. Check GTM Debug panel for variable values

GTM Best Practices

Variable Fallbacks: Always provide fallback values for GTM variables to prevent errors when data is missing.
Data Format: Ensure prices are converted from dollars to cents (multiply by 100) before sending to Lomadee.
Testing: Use GTM’s preview mode extensively to test all scenarios before publishing.

Validation and Testing

How to Verify It’s Working

  1. Open DevTools (F12) on the page where you implemented the pixel
  2. Go to Console tab and check for errors
  3. Go to Network tab and look for:
    • Script loading: pixel.js
    • Requests to Lomadee domains after calling sendOrder()

Implementation Checklist

Basic Installation:
  • Script included in page <head>
  • Pixel initialized correctly
  • No errors in browser console
Conversion Implementation:
  • sendOrder() called ONLY on confirmation page
  • orderId is unique for each order
  • Prices are in cents (e.g., 9990 for $99.90)
  • All required fields are filled
Product Data:
  • price represents final value after discounts
  • listPrice is original price without discount
  • quantity is an integer
  • Categories are filled correctly
SubItems:
  • “Items” contains sum of all final products
  • “Shipping” contains shipping value
  • “Discounts” contains general discounts (negative value)
  • “value” contains total order value (sum of all subItems)

Development Environment Testing

Error Handling

Robust Implementation

Troubleshooting

Common Issues

Symptoms:
  • “lomadeePixel is not defined” error in console
  • Script doesn’t appear in Network tab
Solutions:
  1. Check if script is in page <head>
  2. Check if ad blockers are active
  3. Check if CDN is accessible
  4. Try loading script without async temporarily
Symptoms:
  • sendOrder() doesn’t generate Network requests
  • No success logs in console
Solutions:
  1. Check if calling sendOrder() on correct page
  2. Check if all required fields are filled
  3. Check if prices are in cents
  4. Check if there are no JavaScript errors on page
Symptoms:
  • Commissions not being calculated correctly
  • Products don’t appear in reports
Solutions:
  1. Check if price has final value after discounts
  2. Check if subItems.Items is sum of all products
  3. Check if not sending same orderId multiple times
  4. Check if categories are in correct format

Advanced Debug

Important Considerations

Don’t Duplicate Conversions: Make sure to call sendOrder() only ONCE per order. Implement checks to avoid multiple sends of the same orderId.
Price Format: All monetary values must be in cents. $99.90 = 9990 cents.
Performance: The pixel is asynchronous and doesn’t block page loading. Conversion is sent in background.

Platform Integration

WordPress/WooCommerce

Shopify

Support

For questions or issues:
  1. Technical documentation: Check this complete documentation
  2. Technical support: Lomadee Help Center
  3. Direct contact: Contact our technical team

Useful Information for Support

When contacting support, have on hand:
  • URL of page where pixel is implemented
  • Example of data being sent in sendOrder()
  • Screenshots of console errors (if any)
  • Browser and version being used