Ecommerce Analytics

Ecommerce analytics lets you track purchases, revenue, cart activity, and product performance alongside your deep link metrics. All ecommerce data appears in the Analytics page under the Ecommerce, Attribution, and Cohorts tabs.

Note

Ecommerce analytics is available on paid plans (Standard and above). Free tier appspaces cannot send ecommerce events.

Setting up ecommerce tracking

Ecommerce events are tracked via the Tolinku SDK. Install the SDK for your platform, initialize it with your publishable API key, and call the ecommerce methods.

Web

import { Tolinku } from '@tolinku/web-sdk';

const tolinku = new Tolinku({ apiKey: 'tolk_pub_...' });
tolinku.setUserId('user_123'); // Required for attribution

// Track a purchase
await tolinku.ecommerce.purchase({
  transaction_id: 'order_456',
  revenue: 49.99,
  currency: 'USD',
  items: [
    { item_id: 'sku_1', item_name: 'T-Shirt', price: 24.99, quantity: 2 }
  ]
});

React Native

import { Tolinku } from '@tolinku/react-native-sdk';

Tolinku.init({ apiKey: 'tolk_pub_...' });
Tolinku.setUserId('user_123');

await Tolinku.ecommerce.purchase({
  transaction_id: 'order_456',
  revenue: 49.99,
  currency: 'USD',
  items: [
    { item_id: 'sku_1', item_name: 'T-Shirt', price: 24.99, quantity: 2 }
  ]
});

iOS (Swift)

try Tolinku.configure(apiKey: "tolk_pub_...")
let tolinku = try Tolinku.requireShared()
tolinku.setUserId("user_123")

await tolinku.ecommerce.purchase(
  transactionId: "order_456",
  revenue: 49.99,
  currency: "USD",
  items: [TolinkuItem(itemId: "sku_1", itemName: "T-Shirt", price: 24.99, quantity: 2)]
)

Android (Kotlin)

Tolinku.configure(apiKey = "tolk_pub_...", context = applicationContext)
Tolinku.setUserId("user_123")

Tolinku.ecommerce.purchase(
  transactionId = "order_456",
  revenue = BigDecimal("49.99"),
  currency = "USD",
  items = listOf(TolinkuItem(itemId = "sku_1", itemName = "T-Shirt", price = BigDecimal("24.99"), quantity = 2))
)

Flutter (Dart)

Tolinku.configure(apiKey: 'tolk_pub_...');
Tolinku.instance.setUserId('user_123');

await Tolinku.instance.ecommerce.purchase(
  transactionId: 'order_456',
  revenue: 49.99,
  currency: 'USD',
  items: [TolinkuItem(itemId: 'sku_1', itemName: 'T-Shirt', price: 24.99, quantity: 2)],
);

Event types

Tolinku supports 13 ecommerce event types:

Event	Method	When to use
view_item	ecommerce.viewItem()	User views a product page
add_to_cart	ecommerce.addToCart()	Item added to shopping cart
remove_from_cart	ecommerce.removeFromCart()	Item removed from cart
add_to_wishlist	ecommerce.addToWishlist()	Item added to wishlist
view_cart	ecommerce.viewCart()	User views their cart
add_payment_info	ecommerce.addPaymentInfo()	Payment method entered
begin_checkout	ecommerce.beginCheckout()	Checkout flow started
purchase	ecommerce.purchase()	Order completed (requires transaction_id, revenue, currency)
refund	ecommerce.refund()	Order refunded (requires transaction_id, revenue)
search	ecommerce.search()	Product search performed
share	ecommerce.share()	Product shared
rate	ecommerce.rate()	Product rated or reviewed
spend_credits	ecommerce.spendCredits()	Loyalty credits redeemed

Cart ID lifecycle

The SDK automatically manages a cart ID to link cart events together:

1. On the first addToCart() call, a unique cart ID is generated and stored locally
2. All subsequent cart events (viewCart, beginCheckout, addPaymentInfo) automatically include the same cart ID
3. After purchase(), the cart ID is cleared
4. The next addToCart() generates a new cart ID for the new shopping session

You can also pass your own cartId parameter to any cart-related method if you manage cart IDs server-side.

Dashboard overview

The analytics page has five tabs. Ecommerce data appears in three of them:

Ecommerce tab

Revenue-focused metrics and breakdowns:

• Revenue overview cards: Total Revenue, Net Revenue, Orders, AOV, Cart Abandonment Rate, Add-to-Cart Rate
• Revenue time series: Daily revenue chart
• Ecommerce funnel: View Item > Add to Cart > View Cart > Begin Checkout > Add Payment Info > Purchase
• Top products: Best-selling items by revenue
• Revenue by channel: Campaign/source/medium with revenue and conversion rate
• Cart abandonment: Abandonment rate and abandoned cart value
• Coupons: Revenue and usage by coupon code
• Revenue by device and platform: Mobile vs desktop, iOS vs Android vs Web

Attribution tab

See which deep link campaigns actually drive revenue:

• Choose an attribution model: Last Click, Linear, or Time Decay
• Set an attribution window: 7, 14, 30, 60, or 90 days
• View attributed revenue, orders, and percentage of total per campaign
• See unattributed revenue (purchases without a matching click)

Tip

Attribution requires setUserId() to be called in the SDK before the user clicks a deep link. The same user ID must appear on both the click event and the purchase event.

Cohorts tab

Track customer lifetime value over time:

• Cohort matrix: Revenue by acquisition month across subsequent months
• Average LTV: Across all cohorts
• Total purchasing users: Unique buyers in the period

Currency configuration

Set your base currency in Appspace Settings > Ecommerce. All revenue is automatically converted to your base currency using live exchange rates from Open Exchange Rates (200+ currencies supported, updated hourly).

If a purchase event doesn’t include a currency field, the appspace’s base currency is used as the default.

Reporting timezone

Set your reporting timezone in Appspace Settings > Ecommerce. Revenue time series charts group data by date in your configured timezone, so daily revenue totals match your business hours.

Fraud detection

Basic fraud rules are enabled by default on paid plans:

• Bot detection: Purchases from bot-flagged user agents are blocked
• Impossible revenue: Purchases exceeding your configured maximum are flagged
• Velocity check: Users exceeding the configured purchases-per-hour limit are flagged
• Currency mismatch: Purchases in currencies not in your allowed list are flagged

Flagged events (severity 1) are included in analytics but marked. Blocked events (severity 2) are not stored. Configure fraud settings in Appspace Settings > Ecommerce.

Transaction deduplication

Purchase and refund events are automatically deduplicated by transaction_id. If the same transaction ID is sent twice (e.g., due to a network retry), only the first event is stored. This prevents double-counting revenue.

Data retention

Ecommerce data follows the same retention limits as all analytics data:

Plan	Retention
Free	7 days
Standard	180 days
Growth	365 days
Scale / Enterprise	730 days

Export your data via CSV before it expires if you need it for longer periods.

Testing your integration

Before going live, you can verify your ecommerce integration by:

1. Sending a test event via the SDK or API
2. Checking the Analytics > Ecommerce tab for the event
3. Verifying revenue totals, currency formatting, and item details appear correctly

Caution

Test mode (for filtering test events from production analytics) is planned for a future release. For now, use a separate test appspace or verify in a staging environment.

Known limitations

• Cross-device attribution: If a user clicks a deep link on their phone but purchases on their desktop, attribution only works if they are logged in on both devices (same user_id)
• Product revenue vs base currency: The top products table uses item prices in the original currency, not the base currency. For multi-currency stores, product-level revenue totals may mix currencies
• Cart abandonment timing: The dashboard shows an approximate abandonment rate (checkouts vs purchases). The cart abandonment background job provides more accurate per-cart detection with webhook notifications

GDPR: Deleting user data

You can delete all analytics events for a specific user via the API:

curl -X DELETE https://api.tolinku.com/v1/api/analytics/user/USER_ID \
  -H "X-API-Key: tolk_sec_..."

This removes the user’s events from all three ClickHouse tables (events, event_items, event_properties). The deletion is asynchronous; data is typically removed within minutes.

Ecommerce API Reference Full API documentation for ecommerce event ingestion and query endpoints.

SDK Documentation Integration guides for Web, iOS, Android, React Native, and Flutter.