> ## 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.

# Company and period object

> The fourteen figures Beacon publishes about your company as a whole, one row per period — recurring revenue, its five movements, retention, margin and pipeline velocity — and which doors each one reaches, every one behind an opt-in.

The company-and-period object carries fourteen figures about your business as a whole, at one row per period, and two timestamps that accompany every one of them on every door: `as_of` and `computed_at`. **All fourteen reach the doors below, each behind an opt-in that states who becomes able to see it.** The example payload shows what a door returns.

This is the one object that is not about a customer. Every account, deal, segment and cohort belongs to the one company, and this is where their figures roll up.

<Note>
  The names, types and availability below are fixed. No read interface or MCP tool serves them yet — this page publishes the shape ahead of the doors.
</Note>

On the read interface this object is `period` and the collection is [`GET /periods`](/api-reference). The company half of the name is not in the address because a key covers exactly one company: a period is a period of yours.

## Example payload

```json theme={null}
{
  "object": "period",
  "id": "2026-07",
  "as_of": "2026-08-05T06:00:00Z",
  "computed_at": "2026-08-05T06:11:48Z",
  "mrr": 1284000,
  "arr": 15408000,
  "new_mrr": 62000,
  "expansion_mrr": 41500,
  "contraction_mrr": 12800,
  "churn_mrr": 28400,
  "reactivation_mrr": 4200,
  "gross_revenue_retention": 0.968,
  "net_revenue_retention": 1.021,
  "logo_churn": 0.014,
  "contribution_margin": 742000,
  "margin_contribution_index": 63,
  "margin_contribution_band": "in_band",
  "pipeline_velocity": 66
}
```

The identifier is the period the row describes. A period is a month, a quarter, a year or the trailing twelve months — the retention figures in particular are struck over whichever of those you ask for, and the same figure over two different periods is two different numbers.

## Attributes

| Value | Type | Method | What it holds |
| - | - | - | - |
| `as_of` | Timestamp, UTC | System | The moment the value describes — a property of the data, not of Beacon's activity. For a value composed from several sources it is the oldest of them. Present on every response and every property. |
| `computed_at` | Timestamp, UTC | System | When Beacon last worked the value out. Present on every response and every property. |
| `mrr` | Number, reporting currency | Measured | Recurring revenue for the company in the period, as an exact figure. [Definition](/definitions/mrr) |
| `arr` | Number, reporting currency | Measured | The same figure stated annually. It is always recurring revenue multiplied by twelve; there is no separate annual calculation that arrives at it another way. [Definition](/definitions/arr) |
| `new_mrr` | Number, reporting currency | Measured | Recurring revenue that started in the period from customers with no prior history. A customer returning after a gap is not new — that is `reactivation_mrr`. [Definition](/definitions/new-mrr) |
| `expansion_mrr` | Number, reporting currency | Measured | Additional recurring revenue from customers you already had. An upgrade or a cross-sell is a property of this movement, not a movement of its own. [Definition](/definitions/expansion-mrr) |
| `contraction_mrr` | Number, reporting currency | Measured | Recurring revenue lost from customers who reduced but did not leave. A downgrade is a property of this movement. [Definition](/definitions/contraction-mrr) |
| `churn_mrr` | Number, reporting currency | Measured | Recurring revenue lost from customers who went to zero. Voluntary, involuntary and silent churn are kinds of this movement, not separate movements. [Definition](/definitions/churn-mrr) |
| `reactivation_mrr` | Number, reporting currency | Measured | Recurring revenue from customers who had previously churned and came back. [Definition](/definitions/reactivation-mrr) |
| `gross_revenue_retention` | Number, a ratio | Measured | Recurring revenue kept from the customers held at the start of the period, before any expansion is counted. It cannot rise above 1.0. [Definition](/definitions/gross-revenue-retention) |
| `net_revenue_retention` | Number, a ratio | Measured | Recurring revenue kept from the customers held at the start of the period, after expansion, contraction and churn. It can rise above 1.0. The gap between this and the gross figure is what expansion contributed. [Definition](/definitions/net-revenue-retention) |
| `logo_churn` | Number, a ratio | Measured | The share of the customers you held at the start of the period who had left by the end. A count of customers, not an amount of revenue — a period can lose many small customers and little revenue, or the reverse, and this is the figure that tells them apart. [Definition](/definitions/logo-churn) |
| `contribution_margin` | Number, reporting currency | Measured | What the company's revenue contributed after the costs attributed to serving it. [Definition](/definitions/contribution-margin) |
| `margin_contribution_index` | Number, 0–100 | Measured | How well margin is holding up across the business, on one scale. Higher is better. [Definition](/definitions/margin-contribution-index) |
| `margin_contribution_band` | String, one of four bands | Measured | Which band the index falls in — `additive`, `in_band`, `marginal` or `dilutive`. The boundaries are Beacon's and move with your growth posture; they are not something you configure. [Definition](/definitions/margin-contribution-band) |
| `pipeline_velocity` | Number, 0–100 | Measured | How healthily your whole open pipeline is moving, against the pace your own deals have historically set. Higher is healthier. This is the company-wide score; the same measure is also published for each segment's pipeline on the [segment object](/data-model/segment), and the two are one figure at two levels, not two figures. [Definition](/definitions/pipeline-velocity) |

**The five movements are a closed set, and they do not overlap.** Recurring revenue at the end of a period is recurring revenue at the start, plus new, expansion and reactivation, less contraction and churn. Every change is exactly one of the five, so nothing is counted twice and nothing falls between them. Each is published as the amount that moved; which movement it is carries the direction.

**Revenue that did not move is not a movement.** A customer paying the same as last period, and a customer who is inactive, are both baseline retained revenue. Neither is one of the five, and neither appears on this object.

**Recurring revenue is exact here, and banded on an account.** On the [account object](/data-model/account) it is published as `mrr_band`, and no exact recurring-revenue figure is published there today. The company total is published as it stands.

**Pipeline velocity here is the score for your whole pipeline.** On this object it is scored over every open deal the company holds, against the pace set by every deal that closed in the trailing twelve months. On a segment it is scored over that segment's deals against that segment's history. A company-wide reading and a segment reading can differ without either being wrong, and neither is an average of the other. No score by team is published anywhere, because nothing in Beacon defines what a team is.

**Money figures on this object are aggregates, and they travel with two facts rather than four.** Each is assembled from many contracts, every one of them converted at its own point. So a money figure carries your reporting currency, and the kinds of anchor its components were pinned under — a billing event, a contract effective date, a plan rate; one, two or all three, always given as a list even when the list has one entry. It does not carry a single anchor date or a single billing currency, because it does not have one. That absence is stated rather than filled: never a blank, never a placeholder date, never a `mixed`. The list also never says which contract took which kind — that would put contract-level detail on a company figure, which is the line this object exists on the right side of.

**Neither retention ratio, neither margin index and not pipeline velocity carries a currency of its own.** The ratios are ratios of figures already in your reporting currency, and the index, the band and the velocity score are scores.

## Availability

✓ available by default · ⊕ available after an opt-in that states who becomes able to see the value · — not available.

**Nothing on this object is served on any door today, and that is true of every one of the fourteen rather than of some of them.** The names, types, ceilings and marks below are fixed and will not change when the doors open. Rather than repeat that on every row, it is stated once here: read the table as what each value *will* reach, not as what is callable now.

| Value | Read interface | MCP tools | Events | CRM property | CRM name | Audience ceiling |
| - | - | - | - | - | - | - |
| `as_of` | ✓ | ✓ | in every event | ✓ | `beacon_as_of` | `operational` |
| `computed_at` | ✓ | ✓ | in every event | ✓ | `beacon_computed_at` | `operational` |
| `mrr` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_mrr` | `operational` |
| `arr` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_arr` | `operational` |
| `new_mrr` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_new_mrr` | `operational` |
| `expansion_mrr` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_expansion_mrr` | `operational` |
| `contraction_mrr` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_contraction_mrr` | `operational` |
| `churn_mrr` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_churn_mrr` | `operational` |
| `reactivation_mrr` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_reactivation_mrr` | `operational` |
| `gross_revenue_retention` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_gross_revenue_retention` | `operational` |
| `net_revenue_retention` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_net_revenue_retention` | `operational` |
| `logo_churn` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_logo_churn` | `operational` |
| `contribution_margin` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_contribution_margin` | `leadership-only` |
| `margin_contribution_index` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_margin_contribution_index` | `leadership-only` |
| `margin_contribution_band` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_margin_contribution_band` | `leadership-only` |
| `pipeline_velocity` | ⊕ | ⊕ | ⊕ | ⊕ | `beacon_pipeline_velocity` | `operational` |

**Every figure on this object takes an opt-in on every door, and the two timestamps do not.** That is not a rule about money: the index, the band and the velocity score carry no money and take the same opt-in as the revenue figures. It follows from how sensitive the record behind each value is — a company-level figure reveals the position of the whole business — and every one of the fourteen sits at the same level on that test. `as_of` and `computed_at` say when, not what, and travel freely.

**Where the choice is made.** None of the fourteen is open by default on any door. The choice happens when a reader grant that reaches a value is issued or widened, when you subscribe to events, or when you turn a CRM property on. Whoever makes it is shown who becomes able to see the value, and their yes is recorded — holding a grant is no longer enough on its own.

**The events door is listed and not yet served.** A value marked on it has a named event — `period.mrr.changed`, `period.net_revenue_retention.changed` — sent once per recalculation when the published value differs from the last one, carrying the new value, the previous value and both timestamps. Nothing sends an event today and there is nothing to subscribe to yet. `as_of` and `computed_at` have no event of their own; they travel inside every event.

**What accompanies a money figure on your CRM records is not settled.** A CRM property holds one value, and the figures above need their reporting currency and their anchor kinds beside them to be read correctly. The mark says the door is open behind an opt-in; it does not say the rendering is finished. That is being worked out and will be stated here when it is.

**The three margin figures sit at `leadership-only`, and the eleven others do not.** That is derived rather than assumed: it comes from reading who, in Beacon's own margin specification, reads the live consolidated figure at full scope — and every such role is at leadership level. The revenue figures were put through the same check against Beacon's revenue framework, which carries no read restriction of any kind on recurring revenue, its movements or the retention ratios, so they sit at `operational`. Pipeline velocity was checked against Beacon's velocity specification, where the widest reader of the score is sales leadership, and sits at `operational` too.

**A ceiling is not a block, and it is not a rule about your own staff.** It governs where a value may travel and which grant may cover it — not who inside your company may look at a number your company owns. A ceiling and an opt-in are two different things: the ceiling decides which grants may cover a value at all; the opt-in decides that a recorded choice is made before any door opens.

Enumerated values are lowercase with underscores — `additive`, `in_band`, `marginal` — on every door.

## Who already reads the records behind these figures

This matters to a finance reader and is rarely stated, so it is stated here.

**The revenue figures on this object are read out of the same locked period records your external accountants work from** — the closing recurring-revenue table, the movement totals and the reconciliation report — on which an external auditor holds a standing, regulated read. That is a fact about those records, not about this interface: the audit read is not a Beacon door, and nothing Beacon publishes widens or narrows it. It is worth knowing because it answers the question a CFO asks first, which is whether the numbers on this page are read from the same records their auditor works from. They are.

**Nothing behind the three margin figures is read by anyone outside your company.** Margin is consolidated inside Beacon from your own cost and revenue inputs, and no party outside your organisation holds a standing read on any of it.

**Nothing behind pipeline velocity is read by anyone outside your company either.** It is scored from your own CRM's deal records, and no outside party holds a read on them through Beacon.

## Freshness

| Value | Recomputed | Sealed |
| - | - | - |
| `mrr` · `arr` · the five movements · `gross_revenue_retention` · `logo_churn` | Not declared — see below | Inside the locked record for the period they belong to |
| `net_revenue_retention` | Within 60 minutes of a change at source | Monthly, after the period's lock |
| `contribution_margin` · `margin_contribution_index` | Monthly, at the margin consolidation cycle on the fifth business day | The month-end view is fixed at that point and re-opened at the next monthly cycle; the quarter-end view is final and does not re-open |
| `margin_contribution_band` | On the same monthly cycle, **and at any time your growth posture changes** | Fixed with the index it bands; the reset that follows a posture change is fixed at the moment of the change |
| `pipeline_velocity` | Each recalculation cycle — a daily consolidation — over the company's open deals at that cycle. The pace it is scored against is rebuilt quarterly and does not move between rebuilds | **Which cycle's score a period publishes is not yet declared** — see below |

**How often the revenue figures refresh before a period closes is not declared, and that is stated rather than filled in.** The rule Beacon follows is that a figure's refresh cadence is the cadence of the lock that freezes it, read at the part of Beacon that owns the figure. Recurring revenue, its movements and the two retention ratios live in Beacon's shared core, which no single part owns — so for most of them there is nothing yet to read a cadence from. The row above says so rather than carrying a plausible number. It will be filled in, not quietly.

**Pipeline velocity is scored once per cycle, and a period holds many cycles.** Which cycle's score stands for the period — the last one inside it, or another rule — is not yet declared, and this page says so rather than choosing one. It will be stated here when it is decided, and the score you read before then should be read with its own `computed_at`.

**The band has no fixed refresh interval, because one of the two things that moves it is an event rather than a date.** A change in your growth posture resets the band envelope the moment it is executed. Between such changes the band moves on the monthly cycle with the index. There is no freshness floor for the posture reset and none is implied by the monthly one.

**An entity whose consolidated margin differs from its source figure by more than 2% is held out of the month's locked view until the difference is resolved**, rather than locked in with the discrepancy inside it. So a margin figure that is present is a reconciled one.

**Beacon's margin calculation does not retune itself.** Its inputs are weighted on your trailing twelve months of revenue, and the weights and thresholds are recalibrated on a quarterly cycle by people, never between locks and never by the system on its own. That is why every figure on this object is `Measured` rather than `Modelled`: the arithmetic is fixed and written down, and the same inputs return the same figure.

A correction arriving after a period is sealed is recorded as a named adjustment in the current period. A sealed figure is never quietly restated. [Sealed and live figures](/sealed-and-live) covers what a seal fixes; [Period close and corrections](/period-close) covers what happens to a closed period.

## Versioning

The published object is versioned separately from Beacon's internal model. A value is never removed from a published version — it is deprecated, and the removal lands in the next version. A published name is permanent; a rename ships as a redirect.

`pipeline_velocity` is the first value added to this object after its first publication. It is declared here ahead of the [API](/api-reference), which carries it from its next version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.