> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconrevenue.io/llms.txt
> Use this file to discover all available pages before exploring further.
# How the objects relate
> How an account, a deal, a segment and a cohort connect — which belongs to which, which links can move, and which of those links are published today.
Beacon publishes four objects today — [account](/data-model/account), [deal](/data-model/deal), [segment](/data-model/segment) and [cohort](/data-model/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 links described here are how Beacon's model is built. Only some of them are published as values yet — the last section says exactly which. No read interface or MCP tool serves any object yet.
## The five objects in one view
| Object | One row per | Belongs to | Holds | Can its membership change? |
| - | - | - | - | - |
| Account | Customer account | Exactly one segment · several cohorts, of different types | Its deals · its subscriptions | Its segment can change. Its cohorts never do |
| Deal | Opportunity | Exactly one account | — | Never. A deal does not move between accounts |
| Segment | Segment in your set | — | Its accounts | Yes — an account can cross a boundary, and the whole set can be re-cut |
| Cohort | Cohort | — | The accounts that went through the same event together | Never. Membership is frozen when the cohort opens |
| Company and period | Period, for the company as a whole | — | Nothing — it holds totals, not records | It has no membership. What falls in a period is decided by when things happened |
## 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](/data-model/lifecycle) 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](/definitions/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:**
| Link | Published? | How |
| - | - | - |
| Account → its segment | Yes | `segment` on the account, and `segment_health_tier` beside it |
| Deal → its account | No | The deal object carries no account reference |
| Account → its cohorts | No | Neither the account nor the cohort lists the other |
| Segment → its accounts | Count only | `segment_account_count`; the accounts themselves are not listed |
| Cohort → its members | No | The cohort publishes its curves and figures, not its member list |
| Company period → what rolls up into it | No | The period publishes totals; nothing on it names the accounts, deals, segments or cohorts they came from |
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](/api-reference) 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](/data-model/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](/data-model/lifecycle) page.
## Related
The objects, the doors, and the availability marks.
What opens a cohort, and why the set of types is fixed.
How the grouping is formed and when an account moves.
The thirteen figures for the company as a whole, one row per period.
How the journey itself is stored — the lifecycle record, stages, movement and signals.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.