v2_6_<object> and grouped below by lane. The event log is the exception: it is events, shared with v2.3. Column types are listed in Querying → Types.
Keys
- Every table has
org_id(your Autumn organization) andenv(liveorsandbox, neverproduction). Match both in every join and filterenvin every query. - Join on
internal_*ids,customer_plan_idandbalance_id. Your own ids (customer_id,plan_id,feature_id,entity_id) can be renamed, can be null, are shared by every version of a plan, or are unique only within one customer. - The Key line on each table is its primary key.
Catalog
These four tables describe your pricing, not your customers: the features you meter, the plans you sell and what each plan includes. They change only when you edit your catalog. A plan with three features has one row inv2_6_plans and three rows in v2_6_plan_items. Every version of a plan is its own row, so join on internal_plan_id to get the exact version a customer is on, and group by plan_id when you want all versions together.
v2_6_features — feature catalog
v2_6_features — feature catalog
Every feature you have defined in Autumn: the things you meter or gate, such as
messages, seats or sso. One row is one feature, the same object POST /v1/features.get returns.One row per: feature. Key: org_id, env, internal_feature_id. API object: Feature.v2_6_plans — plan versions, with base price and trial
v2_6_plans — plan versions, with base price and trial
Every plan in your catalog, one row per version. If you changed Pro after customers subscribed, Pro v1 and Pro v2 are two rows with the same
plan_id and different internal_plan_ids. The plan’s base price and free trial are columns on the row.One row per: plan version. Key: org_id, env, internal_plan_id. API object: Plan.v2_6_plan_items — what each plan version includes
v2_6_plan_items — what each plan version includes
What a plan grants, one row per feature on the plan. “Pro includes 1,000 messages a month, then $0.02 per message” is one row. The item’s price, reset and rollover settings are columns on the row.One row per: item on a plan version. Key:
org_id, env, internal_plan_item_id. API object: Plan item (plan.items[]).A row with
is_custom = true belongs to one customer’s custom plan, not to your catalog. Filter is_custom = false when you want your published pricing only. See Custom plans.v2_6_plan_licenses — seats a plan provides
v2_6_plan_licenses — seats a plan provides
Which plans come with licenses (seats) of another plan. “Team includes 5 Member licenses” is one row: Team is the parent plan, Member is the license plan. Customers then assign those seats to their entities. Only your catalog’s links are here, not per-customer changes.One row per: license link in your catalog. Key:
org_id, env, plan_license_id. API object: Plan license (plan.licenses[]).Customers and plans
These tables describe who your customers are and which plans they hold. A customer can have entities (users, workspaces, projects inside the customer), and a plan can be attached to the customer or to one entity.customer_plan_id is the id of one customer’s copy of a plan. internal_plan_id is the plan version in your catalog. Ten customers on Pro v2 have ten different customer_plan_id values and share one internal_plan_id. Balances, flags and invoices point at customer_plan_id when they need the customer’s own subscription (its status, its period), and at internal_plan_id when they need the plan.
v2_6_customers — customer record
v2_6_customers — customer record
Your customers, one row each, with the fields
POST /v1/customers.get returns at the top level. Their plans, balances and invoices are in their own tables.One row per: customer. Key: org_id, env, internal_customer_id. API object: Customer.v2_6_entities — users, workspaces and other sub-customers
v2_6_entities — users, workspaces and other sub-customers
Entities are things inside a customer that get their own plans or balances: a user, a workspace, a project. Each one is counted against a feature (often
seats). Deleted entities are left out.One row per: entity. Key: org_id, env, internal_entity_id. API object: Entity.v2_6_subscriptions — recurring plans a customer holds
v2_6_subscriptions — recurring plans a customer holds
Every recurring plan a customer has or had: one row each time a plan was attached to a customer or to one of their entities. This is
customer.subscriptions[], but with every status, including ended ones, so you can analyse history.One row per: recurring plan attached to a customer, any status. Key: org_id, env, customer_plan_id. API object: Subscription (customer.subscriptions[]).The API’s status of a subscription
v2_6_subscriptions.status is the full lifecycle status, so you can see trials, expired plans and paused plans. The API’s subscriptions[] array is narrower: it returns only live plans, and shows past_due as active with past_due = true. To get the list the API returns:
v2_6_purchases — one-off plans a customer holds
v2_6_purchases — one-off plans a customer holds
Every one-off plan a customer bought, such as a credit pack. This is
customer.purchases[], with every status.One row per: one-off plan attached to a customer, any status. Key: org_id, env, customer_plan_id. API object: Purchase (customer.purchases[]).Custom plans
When you change a plan for one customer (more credits, a different price, an extra feature), Autumn gives that customer their own custom version of the plan. The subscription row hasis_custom = true, but internal_plan_id still points at the catalog plan it was based on, whose items are not what this customer gets. The customer’s own items are in v2_6_plan_items with is_custom = true, and v2_6_customer_plan_items says which of them belong to which subscription.
To list what a customer’s plan actually includes, custom or not:
v2_6_purchases. A row with row_type = 'price' and no internal_plan_item_id is the custom plan’s base price.
v2_6_customer_plan_items — items and prices on custom plans
v2_6_customer_plan_items — items and prices on custom plans
Only used by custom plans. When you give one customer their own version of a plan (more credits, a different price), that customer’s items and prices are not in your catalog plan. This table says which items and prices make up each custom subscription or purchase. If you don’t use custom plans, it is empty and you can skip it.One row per: item or price on a custom plan. Key:
org_id, env, customer_plan_item_id. API object: None of its own. It is how you rebuild subscription.plan for a custom plan.v2_6_licenses — seat pools
v2_6_licenses — seat pools
A customer’s license pools: “this customer has 7 Member seats from their Team plan, 4 assigned and 3 free”. Only pools on live plans (active or past due) are included, as in
customer.licenses[].One row per: license pool. Key: org_id, env, customer_license_id. API object: Customer license (customer.licenses[]).A seat is a subscription too: the license plan attached to the entity that holds the seat. Its row in
v2_6_subscriptions has customer_license_id set, and its status, canceled_at and billing period are copied from the plan that provides the seat.Balances
These tables hold whatPOST /v1/customers.get and POST /v1/entities.get return under balances and flags, already computed. Read Working with balances first: it explains the per-view rows and the order grants are used up in, with a worked example.
v2_6_balances — balance per customer, feature and view
v2_6_balances — balance per customer, feature and view
The balance a customer or entity sees for one feature: the
balances object of POST /v1/customers.get or POST /v1/entities.get. There is one row for the customer’s view, and one more for each entity’s view, because an entity also sees its own grants. Filter on scope.One row per: (customer, feature, view). Key: org_id, env, balance_id. API object: Balance (customer.balances{}, entity.balances{}).v2_6_breakdowns — the grants behind a balance
v2_6_breakdowns — the grants behind a balance
Where a balance comes from: one row per grant that makes up a balance, such as “1,000 from Pro this month” and “500 from a credit pack”. This is the balance’s
breakdown[] array, in the same order, and position is the order Autumn uses the grants up.One row per: grant in a balance, per view. Key: org_id, env, balance_id, breakdown_id. API object: Balance breakdown (balance.breakdown[]).v2_6_rollovers — carried-over balance
v2_6_rollovers — carried-over balance
Unused balance carried over from earlier periods that has not expired: the balance’s
rollovers[] array. Autumn uses rollovers up before any grant in v2_6_breakdowns.One row per: unexpired rollover, per view. Key: org_id, env, balance_id, rollover_id. API object: Balance rollover (balance.rollovers[]).v2_6_flags — boolean features
v2_6_flags — boolean features
On/off features a customer or entity has, such as
sso: the flags object of the customer or entity. If several plans grant the same flag, the row is the one the API shows.One row per: (customer, boolean feature, view). Key: org_id, env, flag_id. API object: Flag (customer.flags{}).v2_6_pooled_balance_contributions — what feeds a pooled balance
v2_6_pooled_balance_contributions — what feeds a pooled balance
What feeds a shared pool. With pooling, plans on several entities (say each seat’s 100 credits) add up into one customer-level balance. The pool is one row in
v2_6_breakdowns; this table lists the plans that feed it and how much each adds.One row per: contributor to a pool. Key: org_id, env, contribution_id. API object: Pooled balance contribution (breakdown[].contributions.list[]).Invoices
v2_6_invoices — invoice record
v2_6_invoices — invoice record
Invoices for your customers, from Stripe or RevenueCat.One row per: invoice. Key:
org_id, env, invoice_id. API object: Invoice (POST /v1/invoices.list).v2_6_invoice_line_items — invoice lines
v2_6_invoice_line_items — invoice lines
The lines on each invoice: the base price, usage charges, seats.One row per: invoice line. Key:
org_id, env, line_item_id. API object: Invoice item (invoice.items[]).Rewards and referrals
A reward is either a coupon (a discount) or a feature grant (free balance). A referral program says which reward a referral earns, and each use of a customer’s referral code is a row inv2_6_referrals.
v2_6_coupons — discount rewards
v2_6_coupons — discount rewards
Your discount coupons: percentage off, a fixed amount off, or invoice credits, with their promo codes.One row per: coupon. Key:
org_id, env, internal_reward_id. API object: Coupon.v2_6_feature_grants — free-balance rewards
v2_6_feature_grants — free-balance rewards
Rewards that give free balance instead of a discount, for example “500 bonus messages”.One row per: feature grant. Key:
org_id, env, internal_reward_id. API object: Feature grant.v2_6_referral_programs — referral configuration
v2_6_referral_programs — referral configuration
Your referral programs: which reward a referral earns, who receives it, and when.One row per: referral program. Key:
org_id, env, internal_referral_program_id. API object: Referral program.v2_6_referrals — uses of a referral code
v2_6_referrals — uses of a referral code
Each time someone used a customer’s referral code: who referred whom, under which program, and whether the reward was given.One row per: use of a referral code. Key:
org_id, env, redemption_id. API object: Customer referral (customer.referrals[]).Events
events — usage event log
events — usage event log
Every usage event you sent with
track. It is not versioned: v2.3 and v2.6 read the same table, and it only grows.One row per: event. Key: org_id, env, id. API object: Event.