Meta Pixel Conversions API Addon for Google Analytics 4 PRO User Guide

Meta Pixel Conversions API Addon for Google Analytics 4 PRO

Requires the Google Analytics 4 PRO extension.

Next level analytics: Meta Pixel Conversions API.

What is Meta's Conversions API?

Meta's Conversions API is designed to act as a system of bridges between an advertiser's marketing data (such as website & app events, business messaging or even offline conversions) and Meta. This includes data from a server, a website, mobile app or CRM.

Conversions API, when used to its full potential, eliminates the need for maintaining multiple connection points for each data source. Instead, advertisers can leverage Meta's Conversions API to simplify their tech stack by sending multiple event types. With our integration, advertisers can establish a direct connection between their server and Meta's Conversions API endpoint.

What are the advantages of using Meta's Conversions API?

Optimize Ad Targeting - Efficiently utilize a broader, more accurate data set to properly target ads to your user base.
Decrease Cost per Result - Streamline your tracking data to maximize the efficiency of your ads, as well as increase conversion rate & revenue.
Effectively Measure Outcomes - Ensure you're taking the proper decisions to drive growth and streamline workflows.
Gain access to more accurate tracking - Bypass traditional client-side tracking limitations with a server-side implementation.

How does it work?

Here's a handy diagram to show you how the Meta Pixel and Meta Pixel Conversions API work:

Features of the Addon.

Server-side Purchase Event Tracking.
Server-side Add Payment Info Event Tracking.
Server-side Initiate Checkout Event Tracking.
Server-side Add To Cart Event Tracking.
Server-side Add To Wishlist Event Tracking.
Server-side Search Event Tracking.
Server-side View Content Event Tracking.
Server-side View Category Event Tracking.
Meta Pixel Conversions API Test Mode integration.
Ability to track selected events in conjunction with the frontend Meta Pixel.
Directly and fully integrated into the Google Analytics 4 PRO extension.
Log functionality for in-depth debugging of events sent to the Meta API.
Easy setup, all that's required is the Meta Pixel ID and the Meta Pixel Conversions API Key.
Option to track only specific customer groups
Ability to send data to multiple Meta Ads properties

Requirements for using the Meta Pixel Conversions API Addon.

To use the Meta Pixel Conversions API Addon, you'll need the following:

A Meta Pixel client-side integration, in order to gain access to your Meta Pixel Tracking Base Code. Our Google Analytics 4 PRO extension comes with the possibility of setting up the client-side Meta Pixel out of the box, which can be done within minutes.
The Google Analytics 4 PRO extension enabled and configured.

HOW TO INSTALL

This extension is installed via Composer, which is the official and only supported installation method.

Step 1: Prerequisites

Ensure your Magento version is compatible (2.3.0 - 2.4.8 and all Security Patches)
Install on a testing/development environment first
Set Magento to developer mode before installation
Make sure you have Composer installed on your server

php bin/magento deploy:mode:set developer

Step 2: Access Composer Configuration

Head into the Downloadable Products section of your weltpixel.com account. This is where you'll be able to see your Composer Configuration Commands.

You'll need to have Composer installation enabled for your account. If you don't see the Composer Configuration Commands, please contact our support team.

Step 3: Configure Repository

Run the generated commands from your account. Example commands:

composer config repositories.weltpixel composer https://weltpixel.repo.packagist.com/your-id/

composer config --global --auth http-basic.weltpixel.repo.packagist.com token your-token

These commands will provide you access to the WeltPixel repository. Replace 'your-id' and 'your-token' with the actual values from your account.

Step 4: Install via Composer

Run the following command in your Magento root directory:

composer require weltpixel/module-ga4-metass

Step 5: Enable and Setup

Run the following commands:

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f

Step 6: Cache Management

Flush any caches:

php bin/magento cache:flush

Step 7: Production Mode

If your store was in production mode, switch it back:

php bin/magento deploy:mode:set production

Wooohooo! The extension is now installed on your Magento store! Congrats!

How to Upgrade the Extension

Step 1: Run: composer update (for the package)
Step 2: Run setup commands: php bin/magento setup:upgrade, php bin/magento setup:di:compile, php bin/magento setup:static-content:deploy -f
Step 3: Flush cache: php bin/magento cache:flush

How to configure the Meta Pixel Conversions API Addon.

Enable Meta Pixel Server Side Tracking - When enabled, the server-side Meta Pixel functionality will use the Meta Pixel Javascript Tracking code configured in the client-side configuration section.
Meta Pixel ID - Your Meta Pixel's unique ID. This ID can be found in your Meta Events Manager account under Data Sources → Settings → Dataset ID. You can also find it in your Meta Pixel Javascript Tracking code in client-side configuration section, as the id parameter in the facebook.com link.
Conversions API Access Key - The Conversions API Access Key (token) can be generated in the Meta Pixel settings. You can follow Meta's documentation for instructions on how to manually generate a token.
Track Events - Select the Events that you want to track via the Meta Pixel Conversions API: Purchase / Add Payment Info / Initiate Checkout / Add To Cart / Add To Wishlists / Search / View Content / View Category

Send enabled events via the frontend Meta Pixel as well - Set this option to Yes if you want to send events via the frontend Meta Pixel as well. Meta Events Manager should have built-in functionality to avoid data duplication, and this may (in some cases) enrich your data.
Enable Test Mode - This functionality can be used to send test events to the Meta Pixel. Find your Test Code in the Test Events section of the Meta Pixel configuration and paste it below. Any event sent will then be marked as a test event and will show up instantly in the Test Events section. Remember to disable this option when you're finished testing.
Test Event Code - This code may change periodically, so make sure you double-check it in the Meta Pixel Test Events section after disabling and re-enabling Test Mode.
Enable File Log - Enable the creation of a log file that shows the pushed event data. The meta-api.log file can be found in the var/log directory of Magento 2 root.
Track Only Specific Customer Groups - If set to Yes, only selected customer groups will be tracked by Meta Pixel server-side events.
Send eCommerce Event Data to multiple Meta Ads properties - If set to Yes, you'll be able to add additional Meta property IDs to which you want to send eCommerce event data to. You'll need the Meta Pixel ID and Conversions API Access Key of each additional property you want to add. Note: Adding a new property here will only send the enabled eCommerce events in the Meta Pixel Server Side Tracking configuration. If you need to also send Page View events, in order to stitch data and ensure attribution, you'll also need to add additional Meta Pixel Tracking codes in the Meta Pixel Tracking Javascript Code section above.

Change Log.

What's new in v.1.16.0 - January 7, 2026

Giving back: As a celebration of over 10 years of activity within the Magento 2 ecosystem, and as a way to give back to the community, a number of WeltPixel extensions (both FREE and paid) have officially gone fully Open Source via public Github repositories. Find the full list on Github.
New Feature: Introduced composer as the official and singular installation method for all WeltPixel products. Previously, this was only available for the PRO version of the Google Analytics 4 extension, as well as the Marketing Suite Pro.
Fixed a bug that would sometimes cause events to be processed multiple times due to an unhandled response code (100) from the Meta API. Events will now only be processed once upon successful API response.

What’s new in v.1.15.11 - November 25, 2025

New Feature: Augumented the addon's server-side logging functionality with a Magento Admin interface, allowing merchants to explore payloads and event logs without having to access the server.

What’s new in v.1.15.9 - October 28, 2025

Magento Compatibility: Introduced compatibility with the latest released Magento 2 Security Patches - Magento 2.4.8-p3, Magento 2.4.7-p8, Magento 2.4.6-p13, Magento 2.4.5-p15 & Magento 2.4.4-p16.
New Feature: Enhanced client and server-side purchases with additional data about the user (email, phone number) to significantly increase Event Match Quality.
New Feature: Added an interactive form that can be submitted via the Magento Admin to provide an efficient method of submitting feedback/feature requests.
Added adjustments to pricing parameter calculation to Begin Checkout and Add Payment Info events to ensure a higher degree of data accuracy.

What’s new in v.1.15.7 - September 2, 2025

New Feature: Optimized the addon's event logging functionality to increase clarity and improve the process of searching/filtering through logged events. All data logged for a specific event is now included on the same line. Before this release, every logged piece of information would take up a separate line, even if related to the same eCommerce event.
New Feature: The addon now features the capability of sending data to multiple Meta Ads properties via newly added Magento Admin settings. This allows you to send event data from the same Magento 2 instance to any number of Meta Ads properties. This feature is also included in the Google Analytics 4 PRO extension and other API addons.
Magento Compatibility: Introduced compatibility with the latest released Magento 2 Security Patches - Magento 2.4.8-p2, Magento 2.4.7-p7, Magento 2.4.6-p12, Magento 2.4.5-p14 & Magento 2.4.4-p15.
Fixed an issue that would, in very specific cases, prevent the addon from sending purchase events via cron. This would happen when, for any reason, the ID of the product on the order that was supposed to be sent no longer existed (deleted product, for example).
Added adjustments to ensure the correct content_type value is sent for Configurable Products. Previously, the value "product" was sent for Configurable Products, whereas Meta requires "product_group".

What’s new in v.1.15.3 - June 20, 2025

New Feature: Added options to allow for filtering of events based on Customer Groups. The extension now pulls all Customer Groups and allows merchants to select for which of those they'd like event data to be sent.
Magento Compatibility: Introduced compatibility with the latest Magento 2.4.8-p1, 2.4.7-p6, 2.4.6-p11 & 2.4.5-p13 Security Patches releases. Upgrade ASAP to keep your store secure.
Made various code optimizations related to Grand Total and Subtotal calculations in order to increase module customizability.

What’s new in v.1.15.0 - April 22, 2025

Magento Compatibility: Introduced compatibility with the new Magento 2.4.8 release, as well as the accompanying 2.4.7-p5, 2.4.6-p10, 2.4.5-p12 and 2.4.4-p13 Security Patches.
PHP Compatibility: Introduced compatibilty with PHP 8.4, which is now officially compatible with the latest Magento 2.4.8 version.

What's new in v.1.14.19 - April 8, 2025

Fixed an issue that caused the incorrect user IP address to be sent when utilizing CDNs such as Cloudflare. Previously, the extension would always send the IP assigned by the CDN.
Fixed an issue that sometimes prevented the extension's Order Exclusion by Status functionality from properly working when sending orders via cron.
Added a default User Agent the extension uses when orders are sent via cron.
Fixed an incorrect namespace used throughout the extension files.

What's new in v.1.14.13 - February 17, 2025

New Feature: The addon now benefits from the Google Analytics 4 PRO extension's Measurement Protocol Log functionality, which generates a log file in the var/log directory that includes information about each triggered event. The functionality can be enabled in the addon's Magento Admin configuration section.
Removed deprecated Magento 2.2.x code version from extension package.

v.1.10.1 - November 14, 2024

Initial extension release. This product is an addon and requires a version equal to or higher than 1.14.9 of the Google Analytics 4 PRO extension to be used.