Schema Reference

Available on request — The Autumn Lakehouse is provisioned per customer. Contact us at hey@useautumn.com to get access.

Every object is delivered as a table named v2_3_<object>. Tables are grouped below by lane.

Type legend

Types below are engine-neutral. How each engine surfaces them:

Logical type	ClickHouse
`string`	`Nullable(String)`
`number`	`Nullable(Decimal(38, …))`
`number (epoch ms)`	`Nullable(Decimal(38, …))`
`boolean`	`Nullable(Bool)`
`json (string)`	`Nullable(String)`
`json[] (string)`	`Array(Nullable(String))`
`string[]`	`Array(Nullable(String))`
`timestamp`	`Nullable(DateTime64)`

Timestamps are epoch-milliseconds (number (epoch ms)), not native datetimes — convert before use. See Querying → Timestamps. The one exception is v2_3_events.timestamp, which is a real timestamp.
JSON columns are stored as strings — parse them with JSONExtract* (ClickHouse).

Keys

⭐ marks the stable, immutable key for a table — join and filter on this.
🔗 marks a stable foreign key (internal_customer_id, internal_feature_id, internal_product_id, internal_entity_id, internal_reward_id) — join to the matching internal_id.
External ids (customer_id, plan_id, feature_id, entity_id, id, …) are mutable — convenient for display, but don’t rely on them as stable keys. See Querying → Use internal ids.
org_id is your tenant id (constant across your tables); env is sandbox or production.

Catalog

Your pricing model: features, plans, plan items, rewards, and referral programs.

v2_3_features — feature catalog

Column	Type	Notes
`internal_id`	string	⭐ stable key
`feature_id`	string	external id (e.g. `AI_CREDITS`), mutable
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`name`	string
`type`	string	feature type
`display`	json (string)	display config
`config`	json (string)	metered / credit-system config

v2_3_plans — plan headers with base pricing

Column	Type	Notes
`internal_id`	string	⭐ stable key — one row per plan version
`plan_id`	string	external id, mutable, shared across versions
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`name`	string
`description`	string
`group`	string
`version`	number	plan version number
`add_on`	boolean
`auto_enable`	boolean
`archived`	boolean
`base_variant_id`	string
`created_at`	number (epoch ms)
`config`	json (string)
`price_amount`	number	base recurring price
`price_interval`	string	billing interval
`price_interval_count`	number
`trial_duration_length`	number
`trial_duration_type`	string
`trial_card_required`	boolean
`trial_on_end`	string

v2_3_plan_items — entitlements + linked prices

Column	Type	Notes
`internal_id`	string	⭐ stable key
`plan_id`	string	external plan id
`internal_product_id`	string	🔗 → `v2_3_plans.internal_id`
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`feature_id`	string	external feature id
`internal_feature_id`	string	🔗 → `v2_3_features.internal_id`
`included`	number	allowance (`0` if unlimited)
`unlimited`	boolean
`reset_interval`	string	null for boolean / continuous-use
`reset_interval_count`	number	null if count is 1
`has_price`	boolean
`price_amount`	number	single-tier only
`price_tiers`	json (string)	multi-tier array (null if single/fixed)
`price_tier_behavior`	string	graduated / stairstep
`price_interval`	string
`price_interval_count`	number
`price_billing_units`	number
`price_billing_method`	string	prepaid / usage_based
`price_max_purchase`	number	usage_limit − included
`rollover_max`	number
`rollover_max_percentage`	number
`rollover_expiry_duration_type`	string
`rollover_expiry_duration_length`	number

v2_3_rewards — discounts, free products, promos

Column	Type	Notes
`internal_id`	string	⭐ stable key
`id`	string	external id, mutable
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`name`	string
`type`	string	percentage_discount / fixed_discount / free_product
`created_at`	number (epoch ms)
`discount_value`	number
`discount_duration_type`	string
`discount_duration_value`	number
`discount_apply_to_all`	boolean
`discount_price_ids`	json (string)	string array (null for free-product)
`free_product_id`	string	plan id (null for discount)
`free_product_duration_type`	string
`free_product_duration_value`	number
`promo_codes`	json (string)	array of `{code, global_max_redemption}`

v2_3_referral_programs — referral configuration

Column	Type	Notes
`internal_id`	string	⭐ stable key
`id`	string	external id, mutable
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`created_at`	number (epoch ms)
`reward_id`	string	external reward id
`internal_reward_id`	string	🔗 → `v2_3_rewards.internal_id`
`trigger_event`	string	customer_creation / checkout
`received_by`	string	referrer / all
`product_ids`	string[]	external plan ids
`exclude_trial`	boolean
`unlimited_redemptions`	boolean
`max_redemptions`	number

Subjects

Who your plans apply to: customers and entities (sub-customers).

v2_3_customers — customer master record

Column	Type	Notes
`internal_id`	string	⭐ stable key
`customer_id`	string	external id, mutable (may be null)
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`name`	string
`email`	string
`created_at`	number (epoch ms)
`fingerprint`	string
`stripe_id`	string	Stripe customer id
`metadata`	json (string)
`send_email_receipts`	boolean
`billing_controls`	json (string)	auto_topups, spend_limits, usage_alerts, overage_allowed
`config`	json (string)
`processors`	json (string)	stripe / vercel / revenuecat links

v2_3_entities — sub-customers scoped to a feature

Column	Type	Notes
`internal_id`	string	⭐ stable key
`id`	string	external id, mutable
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`customer_id`	string	parent customer external id
`internal_customer_id`	string	🔗 → `v2_3_customers.internal_id`
`feature_id`	string	entity feature scope (external)
`name`	string
`created_at`	number (epoch ms)
`deleted`	boolean
`billing_controls`	json (string)	spend_limits, usage_alerts, overage_allowed

States

Active customer–product relationships: recurring subscriptions and one-off purchases.

v2_3_subscriptions — recurring customer products

Column	Type	Notes
`internal_id`	string	⭐ stable key
`id`	string	external id, mutable
`customer_id`	string	external customer id
`internal_customer_id`	string	🔗 → `v2_3_customers.internal_id`
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`plan_id`	string	external plan id
`internal_product_id`	string	🔗 → `v2_3_plans.internal_id`
`add_on`	boolean
`auto_enable`	boolean
`status`	string	active / scheduled
`past_due`	boolean
`canceled_at`	number (epoch ms)	null if not canceled
`expires_at`	number (epoch ms)	null if no expiry
`trial_ends_at`	number (epoch ms)	null if no trial
`started_at`	number (epoch ms)
`quantity`	number
`current_period_start`	number (epoch ms)	null if none
`current_period_end`	number (epoch ms)	null if none
`entity_id`	string	external entity id (null = customer-scoped)
`internal_entity_id`	string	🔗 → `v2_3_entities.internal_id` (null = customer-scoped)

v2_3_purchases — one-off purchases

Column	Type	Notes
`internal_id`	string	⭐ stable key
`id`	string	external id, mutable
`customer_id`	string	external customer id
`internal_customer_id`	string	🔗 → `v2_3_customers.internal_id`
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`plan_id`	string	external plan id
`internal_product_id`	string	🔗 → `v2_3_plans.internal_id`
`expires_at`	number (epoch ms)	null if no expiry
`started_at`	number (epoch ms)
`quantity`	number
`entity_id`	string	external entity id (null = customer-scoped)
`internal_entity_id`	string	🔗 → `v2_3_entities.internal_id` (null = customer-scoped)

Balances

Feature balances, their per-entitlement breakdowns, and boolean feature flags.

Balances, breakdowns, and flags carry both pooled (customer-level) rows — where entity_id is null — and per-entity rows. Filter on entity_id IS NULL for customer-level totals to avoid double counting. See Querying → Pooled vs per-entity.

v2_3_balances — aggregated balance per customer × feature × entity

Column	Type	Notes
`internal_customer_id`	string	⭐🔗 part of key → `v2_3_customers.internal_id`
`internal_feature_id`	string	⭐🔗 part of key → `v2_3_features.internal_id`
`entity_id`	string	⭐ part of key (null = pooled)
`customer_id`	string	external customer id
`feature_id`	string	external feature id
`internal_entity_id`	string	🔗 → `v2_3_entities.internal_id` (null = pooled)
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`unlimited`	boolean
`granted`	number	total granted (incl. rollover)
`remaining`	number	total remaining (incl. rollover)
`usage`	number	total usage
`overage_allowed`	boolean
`max_purchase`	number	null if unbounded
`reset_interval`	string	single interval or `multiple`
`reset_interval_count`	number	null if `multiple` or count 1
`reset_resets_at`	number (epoch ms)	earliest reset across entitlements
`next_reset_at`	number (epoch ms)	earliest next reset

v2_3_breakdowns — per-entitlement balance detail

Column	Type	Notes
`internal_id`	string	⭐ part of key (customer_entitlement id)
`entity_id`	string	⭐ part of key (null = pooled)
`id`	string	external id, mutable
`customer_id`	string	external customer id
`internal_customer_id`	string	🔗 → `v2_3_customers.internal_id`
`internal_entity_id`	string	🔗 → `v2_3_entities.internal_id` (null = pooled)
`feature_id`	string	external feature id
`internal_feature_id`	string	🔗 → `v2_3_features.internal_id`
`plan_id`	string	external plan id
`internal_product_id`	string	🔗 → `v2_3_plans.internal_id`
`included_grant`	number	allowance grant
`prepaid_grant`	number	prepaid grant
`remaining`	number
`usage`	number
`unlimited`	boolean
`reset_interval`	string	null for continuous-use
`reset_interval_count`	number	null if count 1
`reset_resets_at`	number (epoch ms)	next reset
`price_amount`	number	single-tier only
`price_billing_method`	string	prepaid / usage_based
`price_billing_units`	number	default 1
`price_max_purchase`	number
`price_tier_behavior`	string	graduated / stairstep (multi-tier)
`price_tiers`	json (string)	multi-tier array
`expires_at`	number (epoch ms)	null if no expiry
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`

v2_3_flags — boolean feature flags

Column	Type	Notes
`internal_id`	string	⭐ part of key
`entity_id`	string	⭐ part of key (null = pooled)
`id`	string	external id, mutable
`customer_id`	string	external customer id
`internal_customer_id`	string	🔗 → `v2_3_customers.internal_id`
`internal_entity_id`	string	🔗 → `v2_3_entities.internal_id` (null = pooled)
`feature_id`	string	external feature id
`internal_feature_id`	string	🔗 → `v2_3_features.internal_id`
`plan_id`	string	external plan id
`internal_product_id`	string	🔗 → `v2_3_plans.internal_id`
`expires_at`	number (epoch ms)	null if no expiry
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`

Invoices

Invoices and their line items.

v2_3_invoices — invoice master record

Column	Type	Notes
`id`	string	⭐ stable key (invoice id)
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`customer_id`	string	external customer id
`internal_customer_id`	string	🔗 → `v2_3_customers.internal_id`
`entity_id`	string	external entity id (null = customer-scoped)
`internal_entity_id`	string	🔗 → `v2_3_entities.internal_id` (null = customer-scoped)
`plan_ids`	string[]	external plan ids
`internal_product_ids`	string[]	🔗 → `v2_3_plans.internal_id`
`stripe_id`	string	Stripe invoice id
`processor_type`	string	stripe / …
`status`	string	paid / open / void / draft
`total`	number	invoice total
`amount_paid`	number
`refunded_amount`	number
`currency`	string	ISO 4217 code
`created_at`	number (epoch ms)
`hosted_invoice_url`	string	raw Stripe URL
`discounts`	json[] (string)	array of discount objects

v2_3_invoice_line_items — invoice line detail

Column	Type	Notes
`id`	string	⭐ stable key (line item id)
`org_id`	string	your tenant id
`env`	string	`sandbox` / `production`
`invoice_id`	string	🔗 → `v2_3_invoices.id`
`customer_id`	string	external customer id
`description`	string
`period_start`	number (epoch ms)
`period_end`	number (epoch ms)
`feature_id`	string	external feature id (null for non-feature lines)
`internal_feature_id`	string	🔗 → `v2_3_features.internal_id`
`feature_name`	string	resolved feature name
`plan_id`	string	external plan id
`internal_product_id`	string	🔗 → `v2_3_plans.internal_id`
`amount`	number	pre-discount
`amount_after_discounts`	number
`currency`	string	ISO 4217 code
`direction`	string	charge / refund
`billing_timing`	string	in_advance / in_arrear
`prorated`	boolean
`discounts`	json[] (string)	array of discount objects

Events

The append-only usage event log. This is the highest-volume table and is append-only (no updates).

v2_3_events — usage event log

Column	Type	Notes
`id`	string	⭐ stable key (event id)
`org_id`	string	your tenant id
`org_slug`	string
`internal_customer_id`	string	🔗 → `v2_3_customers.internal_id`
`env`	string	`sandbox` / `production`
`created_at`	number (epoch ms)	when Autumn recorded the event
`timestamp`	timestamp	event time — a real timestamp, use directly
`event_name`	string
`idempotency_key`	string
`value`	number
`entity_id`	string	external entity id (null = customer-scoped)
`internal_entity_id`	string	🔗 → `v2_3_entities.internal_id`
`internal_product_id`	string	🔗 → `v2_3_plans.internal_id`
`customer_id`	string	external customer id
`properties`	json (string)	event properties (e.g. `subtype`, `model`)
`deductions`	json (string)	per-feature deductions for this event

Unlike every other table, v2_3_events.timestamp is a native timestamp — no epoch-ms conversion needed. created_at is still epoch-ms.

​Type legend

​Keys

​Catalog

​Subjects

​States

​Balances

​Invoices

​Events

Type legend

Keys

Catalog

Subjects

States

Balances

Invoices

Events