Matomo is an open-source web analytics platform that helps businesses measure visits, page views, and conversion activity across their websites. It provides detailed reporting on visitor behavior, acquisition channels, and ecommerce performance while giving organizations full ownership of their data. Its Tracking HTTP API allows server-side events to be sent directly to a Matomo instance for measurement and attribution.
Product Type: Analytics
Integration Type: Starter Kit
Event Source Type: Web
Event Scope: Full-Funnel Events
- Sends server-side page, product, and e-commerce events directly to Matomo via the Tracking HTTP API.
- Delivers events in bulk POST batches of up to 500 events per request.
- Preserves visitor identity across events using a consistent visitor ID and user ID.
- Records the original event timestamp so batching delays do not affect when a hit is registered.
- Supports e-commerce measurement including cart and order lifecycle events.
- A visitor ID (
_id) is derived from anonymousId as a 16-character hexadecimal string, and uid carries the customer's userId. Identity is preserved across events through consistent _id and uid values.
- The
cdt field sends the original event timestamp so batching delays and retries do not skew when a hit is recorded.
token_auth is required for IP, datetime, and geo overrides. cip (visitor IP) and city are always authentication-gated, and cdt is gated only when the event is older than 24 hours (backfill or replay).- Without a valid token, Matomo counts every event that includes an authentication-gated field as invalid. If a valid token cannot be acquired, remove
cip and city (and cdt if events can be older than 24 hours) from the playbook.
- E-commerce must be enabled for the website in Matomo (Administration → Websites → Ecommerce: "Yes, an Ecommerce shop"). If it is not enabled, every e-commerce hit (Cart Viewed, Checkout Started, Order Completed) is rejected as invalid. Page views 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, and each order needs a unique order_id.
- 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 products carry an identifier.
- Checkout Started and Cart Viewed are cart updates, so order-only details (tax, shipping, discount, order ID) are 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, though IP-based geolocation via
cip still applies.
- A
200 response with {"tracked":0,"invalid":N} is still treated as delivered by the pipeline, so individual rejected hits do not surface as errors.
- Self-hosted Matomo instances have no rate limits.
- No-result site searches are not tracked.
- Product Added and Product Removed events lack the full-cart data that Matomo's cart update requires, so they are not sent as e-commerce cart updates.
- Ask vendor representatives for the following credentials:
DOMAIN_URL: The base URL of your Matomo instance (self-hosted domain or Matomo Cloud domain).TOKEN_AUTH: A 32-character authorization key from a Matomo user with write or admin permission on the target website. Required for IP, datetime, and geo overrides.
- 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 as DOMAIN_URL/matomo.php. |
TOKEN_AUTH | Optional 32-character token authenticating requests that use IP, datetime, or geo overrides. |
- 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: Enables tracking request processing. Must be set to 1. | Enrichment – '1' |
apiv | String: Tracking API version, currently always 1. | Enrichment – '1' |
idsite Required | String: The ID of the website being tracked. | $$SITE_ID$$ |
url | String: Full URL for the current action. | context.page.url |
urlref | String: Full HTTP referrer URL. | context.page.referrer |
ua | String: Override value for the user-agent header. | context.userAgent |
uid | String: User ID identifying the logged-in user. | userId |
cip | String: Override value for the visitor IP. Requires token_auth. | context.ip |
city | String: Override value for the visitor's city. Requires token_auth. | traits.address.city |
lang | String: Override value for the Accept-Language header. | context.locale |
rand | String: Random value to prevent request caching. | messageId |
_id | String: 16-character hexadecimal visitor ID. | Expression – first 16 chars of anonymousId with dashes removed |
cdt | String: Override datetime of the request (event timestamp, UTC). Requires token_auth when older than 24h. | Expression – converts event timestamp to epoch seconds |
| Output Key | Description | Expected Input |
|---|
action_name | String: Title of the page action being tracked. | context.page.title |
| Output Key | Description | Expected Input |
|---|
search | String: Site search keyword. Tracks the request as a site search. | properties.query |
| Output Key | Description | Expected Input |
|---|
_pkc | String: Category of the product list being viewed. | properties.category |
| Output Key | Description | Expected Input |
|---|
_pks | String: SKU of the product being viewed. | Expression – properties.sku or properties.product_id |
_pkn | String: Name of the product being viewed. | properties.name |
_pkc | String: Category of the product being viewed. | properties.category |
_pkp | Float: Price of the product being viewed. | properties.price |
| Output Key | Description | Expected Input |
|---|
idgoal Required | String: Set to 0 to track an ecommerce cart update. | Enrichment – '0' |
ec_items | Array: Cart items as [sku, name, category, price, quantity] rows. | Expression – maps properties.products |
revenue | Float: Total value of items in the cart. | Expression – totals properties.products |
| Output Key | Description | Expected Input |
|---|
idgoal Required | String: Set to 0 to track an ecommerce cart update. | 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 |
| Output Key | Description | Expected Input |
|---|
idgoal Required | String: Set to 0 to track an ecommerce order. | Enrichment – '0' |
ec_id Required | String: Unique ecommerce order identifier used for de-duplication. | properties.order_id |
revenue Required | Float: Grand total for the ecommerce order. | properties.total |
ec_st | Float: Order subtotal, excluding shipping. | properties.revenue |
ec_tx | Float: Tax amount of the order. | properties.tax |
ec_sh | Float: Shipping cost of the order. | properties.shipping |
ec_dt | Float: Discount offered on the order. | properties.discount |
ec_items | Array: Order items as [sku, name, category, price, quantity] rows. | Expression – maps properties.products |
| Output Key | Description | Expected Input |
|---|
c_n | String: Name of the content or promotion. | properties.name |
c_p | String: Content piece, such as the creative. | properties.creative |
| Output Key | Description | Expected Input |
|---|
c_i | String: Name of the content interaction. | Enrichment – 'click' |
c_n | String: Name of the content or promotion. | properties.name |
c_p | String: Content piece, such as the 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? |
|---|
idsite Required | my-site-id | No |
_id Recommended | af344a398df83874 | No |
uid Recommended | user_12345 | No |
ec_id Required | order_98765 | No |
Success is judged by HTTP status only. A 200 response with {"tracked":0,"invalid":N} is still treated as delivered by the pipeline, so individual rejected hits do not surface as errors. Because of this, confirm data is landing in Matomo rather than relying on the pipeline status alone.
To verify tracking in the Matomo UI:
- Open Visitors → Real-time to watch visits, page views, and actions arrive as they are sent. This report shows recent activity and refreshes automatically, making it the fastest way to confirm events are being received.
- Open Visitors → Visits Log to inspect individual visits and their actions, and confirm event and page detail appears as expected. Visitor IP and Visitor ID are shown only when you are logged in.
- For ecommerce events, check the Ecommerce reports (such as Ecommerce Log and Ecommerce Orders) to confirm carts and orders are recorded. Ensure Ecommerce is enabled for the website first (Administration → Websites → Ecommerce), or ecommerce hits will be rejected.
- Note that aggregated reports for periods including today are processed on a delay, so use the Real-time and Visits Log reports for immediate confirmation.
If events are not appearing as expected, coordinate with your Matomo representative to confirm data is being received and processed on their end, including reviewing invalid hit counts returned in tracking responses.
