> ## 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. # Subscription object > The nine values Beacon publishes about each subscription — who holds it, what it is for, when it runs and how often it is billed. The subscription object carries nine values about each subscription, at one row per subscription, and two timestamps that accompany every one of them on every door: `as_of` and `computed_at`. A subscription is the agreement between one customer and one product. It is what recurring revenue is counted per, and what a renewal date hangs on. 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. On the read interface this object is `subscription`. **The collection name is not published yet** — it lands with the [API reference](/api-reference) rather than being fixed here. ## Example payload ```json theme={null} { "object": "subscription", "id": "sub_10442", "as_of": "2026-08-05T06:00:00Z", "computed_at": "2026-08-05T06:11:48Z", "subscription_id": "sub_10442", "account_id": "acct_3391", "product_id": "prod_pro_annual", "product_family": "F1", "active_flag": true, "subscription_start_date": "2025-03-01", "subscription_end_date": null, "renewal_date": "2027-03-01", "billing_interval": "annual" } ``` ## Attributes | Value | Type | Method | What it holds | | - | - | - | - | | `as_of` | Timestamp, UTC | System | The moment the value describes. Present on every response and every property. | | `computed_at` | Timestamp, UTC | System | When Beacon last read or worked the value out. Present on every response and every property. | | `subscription_id` | String | Measured | The identifier for the subscription. Read from your billing system where there is one — **and created by Beacon where there is not**, see below. | | `account_id` | String | Measured | The customer account holding the subscription. | | `product_id` | String | Measured | The product the subscription is for. Links to the [product object](/data-model/product). | | `product_family` | String | Measured | The product's family, carried here so a subscription can be grouped without a second lookup. | | `active_flag` | Boolean | Measured | Whether the subscription is live as at `as_of`. | | `subscription_start_date` | Date | Measured | When the subscription began. | | `subscription_end_date` | Date, or null | Measured | When it ended. Null while it is running. | | `renewal_date` | Date, or null | Measured | The next date the subscription renews on. | | `billing_interval` | String | Recorded | How often **this customer** is billed, where that differs from the product's default. Same values as the [product object's](/data-model/product) billing interval. | ## Where a subscription comes from, and where Beacon has to make one **If you bill through a subscription platform, this object is read.** The platform holds subscriptions as first-class records and Beacon takes them as they are. **If you bill out of your accounting system, there is no subscription record to read** — a ledger holds invoices and items, not agreements. So Beacon creates one for each customer-and-product pairing it sees recurring on your invoices. That is stated plainly because it has two consequences worth knowing before you meet them: * **The identifier is Beacon's, not yours.** It will not match anything in your accounting system, because your accounting system has nothing to match it to. * **`billing_interval` will usually be empty on this path.** Where Beacon created the subscription, the contracted billing cycle was never recorded anywhere for it to read. The [product's declared billing cycle](/data-model/product) carries the answer instead, which is exactly why that value is asked for during setup. A value that is empty because the thing it describes was never recorded is different from a value that is missing. **Beacon does not fill this one in by inference.** ## Two places a billing cycle can live, and why that is deliberate The product's billing cycle says **how the product is normally sold**. This one says **what this customer actually contracted.** Most of the time they are the same and only one of them is populated. When a customer negotiates a different billing cycle — an annual product billed quarterly, say — the difference belongs to the customer, not to the catalogue, and overwriting the catalogue to record it would mis-describe every other customer on that product. **Where both are present and they disagree, Beacon surfaces the disagreement rather than resolving it silently.** ## Availability **Nothing on this object is served on any door today**, and which values will be available on the read interface, in MCP tools, on events and as CRM properties **has not been settled for this object yet.** It is left unstated here rather than guessed at, and it lands with the same act that publishes the collection. **What is settled is the audience ceiling: every value on this object sits at `operational`.** There is no money on this object; the amounts live on the [invoice line](/data-model/invoice-line-item). ## Freshness | Value | Recomputed | Sealed | | - | - | - | | All values except `billing_interval` | On each sync from your billing or accounting system | Inside the locked record of the period they contributed to | | `billing_interval` | When you change it | Inside the locked record of the period it contributed to | **A subscription that ends does not disappear.** It stays readable with `active_flag` false and its end date set, because the periods it contributed to still need it to reproduce. ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.