Matomo is an open-source web analytics platform that gives organizations full ownership of their visitor and behavioral data. It provides reporting on traffic, engagement, e-commerce activity, and campaign performance across a website. Matomo can be self-hosted or run through Matomo Cloud, allowing teams to choose the deployment model that best fits their privacy and infrastructure needs. Its server-side Tracking API accepts page, e-commerce, and campaign events directly, enabling measurement that does not depend on client-side scripts.
Product Type: Analytics
Integration Type: Starter Kit
Event Source Type: Web
Event Scope: Full-Funnel Events
- Sends page, e-commerce, and campaign events directly to Matomo via the Tracking API.
- Delivers events server-side using bulk HTTP POST, batching up to 500 events per request.
- Preserves visitor identity across events using a consistent visitor ID and customer user ID.
- Records events at their original event time so batching delays do not shift when a hit is logged.
- Supports self-hosted and Matomo Cloud deployments.
- A
TOKEN_AUTH value is required to override IP, datetime, and geo fields. cip (visitor IP) and city always require a valid token, and cdt requires one only when an event is older than 24 hours (backfill or replay).
- Without a valid token, Matomo counts every event that includes a token-gated field as invalid.
- If a valid token cannot be acquired, remove
cip and city from the playbook (and cdt if events can be older than 24 hours).
- E-commerce must be enabled for the website in Matomo. If it is not enabled, every e-commerce event (Cart Viewed, Checkout Started, Order Completed) is rejected as invalid. Pageviews are unaffected.
- Orders are de-duplicated by
ec_id. Re-sending the same order ID for a visitor is rejected as invalid to prevent double-counting. This is expected behavior, so each order needs a unique order_id.
- The
ec_items field is the only field that can cause a request to fail. It is sent as a structured array, so a malformed value produces invalid content and Matomo rejects that hit. All other outputs are flat values that Matomo safely ignores if unrecognized. Keep ec_items as a clean array of [sku, name, category, price, quantity] rows.
- Delivery success is judged by HTTP status only. A
200 response can still report rejected events in its body (for example {"tracked":0,"invalid":N}), and those individual rejections will not surface as errors.
- Bulk POST requests return an accurate count of invalid events in the response body, which can be reviewed to confirm processing.
- Self-hosted Matomo has no vendor-imposed rate limits. Matomo Cloud is volume-based and does not publish specific rate-limit details.
- This integration supports web events only.
- Product Added and Product Removed are not sent to Matomo. Matomo's cart tracking requires the full contents of the cart on every update, but these events carry only the single item that changed — so there is not enough data to send a valid cart update.
- An item SKU is required on each product in
ec_items. The kit falls back from sku to product_id. A product with neither produces a malformed item, so ensure every product carries an identifier.
- Checkout Started and Cart Viewed are treated as cart updates, so order-only detail (tax, shipping, discount, order ID) is not carried on them — only
ec_items and the cart total. Matomo keeps only the latest cart snapshot per visit.
- Geo override is city only.
region, country, latitude, and longitude are not mapped. IP-based geolocation via cip still applies.
- Site searches that return no results are not tracked.
- Ask Matomo representatives, or retrieve from your Matomo instance, the following credentials:
DOMAIN_URL: The base URL of your Matomo instance. The integration appends /matomo.php to this value to form the tracking endpoint.TOKEN_AUTH: The API authentication token. Required to override IP, datetime, and geo fields.SITE_ID: The numeric ID of the website being tracked.
- From the integration library, add a Matomo integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
DOMAIN_URL | Base URL of your Matomo instance. The tracking endpoint is formed by appending /matomo.php. |
TOKEN_AUTH | Optional, sensitive API token used to authorize IP, datetime, and geo overrides. |
SITE_ID | Numeric ID of the Matomo website being tracked. |
- MetaRouter provides all of the event mappings that Matomo integrations typically require. You may add custom events, parameters, or mappings in accordance with Matomo's API documentation.
- In the Pipelines tab, add your Matomo integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|
rec Required | String: Required Matomo tracking flag, always set to '1'. | Enrichment – '1' |
apiv | String: Matomo Tracking API version, set to '1'. | Enrichment – '1' |
idsite Required | String: Matomo site ID for the destination website. | Enrichment – $$SITE_ID$$ |
url | String: URL of the page where the event occurred. | context.page.url |
urlref | String: Referring page URL. | context.page.referrer |
ua | String: Browser or device user agent. | context.userAgent |
uid | String: Customer user ID used to preserve identity across events. | userId |
cip | String: Visitor IP address. Requires a valid TOKEN_AUTH. | context.ip |
city | String: Visitor city for geo override. Requires a valid TOKEN_AUTH. | traits.address.city |
lang | String: Visitor locale or language. | context.locale |
rand | String: Unique value used to prevent request caching. | messageId |
_id | String: Matomo visitor ID (16-char hex) derived from the anonymous ID. | Expression – first 16 chars of anonymousId with dashes removed |
cdt | String: Original event timestamp so batching delay does not skew recording time. Token-gated when event is older than 24h. | Expression – seconds since epoch from event timestamp |
| Output Key | Description | Expected Input |
|---|
action_name | String: Page title used as the Matomo action name. | context.page.title |
| Output Key | Description | Expected Input |
|---|
search | String: Search query entered by the visitor. | properties.query |
| Output Key | Description | Expected Input |
|---|
_pkc | String: Product category viewed. | properties.category |
| Output Key | Description | Expected Input |
|---|
_pks | String: Product SKU or product ID of the viewed item. | Expression – properties.sku or properties.product_id |
_pkn | String: Product name of the viewed item. | properties.name |
_pkc | String: Product category of the viewed item. | properties.category |
_pkp | Float: Product price of the viewed item. | properties.price |
| Output Key | Description | Expected Input |
|---|
idgoal Required | String: Ecommerce goal identifier for cart updates, set to '0'. | Enrichment – '0' |
ec_items | Array: Cart items as [sku, name, category, price, quantity] rows. | Expression – maps properties.products to item rows |
revenue | Float: Total cart value across all products. | Expression – totals properties.products |
| Output Key | Description | Expected Input |
|---|
idgoal Required | String: Ecommerce goal identifier for cart updates, set to '0'. | Enrichment – '0' |
revenue | Float: Order revenue value. | properties.revenue |
ec_items | Array: Cart items as [sku, name, category, price, quantity] rows. | Expression – maps properties.products to item rows |
| Output Key | Description | Expected Input |
|---|
idgoal Required | String: Ecommerce goal identifier for orders, set to '0'. | Enrichment – '0' |
ec_id Required | String: Unique order ID used for de-duplication. | properties.order_id |
revenue | Float: Total order value. | properties.total |
ec_st | Float: Order subtotal. | properties.revenue |
ec_tx | Float: Tax amount applied to the order. | properties.tax |
ec_sh | Float: Shipping charge amount. | properties.shipping |
ec_dt | Float: Discount amount applied to the order. | properties.discount |
ec_items | Array: Purchased items as [sku, name, category, price, quantity] rows. | Expression – maps properties.products to item rows |
| Output Key | Description | Expected Input |
|---|
c_n | String: Campaign or promotion name. | properties.name |
c_p | String: Campaign or promotion creative. | properties.creative |
| Output Key | Description | Expected Input |
|---|
c_i | String: Campaign interaction type, set to 'click'. | Enrichment – 'click' |
c_n | String: Campaign or promotion name. | properties.name |
c_p | String: Campaign or promotion creative. | properties.creative |
These identifiers must be mapped to Matomo in order for successful user matching to occur. Without these IDs, any events sent to Matomo may not be accurately reflected in reporting.
| Attribute | Example | Sync Injector Required? |
|---|
_id Required | a1b2c3d4e5f6a7b8 | No |
uid Recommended | user_12345 | No |
- Confirm delivery by reviewing the bulk POST response body, not just the HTTP status. A
200 response can still report rejected events (for example {"tracked":0,"invalid":N}), and those rejections will not surface as errors in the pipeline.
- If events are counted as invalid, verify that a valid
TOKEN_AUTH is set whenever token-gated fields (cip, city, or a backfilled cdt) are included. A missing, wrong, or placeholder token invalidates every event that carries one of those fields.
- For ecommerce events, confirm Ecommerce is enabled for the website in Matomo under Administration → Websites → Manage → Ecommerce ("Yes, an Ecommerce shop"). If it is not enabled, Cart Viewed, Checkout Started, and Order Completed are rejected as invalid while pageviews continue to track.
- Verify tracked activity in the Matomo UI. Page and event data appear under Visitors → Visits Log, and ecommerce activity appears under the Ecommerce reports, typically within a few minutes of delivery.
- When re-testing orders, use a unique
order_id each time. Matomo de-duplicates orders by ec_id, so re-sending the same order ID for a visitor is rejected as invalid by design.
- Ask your Matomo representative to confirm that events are being received and reflected correctly in the Matomo UI.
