Documentation

The lifecycle

Everybody in Kicklace stands at one stage — Visitor, Subscriber, Account, Activated, Purchaser, Repeat — and nobody puts them there by hand: the stage comes from what the person did. This is the whole ladder in one place: the two orders, the two stages you can switch on, the one thing that moves anybody down it, and every event Kicklace knows by name with what it moves.

Every person in Kicklace sits at one stage of one pipeline, and for people that pipeline is the lifecycle: Visitor, Subscriber, Account, Activated, Purchaser, Repeat. Nobody sets it by hand. It comes from what the person did — a page read, a signup, a payment — so a board of it is a description of your business rather than a list of what somebody remembered to update.

There are two orders, because software is bought two ways, and a workspace picks one when it is made:

A web app or service — Visitor → Subscriber → Account → Activated → Purchaser → Repeat. They sign up first and do the first real thing after.
A downloadable app — Visitor → Subscriber → Downloader → Activated → Account → Purchaser → Repeat. They try it before there is an account.

Both are ordinary pipelines from then on: rename a stage, recolour it, move it, add one of your own, under Settings → Pipelines. A stage's key never changes, even when the stage is renamed, because that is what events, saved views, automations and charts refer to it by.

Two stages you can switch on

Neither of these is in a new workspace, because a product with no trial and no subscription should not carry two empty columns for ever. Settings → Pipelines offers each in one press, at the place it belongs, and Remove takes it away again like any other stage.

Trial sits after Account, between the account and the payment. A trial_started event moves somebody into it — from Stripe, where a subscription created with a trial is a trial starting, or posted by your own server.

Churned goes on the end. A churned event, or the subscription_cancelled one Stripe and GitHub post, moves a paying customer into it.

If people in your workspace already have a stage whose key is trial or churned — one you made yourself — that stage stays and the switch says so. Kicklace never replaces a stage somebody set up.

The one move down

A stage only ever moves forward, with one exception, and it is worth saying plainly because everything else in Kicklace depends on stages meaning what they say.

A cancellation is the exception. From Purchaser or Repeat it moves somebody to Churned: they were paying and they stopped, and a board that still showed them as a customer would not be describing anything.

From Trial the same event moves them to Account instead. A trial that ended is not a customer who left — they never paid — and putting them beside the customers who did would make every churn figure wrong.

From anywhere else it moves nobody. Somebody who has only ever read a page cannot churn.

And it is not the end of the road: a purchase from Churned moves them back up to Purchaser. Somebody who left and came back is a customer again.

What counts as activated

Activated means "did the first real thing in the product", and what that is differs in every product, so the product says what it is.

The built-in activated event always counts, and always will. Beyond it, Settings → Pipelines names any other events that count as well — the ones your own servers post, like project_created or first_invoice_sent — under the Activated stage's own row. Each one moves the person to Activated the first time it arrives.

A page read is never offered, because everybody who arrives reads one.

Every event, and what it moves

These are the names Kicklace knows. POST /api/v1/events takes all of them with a secret key, and the kicklace package's track completes them for you. An event whose stage a workspace has not got — a download where there is no Downloader stage, a trial_started where Trial is switched off — is recorded and moves nobody, with no error anywhere: the event is what happened, and the stage is only what Kicklace makes of it.

Event	What it means	Moves them to	Posted by
`pageview`	Somebody read a page. What makes an anonymous visitor a record at all.	Nobody	The tag, your server
`configure`	A demo or configurator was used. Recorded as a visit.	Nobody	The tag, your server
`cta_click`	A download or install link was clicked.	Nobody	The tag, your server
`waitlist_cta`	A waitlist button was clicked. Kept for sites that already post this name.	Nobody	The tag, your server
`measure_cta`	A second call to action was clicked. Kept for sites that already post this name.	Nobody	The tag, your server
`download`	The product was downloaded or started.	Downloader	The tag, your server
`activated`	The first real thing was done.	Activated	Your server
`signup`	An account was created.	Account	Your server, Clerk, Kinde
`trial_started`	A trial began.	Trial	Your server, Stripe
`purchase`	They paid. A second purchase moves them to Repeat; one from Churned takes them back up to Purchaser.	Purchaser	Your server, Stripe, GitHub
`credit_purchase`	The same as `purchase`, under the name an older billing webhook posts.	Purchaser	Your server
`churned`	Somebody who was paying stopped. From Trial it moves them to Account instead.	Churned	Your server, Stripe
`subscription_cancelled`	The same as `churned`, under the name Stripe and GitHub post.	Churned	Stripe, GitHub, your server
`subscription_started`	A subscription began outside a trial. The paid invoice beside it is what moves them.	Nobody	Stripe, GitHub
`subscription_renewed`	A subscription renewed, or a sponsor changed tier.	Nobody	Stripe, GitHub
`refund`	A charge was refunded.	Nobody	Stripe
`checkout_abandoned`	Somebody left a checkout without paying.	Nobody	Stripe
`sign_in`	Somebody signed in. Signing in is not a stage.	Nobody	Clerk, Kinde
`account_deleted`	An account was deleted at your auth provider. Nothing here is deleted with it.	Nobody	Clerk, Kinde
`github_star`	The repository was starred, if you asked for stars to be recorded. A star is not consent.	Nobody	GitHub

The four names near the top of that table are the ones a browser may post through your public key. Everything else belongs to your own servers or to a door you connected, and goes through a secret key.

A name of your own

Any other name is yours: 2 to 40 characters of lowercase letters, digits and underscores, like credit_added. It lands on the person's timeline under that name and an automation can answer it — "when credit_added arrives, send…" — and it moves nobody between stages, because Kicklace cannot know what a name it has never seen means. If one of them is what activation means in your product, name it under Settings → Pipelines and it will.

Names of your own go through a secret key, never from a browser.

What a chart reads

A chart counting events reads properties.value as money, and the source, medium and campaign the person first arrived with. Anything else you post is kept on the row and shown on their timeline.

Two chart filters read the ladder itself rather than where somebody is standing: reached counts everybody at or past a stage, so a funnel counts a purchaser in the Subscriber row as well. Churned is a stage like any other in that arithmetic — it is at the end, so somebody in it has reached every stage before it.