Subscription object

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 rather than being fixed here.

Example payload

{
  "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.
`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 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 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.

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.

Get started

Lifecycles

Finance

Trust

Reference

Subscription object

Example payload

Attributes

Where a subscription comes from, and where Beacon has to make one

Two places a billing cycle can live, and why that is deliberate

Availability

Freshness

Versioning

​Example payload

​Attributes

​Where a subscription comes from, and where Beacon has to make one

​Two places a billing cycle can live, and why that is deliberate

​Availability

​Freshness

​Versioning

Example payload

Attributes

Where a subscription comes from, and where Beacon has to make one

Two places a billing cycle can live, and why that is deliberate

Availability

Freshness

Versioning