The Insights API lets you pull the same aggregated app metrics you see in Tapcart Insights into your own reports, spreadsheets, or data warehouse. You call Tapcart, and Tapcart returns totals for a date range you choose, such as sessions, revenue, installs, or push campaign performance.

This is a pull API. It requires a merchant API key from Tapcart Support. It is not the same as clickstream webhooks, which push individual shopper events to an endpoint you configure.

In this article:

What the Insights API is (and is not)
How to request your API key
How to make a request
Metrics you can query
Things to know

What the Insights API is

Use the Insights API when you want historical, aggregated reporting, the same kind of numbers shown on Insights charts. Common uses include daily app stats in an internal dashboard, push campaign performance in a spreadsheet, or scheduled pulls into a BI tool.

This is different from other Tapcart data options:

Insights in the dashboard: view the same metrics in Tapcart, including CSV export on most charts. No API key required.
Clickstream webhooks: Tapcart sends live shopper events (product views, add to cart, purchases, and more) to an HTTPS URL you set in Settings. No API key. Webhooks do not return historical totals. See Connecting Clickstream Webhooks.
Analytics integrations (Firebase, Klaviyo, and others): send events into those platforms. Use those when you want data in that tool.

Because you are calling Tapcart for data, Tapcart authenticates every request with your merchant API key.

How to request your API key

A merchant API key is required. It is not available as a self-serve setting in the dashboard yet. Beyond issuing the key, there is no extra Tapcart setup for the Insights API.

To request a key:

Email [email protected] or reach out through LiveChat in your Tapcart dashboard.
Ask for a merchant API key for the Insights API, and include your store name.
Confirm the email address where we should send the key. We send it through a secure link, not in the body of a normal email.

This is your merchant API key. If you also need your Tapcart app ID, ask for that in the same request. You will use both on every API call.

Treat the API key as a secret. Do not share it in public tickets, Slack, or email threads. If you think a key was exposed, contact Tapcart Support so it can be revoked and replaced.

How to make a request

Send a POST request to:

https://api.tapcart.com/insights-pro/v2/metrics

Headers

api-key: your merchant API key
app-id: your Tapcart app ID

Body (JSON)

metricType: which metric to return (see the list below)
appId: your Tapcart app ID (same value as the app-id header)
startTimestamp: start of the date range, inclusive (ISO 8601, for example 2024-01-01T00:00:00Z)
endTimestamp: end of the date range, exclusive
timezone: IANA timezone used to bucket times (for example America/New_York or America/Los_Angeles)
granularity: hour, day, week, or month. Required for time-series metrics. Ignored for metrics that return a single summary.

Example

Daily sessions for January 2024:

metricType: overview_sessions_by_time
appId: your Tapcart app ID
startTimestamp: 2024-01-01T00:00:00Z
endTimestamp: 2024-02-01T00:00:00Z
timezone: America/New_York
granularity: day

What you get back

Every successful response uses the same envelope: the metric you asked for, your app ID, a count of rows, and a records array. The shape of each record depends on metricType. Currency fields may also appear in extras.

Authentication or validation errors typically return a 4xx status. Server errors typically return a 5xx status and may be retried.

Metrics you can query

These metric types match the reporting you see in Insights. Time-series metrics need a granularity value.

Push Explorer

metricType	What it returns	Needs granularity
`push_explorer_individual`	Performance for each one-off push (sends, sessions, carts, purchases, revenue)	No
`push_explorer_automated`	Performance by automated push type (welcome, abandon cart, and similar)	No
`push_explorer_by_time`	Push metrics combined, by time bucket	Yes

Overview

metricType	What it returns	Needs granularity
`overview_sessions_by_time`	Sessions by OS, new vs returning, and source (direct, push, deeplink)	Yes
`overview_sessions_heatmap`	Sessions by day of week and hour of day	No
`overview_revenue_by_time`	App revenue by time bucket	Yes

Revenue

metricType	What it returns	Needs granularity
`revenue_by_time`	Revenue and order counts by time bucket	Yes
`revenue_source_of_orders`	Orders split by direct, push, and inbox attribution	No
`revenue_promo_vs_revenue`	Discounted vs non-discounted revenue by time bucket	Yes
`revenue_aov_by_os`	Revenue and orders by iOS vs Android (AOV = revenue / orders)	No

Acquisition

metricType	What it returns	Needs granularity
`acquisition_daily_active_users`	Daily active devices by OS	Yes
`acquisition_source_of_opens`	Sessions split by direct, push, and deeplink	No
`acquisition_open_rate`	Daily unique openers vs installed base	Yes
`acquisition_app_installs`	Installs by time bucket and OS	Yes
`acquisition_signed_up_users`	New account creations by time bucket	Yes
`acquisition_time_to_first_purchase`	Average time from first session to first purchase	Yes

Retention

metricType	What it returns	Needs granularity
`retention_repurchase_rate`	Customers with one purchase vs two or more, over time	Yes
`retention_session_length`	Average session duration by OS	Yes
`retention_sessions_per_user`	Average sessions per active user by OS	No
`retention_customer_lifetime_value`	Daily customer lifetime value snapshots	No (always daily)
`retention_dormancy_rate`	Active vs dormant device counts	Yes
`retention_order_frequency`	Average orders per customer (guest checkouts excluded)	Yes

Customer Journey

metricType	What it returns	Needs granularity
`customer_journey_conversion_funnel`	Sessions to product view to add to cart to purchase	No
`customer_journey_top_viewed_products`	Top 10 most viewed products	No
`customer_journey_top_wishlisted_products`	Top 10 most net-wishlisted products	No
`customer_journey_top_purchased_products`	Top 10 most purchased products by items sold	No

For field-by-field response schemas, see the Insights API reference.

Things to know

The API key is required. Every request must include api-key and app-id.
Keep the key private. We send it through a secure link. If it is compromised, ask Support to revoke it.
endTimestamp is exclusive. To include all of January, use a start of January 1 and an end of February 1.
This is not a live event stream. You get rolled-up metrics for a date range, not individual shopper actions. For realtime events, use Clickstream Webhooks.
Historical data is included. Unlike webhooks, the Insights API can return metrics for dates before you started using the API, for as long as those metrics exist in Insights.
One-off exports do not need the API. Most Insights charts have a CSV export for the selected date range.

Using the Insights API