How the objects relate

Beacon publishes four objects today — account, deal, segment and cohort. Each page describes one object on its own. This page describes how they fit together: which belongs to which, how many of one go with one of another, which of those links can change after the fact, and which of them you can actually read through a door today.

​

The five objects in one view

​

Account — the spine everything joins to

The account is the object every other object hangs off. It has one identifier, issued once when Beacon resolves the customer’s identity from your connected systems, and that identifier is what a deal, a subscription and a segment assignment all point at. An account belongs to exactly one segment. Segments do not overlap, so there is never a second answer. The account carries its segment’s label as segment, and its segment’s health tier as segment_health_tier for context — the tier is a fact about the group, not about the account. An account belongs to several cohorts at once — the month it became a customer, the month its revenue started, the campaign that first reached it. All of them are correct at the same time, because each answers a different question. An account has deals and subscriptions. Deals are published as their own object. Subscriptions are not: they are the billing records Beacon reads to produce recurring revenue, and what reaches the account from them is already worked out — mrr_band, net_revenue_retention, renewal_date. There is no subscription object on any door.

​

Deal — one account, always

Every deal belongs to exactly one account, and that never changes. A deal is the opportunity as your CRM holds it, keyed to the account identity Beacon resolved rather than to the CRM’s own company record. Its stage history lives inside Beacon and is what deal_stage, days_in_stage and deal_velocity_percentile are read from; the history itself is not published — how it is stored is described on the Lifecycle object page. A deal is never itself a member of a cohort — cohorts hold accounts. What a deal does is open cohorts for its account: the account’s first deal opens its Entered pipeline cohort, and its first won deal opens its Became customer cohort.

​

Segment — a partition of your accounts that can move

Your segments partition your accounts: every account is in exactly one, none is in two, and none is in none. Your set holds between three and twelve segments, and a group has to hold at least 10 active accounts or at least 5% of your recurring revenue to stand as one — below that it is merged into the nearest. The link from account to segment is the one that moves. An account crosses a boundary when its own characteristics change, and Beacon records when it moved and where from. An approved merge, split or rename re-cuts the whole set. Either way, a segment figure can change without any customer doing anything differently — which is why segment_account_count is published beside every other segment value: it is the population every figure is read against, and the first thing to check when a segment number moves. A segment is also one of the seven dimensions a cohort can be cut on. So a cohort can be the accounts acquired in March, in the Enterprise segment — the segment supplies the cut; the cohort supplies the frozen population.

​

Cohort — a population frozen at entry

A cohort’s members are fixed the moment it opens and never change. An account that qualifies later belongs to a later cohort of the same type, never to the one already open. That freezing is what makes two cohorts comparable years apart, and it is the exact opposite of a segment, whose membership is meant to move. Every cohort holds customer accounts, whatever its type. What the type changes is the event that put them there — becoming a customer, revenue starting, a named campaign first reaching them, and the rest of the thirteen on cohort type. Its two retention curves are struck over its members month by month, and its two economics figures — acquisition cost and lifetime value — are struck per member at 18 and 24 months.

​

Company and period — where all of it rolls up

The fifth object is the only one that is not about a customer. It is one row per period for your company as a whole, carrying recurring revenue, the five movements that change it, the two retention ratios, logo churn and margin. Everything else on this page belongs to it. Every account, every deal, every segment and every cohort is one company’s, and the period row is where their figures come together. What it holds is the totals, not the records behind them — there is no list of accounts on a period. A period has no membership, which makes it unlike both a segment and a cohort. A segment’s population moves when an account crosses a boundary. A cohort’s is frozen the moment it opens. A period is neither, because it is a window in time: what falls inside it is settled by when something happened, not by what anything is. The two retention ratios are the one place a population appears — each is struck against the customers you held on the first day of the period, and that starting set is what the ratio is measured from. A period is a month, a quarter, a year or the trailing twelve months. The same figure over two different period lengths is two different numbers, not two views of one number, so a period figure is only comparable to another struck over the same length.

​

Which links are published today

Every object carries its own identifier on every door — id in the example payloads. Beyond that, one link crosses a door today, and the rest do not: So from the published shapes alone you can tell which segment an account is in and how many accounts a segment has. You cannot yet walk from a deal to its account, from an account to its cohorts, from a cohort to its members, or from a company figure down to the records it was built from. That is a limit of what is published, not of how Beacon is built — the links exist in the model — and it is stated here rather than left for you to discover. Nothing on this page is a join key you can rely on being served: the object pages are the contract, and entity_scope on the API narrows a read to one entity inside your grant, it does not join two.

​

What is not here yet

Beacon also holds target and plan figures — what you set out to do, against the periods above. Those are not published as an object yet. When they are, they join this page as the sixth, and the relationship to describe will be between a period’s figures and the plan that period was measured against. The same is true of the lifecycle — the journey the objects on this page move along. Beacon holds one record per lifecycle today, and the design that stores its stages, its movement history and its signal attachments as records is settled but not yet running. When the lifecycle object publishes, it joins this page too, and the relationships to describe are the ones the other objects already imply: an account sits in a stage of the customer lifecycle, a deal’s stage history is the movement record of that journey’s sales leg, and a cohort’s retention curve is struck along it. How that data is stored — and exactly which parts exist today — is on the Lifecycle object page.

​

Related