Activity and Usage Events

Ranksy records two different kinds of event about your merchants — activity and usage. This guide explains the difference, how to send each one, and where each shows up in Ranksy.

The Two Kinds of Event

Both come in through the same /track API call. What separates them is one field: event_handle.

The short version: activity is your product-analytics stream (think Mixpanel), and usage is your metering stream (the numbers you'd bill or report on).

Activity Events

Activity events track how a merchant moves through your app — opened it, opened the dashboard, changed a setting. They're lightweight, and you'd typically send one on every page load.

Send an activity event by calling /track with a type and no event_handle:

{
  "myshopify_domain": "store.myshopify.com",
  "type": "dashboard_viewed",
  "meta": { "page": "/dashboard" }
}

type defaults to app_opened if you leave it out, so a bare /track call already counts as "the merchant opened the app". The meta object is free-form context, stored as-is.

Where it shows up:

• Customer → Activity — a timeline of what the merchant did, most recent first.
• Last seen — every /track call, activity or usage, updates the merchant's last-seen time. You'll see it on the customer record and can sort and filter your CRM by it.

💡 Activity events stay inside Ranksy. They're never sent to Shopify.

Usage Events

Usage events track what your app did for the merchant — the things you'd count, report on, or bill for. Messages sent, orders synced, emails delivered.

Send a usage event by calling /track with an event_handle and, usually, a numeric value:

{
  "myshopify_domain": "store.myshopify.com",
  "event_handle": "messages_sent",
  "attributes": { "value": 12 }
}

The value is what Ranksy sums. Send messages_sent with a value of 12 a hundred times over a month and Usage Metrics shows a count of 100 events and a total of 1,200 messages.

Where it shows up:

• Customer → Usage — per-handle totals for that one merchant.
• Usage Metrics — totals across every merchant, filterable by handle, shop, and date range.

Usage events also carry the merchant's identity forward correctly, so a message sent by store A is counted against store A and never mixed up with store B.

Sending Usage to Shopify (Optional)

Usage events can be forwarded to Shopify's App Events API, where they can feed a usage-based billing meter you've set up on your app. This is optional — leave it off and the event is still recorded in Ranksy.

To forward, include an app_events_token (an app-level JWT you mint from your Shopify Dev Dashboard credentials) on the /track call. The full mint-and-forward flow is in the API reference.

⚠️ Don't put personal data in a usage event's attributes — no names, emails, phone numbers, or customer IDs. Shopify's App Events terms prohibit it, and Ranksy forwards your attributes as-is. Use non-identifying values like a campaign, a plan, or a count.

How Ranksy Decides Which Is Which

One field decides it: event_handle.

• No event_handle → activity. The type and meta are recorded to the activity timeline.
• An event_handle is present → usage. It's counted, summed, and optionally forwarded.

A single /track call is one or the other, never both. If you send an event_handle, the type and meta fields are ignored — a usage event is never also logged as activity, so one tracked action never double-counts.

FAQ

I sent messages_sent as a type and it's not showing in Usage Metrics. Why? Because a type is an activity event — it lands in the Activity timeline, not the usage store, so it's never counted. To get it into Usage Metrics, send it as an event_handle with a value instead:

{ "myshopify_domain": "store.myshopify.com", "event_handle": "messages_sent", "attributes": { "value": 1 } }

Can one call record both an activity and a usage event? No. Send two separate /track calls if you want both.

Does my activity data go to Shopify? No. Only usage events can be forwarded, and only when you choose to by sending an app_events_token. Activity events never leave Ranksy.

Do I need Shopify's developer preview to send usage events? No. Usage events are recorded in Ranksy — and forwarded to the Shopify Dev Dashboard, if you forward them — without any preview. The preview only matters for one specific case: showing standard Shopify events in the merchant-facing Shopify Analytics. See the API reference for that distinction.

What counts as a "standard" vs "custom" usage event? A handle from Shopify's standard registry (it starts with shopify., like shopify.marketing.email_sent) is a standard event and is validated against that registry. Any other handle — like messages_sent or orders_synced — is a custom usage event, recorded with no schema check. Both are counted in Usage Metrics.

Next Steps

• Track endpoint — API reference — the full /track request, both event kinds, and how to mint an app_events_token.
• Usage Metrics endpoint — API reference — read your usage totals back over the API.
• Connect Partner API — sync revenue and subscription data alongside your events.