Conversions API

Overview

Conversions API sends the conversions Matomo already records (goals and ecommerce orders) server-side to Google Ads, Meta, LinkedIn, X and Microsoft Advertising. You need no ad pixels on your website, and ad blockers or browser restrictions no longer distort your campaign figures.

How it works

Per website you set up one or more destinations and define which Matomo goals are sent as which conversion. Matomo records the conversion as usual; a background job sends it within a minute with the recommended cron job, for Google with an adjustable delay.

• Google Ads: Data Manager API, authentication via service account, clicks via gclid, gbraid and wbraid, processing status in the send log.
• Meta: Conversions API with event names such as Purchase or Lead, fbclid and the Meta cookies _fbp/_fbc.
• LinkedIn: Conversions API with conversion rules, clicks via li_fat_id.
• X (Twitter): web conversions of the X Ads API, sign-in with a pixel token or OAuth, clicks via twclid.
• Microsoft Advertising (Bing): UET Conversions API with the UET tag's token, clicks via msclkid. The plugin also reads Microsoft UET Consent Mode.

Consent first

Only what the visitor consented to is sent, per platform. Your consent banner passes the decision via Matomo Tag Manager, Google Consent Mode or the JavaScript API. If the visitor answers only after the conversion, for example for a goal reached on page view, the conversion waits up to 24 hours for the decision; a withdrawal stops everything not sent yet. Optionally your website passes customer data such as the email address; Matomo normalises and hashes it per platform, and plain text is never stored.

Full control

The send log shows every transfer with its status, the platforms' error messages and "Retry". Authentication errors pause a destination automatically, and super users are notified. Matomo's raw data deletion and GDPR tools cover the plugin's data. You find the plugin under Administration → Websites → Conversions API and in the reports under Goals → Conversions API, also in Matomo's dark mode.

Use cases

• No pixels, no gaps: Matomo already records the conversion. Conversions API sends it straight to the ad platforms, so ad blockers and browser restrictions no longer swallow anything, and you need no extra tags on your website.
• Clicks attributed automatically: The plugin detects ad clicks from Google (gclid, gbraid, wbraid), Meta (fbclid), LinkedIn (li_fat_id), X (twclid) and Microsoft (msclkid) and attributes later conversions, even after a login and across visits within your lookback window.
• Consent per platform: Only what the visitor consented to is sent. The signal comes from your consent banner via Matomo Tag Manager, Google Consent Mode or the JavaScript API. Per website you choose the mode "Strict" or "External". If the visitor answers only after the conversion, it waits up to 24 hours for the decision.
• Lean on data: Customer data is normalised and hashed in Matomo; plain text is never stored. IP address, user agent and hashes are deleted after sending, at the latest after 7 days, click IDs after 90 days.
• Every transfer traceable: The send log shows what went to which platform and when, with the platforms' error messages, "Retry" and, for Google, the processing status. Expired access is detected and reported.

Setup step by step

How to install the plugin is described under Installing plugins. The Conversions API needs a self-hosted Matomo 5 with PHP 8.1 or newer, also on the command line. You set it up per website under Administration → Websites → Conversions API or in the reports under Goals → Conversions API. Both are available to administrators of the website.

1. Add the cron job

A background job sends the conversions. Run it every minute, otherwise Matomo sends only once per hour. The plugin page shows the exact line under Setup:

* * * * * php /path/to/matomo/console feinwerkconversionsapi:dispatch > /dev/null 2>&1

If several PHP versions are installed, use the full path of the PHP 8 binary. If the job has not run for more than 15 minutes, the plugin page shows a notice.

2. Add a destination

Choose Google Ads, Meta (Facebook/Instagram), LinkedIn, X (Twitter) or Microsoft Advertising (Bing) and enter the access. Credentials are stored encrypted.

• Meta: Events Manager → data source → Settings → Conversions API → Generate access token, plus the dataset (pixel) ID. The target is an event name such as Purchase or Lead.
• Google Ads: In a Google Cloud project, enable the Data Manager API, create a service account with a JSON key and add its email address as a user in Google Ads, plus the customer ID of the account with the conversion action. The target is the ID of a conversion action of type Import from clicks.
• LinkedIn: Campaign Manager → Signals Manager → Direct API → create an access token, plus the ad account ID. The target is the ID of a conversion rule of type Conversions API.
• X (Twitter): Look up the pixel ID in X Events Manager. Sign in with the pixel token from Events Manager or with the four OAuth keys of an app from the X Developer Portal; if both are filled in, the pixel token is used. The target is the event ID of the conversion event, such as tw-abc12-def34.
• Microsoft Advertising: Open the UET tag, choose Use Conversions API and create the token, plus the UET tag ID. The target is the event name that matches the conversion goal in Microsoft Advertising, such as purchase or lead.

Under Goals to send you assign Matomo goals and the ecommerce order to a target of the platform and choose the value: revenue of the conversion, a fixed value or none. Test connection checks the access.

3. Connect your website

Matomo records the conversion itself as usual. Your website additionally passes the visitor's consent and, on the order confirmation page, the customer data, most easily through Matomo Tag Manager:

var _mtm = window._mtm = window._mtm || [];
_mtm.push({event: 'fwcapi_consent',
  fwcapi_consent: {google: consent.google, meta: consent.meta, linkedin: consent.linkedin,
    x: consent.x, microsoft: consent.microsoft}});

consent stands for the visitor's actual decision from your consent banner, never true for everyone. On the order confirmation page, before Matomo tracks the order:

_mtm.push({event: 'purchase', ecommerce: {transaction_id: 'A-4711'},
  user_data: {email: 'jane@example.org', phone_number: '+4915112345678'}});

If your website uses Google Tag Manager or Google Consent Mode, the plugin reads those entries as well, and Microsoft UET Consent Mode (uetq.push('consent', …)) as the decision for Microsoft. Without a tag manager there is the JavaScript API (_paq.push(['FeinwerkConversionsApi::setConsent', consent])), for server-side tracking the parameters fwcapi_consent, fwcapi_ud and fwcapi_eid. The plugin page shows the right code under Setup.

4. Check the first data

The Send log shows per period what was captured, scheduled, sent or skipped, and below every conversion with its status, attempts and the platform's error message. Retry sends a failed conversion again. For Google, the table of requests also shows the processing status at Google.

Examples

Report conversions to Meta despite ad blockers

Add a Meta destination and assign the ecommerce order to Purchase with its revenue. If the Meta pixel keeps running, choose the order ID under Deduplication with an existing pixel: Meta then counts every order once, even if both pixel and plugin report it.

Report leads to LinkedIn

Assign the goal Contact request to a LinkedIn conversion rule and enter a fixed value, for example the average value of a lead. LinkedIn attributes the conversion to the campaign through the click ID li_fat_id, even if the request comes on a later visit.

Google Ads with orders and newsletter sign-ups

Add a Google destination with two conversion actions. Google recommends a send delay of about six hours so that fresh clicks are known to Google; the plugin presets it for Google. Until they are sent, the conversions are shown as Scheduled in the send log.

Good to know

• Consent: In the default mode Strict, only what the visitor consented to is sent, per platform. Choose the mode External per website if your website ensures consent itself (Administration → Websites → Manage).
• Late consent: If the visitor answers the banner only after the conversion, for example for a goal reached on page view, the conversion waits up to 24 hours for the decision. The plugin passes a later decision to Matomo by itself; it also applies to conversions from earlier visits and to goals tracked server-side. A withdrawal stops everything not sent yet. A denial that only comes from Google Consent Mode's defaults is not a decision yet. Can be switched off per website with Wait for late consent.
• Privacy: Customer data is normalised and hashed in Matomo; plain text is never stored. Full IP address, user agent and hashes are deleted after sending, at the latest after 7 days, click IDs after 90 days. While a conversion waits for consent, IP address and user agent are kept encrypted for up to 24 hours, only for platforms with a destination on the website. Matomo's raw data deletion and GDPR tools cover the plugin's data.
• User ID and cookieless tracking: An ad click from an anonymous visit also counts for a conversion after login, as long as the same browser with the same Matomo cookie is used. Without a visitor cookie, Matomo recognises a visitor only within the same day.
• Troubleshooting: After an authentication error a destination pauses for at least an hour; after five in a row it is deactivated. If Matomo's salt changes, enter the credentials again. The plugin page shows the license status, checked via the Feinwerk Marketplace Connector; the plugin keeps working without a valid license. More help: support@feinwerk.io.

Technical reference

Property	Value
Technical name	FeinwerkConversionsApi
Current version	0.4.0
Matomo	≥ 5.0.0, < 6.0.0
PHP	≥ 8.1.0
License	paid
Database changes	none in the current version

FAQ

Which platforms are supported?

Google Ads via the Data Manager API, Meta (Facebook and Instagram) via the Conversions API, LinkedIn via the Conversions API, X (Twitter) via the web conversions of the X Ads API and Microsoft Advertising (Bing) via the UET Conversions API. You can set up as many destinations per website as you like.

Do I need Google Tag Manager?

No. You pass consent, customer data and order ID via Matomo Tag Manager (_mtm) or Matomo's JavaScript API. If your website uses Google Tag Manager or Google Consent Mode, the plugin reads those entries as well.

Can I keep the pixel running in parallel?

Yes. When running both, the platforms deduplicate via a shared event ID: either the order ID or an ID your website passes to the pixel and to Matomo.

How fast do conversions arrive?

With the recommended cron job the plugin checks every minute what to send. For Google a delay of about 6 hours is preset, so that fresh clicks are already known to Google.

What happens without consent?

In the default mode "Strict" nothing is sent to a platform without consent. If the visitor answers the consent banner only after the conversion, the conversion waits up to 24 hours for the decision; without consent it is dropped and its data deleted. If the website owner ensures consent elsewhere, they can choose the mode "External" per website.

Which Matomo version do I need?

Matomo 5 with PHP 8.1 or newer, also for the command line that runs the cron job. The plugin supports Matomo's dark mode.

Where do I find the Conversions API in Matomo?

Administrators of a website find it under Administration → Websites → Conversions API and in the reports under Goals → Conversions API. There you set up destinations, check the send log and find the code for your website.