Metrics API

Endpoint

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

Returns aggregated analytics data for a given Tapcart app. The specific data returned depends on the metricType provided in the request body.

Authentication

Provide the following headers alongside the request body:

Header	Description
`api-key`	A static key with authorized access for your organization
`app-id`	Your organization's Tapcart id. It's good practice to include this alongside all requests.

If you do not have access to your merchant api key, please reach out to support for assistance.

Request Body

All fields are required unless noted. Fields are validated at the server and unknown fields are stripped from the request.

Field	Type	Description
`metricType`	`string` (enum)	The metric to query. See Metric Types below for all valid values.
`appId`	`string`	The Tapcart app ID. Must match the `app-id` header when using session-based auth.
`startTimestamp`	`string`	Start of the date range (inclusive). ISO 8601 timestamp recommended (e.g. `"2024-01-01T00:00:00Z"`).
`endTimestamp`	`string`	End of the date range (exclusive). ISO 8601 timestamp recommended.
`timezone`	`string`	IANA timezone string used to localize time bucketing (e.g. `"America/Los_Angeles"`).
`granularity`	`"hour" \| "day" \| "week" \| "month"`	Time bucket size for time-series metrics. Required for metrics that return a time series; ignored otherwise.

Example request:

{
  "metricType": "overview_sessions_by_time",
  "appId": "abc123",
  "startTimestamp": "2024-01-01T00:00:00Z",
  "endTimestamp": "2024-02-01T00:00:00Z",
  "timezone": "America/New_York",
  "granularity": "day"
}

Response Envelope

All successful responses share the same top-level shape:

{
  "metricType": "<requested metricType>",
  "appId": "<requested appId>",
  "extras": {
    "currencyCode": "USD",
    "currencyFormat": "${{amount}}"
  },
  "count": 31,
  "records": [ ... ]
}

Field	Type	Description
`metricType`	`string`	Echoed from the request.
`appId`	`string`	Echoed from the request.
`extras.currencyCode`	`string?`	Your store currency code (e.g. `"USD"`). May be absent if not configured.
`extras.currencyFormat`	`string?`	Your money format string (e.g. `"${{amount}}"`). May be absent if not configured.
`count`	`number`	Number of records in the `records` array.
`records`	`object[]`	Array of metric records. Shape varies by `metricType`. See below.

Error response: Validation or input related errors typically return a 400. Internal errors typically return a 500 status

Metric Types

Push Explorer

`push_explorer_individual`

Aggregate performance metrics per individually sent push notification over the requested date range. One record per notificationId. Covers both push and inbox channel attribution.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`notificationId`	`string`	Unique identifier for the notification.
`sentAt`	`string`	ISO timestamp when the notification was sent.
`pushType`	`string`	e.g. `"individual"`, `"custom_segment_individual"`
`channel`	`string?`	`"only_push"`, `"only_inbox"`, or `"both_push_and_inbox"`
`title`	`string?`	Notification title.
`message`	`string?`	Notification body text.
`attachment`	`string?`	Media attachment URL, if any.
`segmentTitle`	`string?`	Name of the target segment, if applicable.
`countSends`	`number`	Total send attempts.
`countSessions`	`number`	Sessions attributed to this notification (push + inbox combined).
`countCarts`	`number`	Carts attributed to this notification.
`countPurchases`	`number`	Purchases attributed to this notification.
`totalRevenue`	`number`	Revenue attributed to this notification.

`push_explorer_automated`

Aggregate performance metrics per automated push type (e.g. welcome, abandon cart) over the requested date range. One record per pushType.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`pushType`	`string`	e.g. `"welcome_push"`, `"abandon_cart"`, `"post_purchase"`, `"win_back"`, `"order_tracking"`
`createdAt`	`string`	ISO timestamp when the automated job was configured.
`countDevices`	`number`	Targeted devices.
`countErrors`	`number`	Send errors.
`countInactive`	`number`	Inactive/unregistered devices skipped.
`countSends`	`number`	Successful sends.
`countSessions`	`number`	Attributed sessions.
`countCarts`	`number`	Attributed cart additions.
`countPurchases`	`number`	Attributed purchases.
`totalRevenue`	`number`	Attributed revenue.

`push_explorer_by_time`

Push metrics for all notification types combined, aggregated by time bucket.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`countDevices`	`number`
`countErrors`	`number`
`countInactive`	`number`
`countSends`	`number`
`countSessions`	`number`
`countCarts`	`number`
`countPurchases`	`number`
`totalRevenue`	`number`

Overview

`overview_sessions_by_time`

Session counts broken down by OS, consumer type (new vs. returning), and source type per time bucket. Returns multiple records per bucket — one per unique combination of OS, consumer type, and source type.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`operatingSystem`	`"ios" \| "android"`
`consumerType`	`"new" \| "returning"`
`sourceType`	`"direct" \| "push" \| "deeplink"`	How the session was initiated.
`countSessions`	`number`

`overview_sessions_heatmap`

Session counts bucketed by day of week and hour of day (in the requested timezone). Returns up to 168 records (7 days × 24 hours).

Requires granularity: No

Record shape:

Field	Type	Description
`dayOfWeek`	`"sunday" \| "monday" \| "tuesday" \| "wednesday" \| "thursday" \| "friday" \| "saturday"`
`hour`	`number`	Hour of day (0–23) in the requested timezone.
`appId`	`string`
`countSessions`	`number`

`overview_revenue_by_time`

Total Tapcart App revenue per time bucket.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`totalRevenue`	`number`

Revenue

`revenue_by_time`

Revenue and order counts per time bucket. Average order value (AOV) can be derived as totalRevenue / countOrders.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`totalRevenue`	`number`
`countOrders`	`number`

`revenue_source_of_orders`

Single aggregate row breaking down total order counts by attribution source (direct, push, inbox) for the full date range.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`countOrders`	`number`	Total Tapcart App orders.
`countPushOrders`	`number`	Orders attributed to push notification click-throughs.
`countInboxOrders`	`number`	Orders attributed to inbox click-throughs.
`countDirectOrders`	`number`	Remaining orders not attributed to push or inbox (floored at 0).

`revenue_promo_vs_revenue`

Revenue split between discounted (promo) and non-discounted orders per time bucket.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`promoRevenue`	`number`	Revenue from orders that had a discount applied.
`otherRevenue`	`number`	Revenue from orders with no discount.

`revenue_aov_by_os`

Total revenue and order count per OS, enabling AOV calculation (totalRevenue / countOrders) broken down by platform.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`operatingSystem`	`"ios" \| "android"`
`totalRevenue`	`number`
`countOrders`	`number`

Acquisition

`acquisition_daily_active_users`

Unique active device count (DAU) per time bucket and OS.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`operatingSystem`	`"ios" \| "android"`
`countDau`	`number`	Distinct active devices in the bucket.

`acquisition_source_of_opens`

Single aggregate row of session counts broken down by how the session was initiated (direct, push, deeplink) for the full date range.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`countDirect`	`number`	Sessions opened directly.
`countPush`	`number`	Sessions opened via push notification.
`countDeeplink`	`number`	Sessions opened via deep link.
`countTotal`	`number`	Total sessions.

`acquisition_open_rate`

Daily unique openers compared against the cumulative installed device base per time bucket. Open rate can be derived as countDailyOpeners / countInstalledBase. The installed base excludes devices inactive for 230+ days before endTimestamp.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`countDailyOpeners`	`number`	Unique devices with at least one session in the bucket.
`countInstalledBase`	`number`	Total active installed devices. This value is the same across all rows — it is computed once for the period end.

`acquisition_app_installs`

App install counts per time bucket and OS.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`operatingSystem`	`"ios" \| "android"`
`countInstalls`	`number`

`acquisition_signed_up_users`

New account creation counts per time bucket.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`countSignups`	`number`

`acquisition_time_to_first_purchase`

Average time from first app session to first purchase, bucketed by when the first purchase occurred.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start (keyed to when the first purchase happened).
`appId`	`string`
`avgTimeToFirstPurchaseMs`	`number`	Average milliseconds elapsed between a customer's first app session and their first purchase.

Retention

`retention_repurchase_rate`

Cumulative repurchase rate over time. For each bucket date, returns the total count of customers who have ever made at least one purchase up to that date, and the count who have made at least two.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`countTotalCustomers`	`number`	Customers with ≥1 purchase ever, as of this bucket date.
`countRepeatCustomers`	`number`	Customers with ≥2 purchases ever, as of this bucket date.

`retention_session_length`

Average session duration and session count per time bucket and OS.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`operatingSystem`	`"ios" \| "android"`	Null OS values are excluded from this metric.
`avgSessionDurationMs`	`number`	Average session length in milliseconds (capped at 1,800,000 ms / 30 min).
`countSessions`	`number`

`retention_sessions_per_user`

Average number of sessions per active user per day, broken down by operating system.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`operatingSystem`	`"ios" \| "android"`	Null OS values are excluded from this metric.
`avgSessionsPerUser`	`number`

`retention_customer_lifetime_value`

Daily customer lifetime value (CLV) snapshots from a pre-materialized model. CLV is calculated using a rolling-year AOV × frequency × expected-lifetime formula.

Requires granularity: No (daily grain is always used)

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the calendar day.
`appId`	`string`
`customerLifetimeValue`	`number`	Estimated CLV for the merchant on this date.

`retention_dormancy_rate`

Active vs. dormant device counts per time bucket. Active = last session within 30 days of the bucket date. Dormant = last session 30–230 days before the bucket date. Lapsed devices (>230 days inactive) are excluded from both counts.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`countDormantDevices`	`number`	Devices last active 30–230 days before this bucket date.
`countActiveDevices`	`number`	Devices last active within 30 days of this bucket date.

`retention_order_frequency`

Average orders per customer per time bucket, along with supporting customer and order counts. Guest checkouts (no associated customer ID) are excluded.

Requires granularity: Yes

Record shape:

Field	Type	Description
`granularity`	`string`	ISO timestamp of the bucket start.
`appId`	`string`
`avgOrdersPerCustomer`	`number`
`countCustomers`	`number`	Distinct customers who placed at least one order in this bucket.
`countOrders`	`number`	Total orders in this bucket (excluding guest checkouts).

Customer Journey

`customer_journey_conversion_funnel`

Single aggregate row showing the conversion funnel from sessions through to purchases for the full date range. Each count represents distinct sessions that reached that funnel stage.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`countSessions`	`number`	Total distinct sessions.
`countProductViewed`	`number`	Sessions with at least one product view.
`countAddedToCart`	`number`	Sessions with at least one add-to-cart.
`countPurchaseCompleted`	`number`	Sessions with at least one completed purchase.

`customer_journey_top_viewed_products`

Top 10 most viewed products with their view counts and share of total views.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`productId`	`number`	Shopify product ID.
`countViews`	`number`	Total views for this product.
`countTotal`	`number`	Total product views across all products (same value on every row; use this to compute share of views).

`customer_journey_top_wishlisted_products`

Top 10 most net wishlisted products (adds minus removes). Products with a net wishlist count of zero or below are excluded.

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`productId`	`number`	Shopify product ID.
`countWishlisted`	`number`	Net wishlist additions (adds minus removes) for this product.
`countTotal`	`number`	Sum of all positive net wishlist counts across all products (same value on every row).

`customer_journey_top_purchased_products`

Top 10 most-purchased products by total items sold (not order count).

Requires granularity: No

Record shape:

Field	Type	Description
`appId`	`string`
`productId`	`number`	Shopify product ID.
`countPurchased`	`number`	Total items purchased for this product.
`countTotal`	`number`	Total items purchased across all products (same value on every row).