Event Tracking
Looking for no-code tracking? Passive data collection captures page views and sessions automatically. No per-event code required.
Event tracking tells Churnkey what your customers do inside your product. You send a named event with an account identifier. Churnkey joins it to that account's billing record, so usage and billing live on one timeline. You can send events over plain HTTP from any language, or with the @churnkey/node package on Node. One request per event is enough.
Who an Event Belongs To
Every event belongs to an account. Every event must carry at least one of these two fields:
| Field | What it is |
|---|---|
customerId | The account's id in your billing provider, for example a Stripe cus_… id |
uid | Your own id for the same account, for example the row id in your database |
These are two names for one account. Churnkey keeps a single internal id for it. That means you can track an account by uid before it has a billing id, for example during a free trial that has not reached checkout.
Send uid alone when the account has no billing id yet. Send both when you have both.
customerEmail is metadata. It is stored with the event, but it cannot identify one. An event with only customerEmail is rejected.
Linking Your Id to the Billing Id
To join a uid to a customerId, send both on one event that is allowed to link them. That is either:
- a server-side event sent with your API key, or
- a browser event signed over its
customerId.
That one event links them. Events already sent under the uid stay on the account, so you do not need to resend anything. Keep sending uid on every event after that. Once the two are linked, an event with only the customerId also lands on the same account.
Some events carry both ids but do not link them:
- A browser event signed over the
uidorcustomerEmailis recorded against theuidonly. Churnkey drops thecustomerIdfrom the stored event, unless the account already has that billing id. - An unverified event, one with no valid API key or signature, is handled the same way.
If the uid already has events and you also sent events with only the customerId before the link, those customerId events stay on a separate account in Churnkey's records. The Lifecycle page still counts them toward that customer for the days that account carried the billing id. Send the uid from the first event to avoid the split.
If an account moves to a new billing id, send the new pair the same way. The latest link wins. The account answers to the new billing id, and any other account that had that billing id gives it up. On the Lifecycle page the old account's usage counts toward that billing id up to the day it last carried it, and not after.
Products Sold to Teams
If your product is sold to a company and used by several people, add a user object to identify the person inside the account:
{
"event": "Report Exported",
"customerId": "cus_abc",
"user": { "uid": "user_123" }
}
user.uid is your own id for that person. It is optional. Account-level metrics, such as activation, retention and usage state, are always computed per account. Churnkey counts active people from the user.uid on each event. When the Lifecycle page is set to Teams, it shows how many people each account had in the last 30 days.
Products Sold to Individuals
If each paying account is one person, omit user. The account is the person. Sending user.uid for a consumer product adds nothing and makes the people count misleading.
What to Track
Two to four explicit server-side events per product is the right amount. Send:
- The things people do in your product every day or week. One to three actions a customer takes when they are getting value:
Report Exported,Campaign Sent,Video Rendered,Job Scheduled. Pick the meaningful actions, not every click and not your highest-volume event. - The thing they get out of it. The lower-volume moment that means the work paid off:
Invoice Sent,Booking Confirmed,Meeting Booked. This is usually the best activation event.
If a system does the work rather than a person, for example reservations synced or emails sent by a sequence, send that. It counts as usage even though no one clicked.
You do not label events when you send them. Every event you send appears on the Lifecycle page:
- Usage is the set of events that count as using your product. Until you change it, every event counts.
- Activation is a second set, and each activation event must also be ticked as usage. A new account is activated when it sends one of them within a window that starts at its first payment. The window is 14 days by default, and you can change it on the Lifecycle page. Until you pick activation events, any usage event counts.
Billing events need no instrumentation. Subscription created, upgraded, paused, past due and cancelled all come from your billing integration.
If you run the Churnkey pause wall or failed-payment wall, the Churnkey script sends a ck-pause-wall or ck-failed-payment-wall event when a signed-in customer loads your app. After that it skips the check in that browser for 24 hours, unless the wall is showing. These events carry the customerId and email but no uid, and they count as usage until you take them out of the usage set. So the Lifecycle page shows who opens your app before you send any events of your own.
Naming
- Event names are Object + Action in Title Case:
Post Created,Teammate Invited,Export Failed. - Property keys are
snake_case:post_type,seat_count. - Keep dynamic values out of event names. Send
Report Exportedwithformat: 'csv', notReport Exported CSV.
Sending Events
Server Side
Server-side events are verified by your API key, and they can link a uid to a customerId, so they are the preferred route. Get your API key and App ID from Churnkey | Account.
If you run Node, use the latest @churnkey/node:
import { Churnkey } from '@churnkey/node';
const appId = process.env.CHURNKEY_APP_ID;
const apiKey = process.env.CHURNKEY_API_KEY;
if (!appId || !apiKey) throw new Error('Set CHURNKEY_APP_ID and CHURNKEY_API_KEY');
const churnkey = new Churnkey({
appId,
apiKey,
mode: 'live', // 'test' for a test-mode API key
});
await churnkey.track({
event: 'Report Exported',
customerId: 'cus_abc', // billing-provider id
uid: 'acct_42', // optional: your own id for the same account
userUid: 'user_123', // optional, B2B only: the person inside the account
properties: {
format: 'csv',
},
timestamp: new Date(), // optional, defaults to now
});
track posts to /v1/api/events/new with your API key, App ID and mode in the headers. Pass uid without customerId for an account that has no billing id yet. mode defaults to 'live'. Pass mode: 'test' when you use a test-mode API key.
track resolves once Churnkey has stored the event. It rejects with a ChurnkeyApiError when:
- the API answers with an error status,
- the request fails before an answer arrives, in which case
statusis0, or - the API stored the event but did not accept your API key (
verified: false).
The error has status, body (the response body) and sent (how many events Churnkey is known to have stored).
To backfill, pass an array of the same objects to trackBatch. It sends them to the bulk endpoint in order, in requests of 100. The bulk endpoint has to be enabled for your account first; see Server Side Bulk Create. If a request fails, the requests before it are already stored, and the error's sent tells you where to resume. A request that failed with a 5xx may have stored its events too, so resuming from sent can send a few events twice.
From any other language, send the request yourself:
const headers = {
'x-ck-api-key': 'YOUR_CHURNKEY_API_KEY',
'x-ck-app': 'YOUR_CHURNKEY_APP_ID',
'x-ck-mode': 'live', // 'test' for a test-mode API key
};
const eventBody = {
event: 'Report Exported',
customerId: 'cus_abc', // billing-provider id
////////////////////////
// OPTIONAL ITEMS BELOW
////////////////////////
uid: 'acct_42', // your own id for the same account
eventDate: '2022-05-01', // use for backfilling data, default is now
eventData: {
format: 'csv',
},
////////////////////////
// B2B ONLY
////////////////////////
user: {
uid: 'user_123', // the person inside the account
},
};
axios.post('https://api.churnkey.co/v1/api/events/new', eventBody, { headers });
The response looks like this:
{ "status": "success", "event_id": "6650c0ffee0000000000abcd", "verified": true }
verified: false means Churnkey stored the event but did not accept your API key. The key is wrong or revoked, or it belongs to another mode. A test-mode key needs x-ck-mode: test. A rejected key still returns 200, so check verified on the response.
Server Side Bulk Create
Use the bulk endpoint to backfill history, for example when you first connect Churnkey and want activation and retention to have a past to measure against. It accepts up to 100 events per request.
The bulk endpoint is turned on per organization. Until it is enabled for your account it returns 404. Email support@churnkey.co with your App ID to request it.
Unlike the single-event endpoint, bulk requests cannot carry customerData. Bulk events can link a uid to a customerId when the request is sent with your API key. A signature in the headers covers only the one customerId it was made over, so events in the request that name a different customerId cannot link it. If any event in the request is invalid, the whole request is rejected and nothing is stored.
const headers = {
'x-ck-api-key': 'YOUR_CHURNKEY_API_KEY',
'x-ck-app': 'YOUR_CHURNKEY_APP_ID',
'x-ck-mode': 'live', // 'test' for a test-mode API key
};
const events = [
{
// ...events as defined above, including event, eventDate, and customerId or uid
},
];
axios.post('https://api.churnkey.co/v1/api/events/bulk', events, { headers });
The response is { "status": "success", "event_count": 100, "verified": true }, where event_count is the number of events stored.
Client Side
Server-side event creation is preferred. Browser traffic is rate limited per IP and can be forged.
Client-side events need the Churnkey script on the page. See Step One of the quick start guide. Send them with window.churnkey.event(...).
Sign the customerId. Compute the signature on your backend using the HMAC steps from Step Two of the quick start guide, with the customerId as the message. A signature over the customerId verifies the event and lets it link a uid to that customerId. Churnkey also accepts a signature over the uid or customerEmail. That verifies the event, but the event cannot link ids.
window.churnkey.event() checks the signature in the mode you last passed to window.churnkey.checkPulse, window.churnkey.init or window.churnkey.check on that page, and in live mode if you passed none. A test-mode signature checked in live mode fails without an error. The event is stored with verified: false.
// Fetched from your backend, see Step Two of the quick start guide.
const hmacSignature = await getSignedCustomerId(customerId);
window.churnkey.event({
customerId: 'cus_abc',
customerEmail: 'jane@example.com', // metadata only
appId: 'YOUR_CHURNKEY_APP_ID',
authHash: hmacSignature,
event: 'Report Exported',
eventData: {
format: 'csv',
},
});
window.churnkey.track(name) is the short form. It records the event for the customer you last passed to window.churnkey.checkPulse, window.churnkey.check or window.churnkey.init on that page, with that call's signature.
window.churnkey.track('Report Exported');
Use window.churnkey.event() when you need eventData, customerData or a uid.
If your integration calls both event() and track() for the same action, remove the extra track() call. Both calls now record the event, so using both counts it twice.
An event sent with either call can start a Pulse that is waiting on it.
Unverified Events
Events sent without a valid API key or signature are accepted. Churnkey stores them with verified: false. An unverified event still counts as usage on the Lifecycle page. It can also start a Pulse. It cannot link a uid to a customerId, and its customerData is ignored.
Limits
Rate Limits
By default, every request to the events endpoints is limited to 50 per minute per IP address. That includes server-side requests sent with your API key. The bulk endpoint counts separately from the single-event endpoints.
If you send events from a few backend hosts, email support@churnkey.co to raise the limit. A raised limit applies per App ID, and only to requests sent with an API key that Churnkey accepts. It is 250 per minute once the bulk endpoint is enabled for your account, unless support sets a different number. Browser traffic stays at 50 per minute per IP.
Requests over the limit return 429. Retry after a minute.
Payload Validation
eventData, customerData and user.data must be flat objects. Values must be strings, numbers or booleans. Nested objects and arrays are rejected. Each object can have at most 256 keys and at most 10,000 characters of JSON.
Dates arrive as ISO strings, because the body is JSON. The Node SDK converts Date values in properties for you. Keys with a null value are dropped.
Errors
| Status | When |
|---|---|
401 | The request has no App ID, or an App ID Churnkey does not recognize. |
422 | The event has neither customerId nor uid, has no event name, or has invalid properties. On the bulk endpoint, the body is not an array or has more than 100 events. |
404 | The bulk endpoint is not enabled for your account. This is checked after the array and size checks above. |
429 | The request is over the rate limit. |
Customer Attributes
In addition to events, you can update customer data. Include a customerData property on the single-event endpoint, or send it to events/customer-update. Churnkey saves customerData only from verified requests. When the request names a customerId, it also needs your API key or a signature over that customerId, the same authority as linking. A signature over the uid or email returns verified: true but does not save customerData for a request that carries a customerId.
You must include at least one of uid or customerId. customerData describes the account. user.data is not stored on a person record. To set the people on an account, use the set-users endpoint described in the Billing Contact API.
const headers = {
'x-ck-api-key': 'YOUR_CHURNKEY_API_KEY',
'x-ck-app': 'YOUR_CHURNKEY_APP_ID',
'x-ck-mode': 'live', // 'test' for a test-mode API key
};
const dataUpdate = {
uid: 'acct_42', // your own id for the account
customerId: 'cus_xyz', // billing-provider id
customerData: {
num_seats: 7,
name: 'Acme, Inc.',
},
};
axios.post('https://api.churnkey.co/v1/api/events/customer-update', dataUpdate, { headers });