Migrating from v2.3

​

Why move

• Balances no longer count old plans. v2_3_balances added up every grant a customer ever had, including ended plans and past cycles, so you had to filter them out. v2_6_balances contains only what the API counts.
• Rollovers are included. v2_3_balances left rollovers out. In v2.6 they are part of the balance and listed in v2_6_rollovers.
• Subscriptions keep their real status. v2_3_subscriptions.status showed every non-active plan as scheduled. v2_6_subscriptions.status is the real status: expired, trialing, paused and so on.

​

What changes in your queries

1. Table prefix. v2_3_ becomes v2_6_. events is unchanged.
2. Product is now plan. Every internal_product_id becomes internal_plan_id, and internal_customer_product_id becomes customer_plan_id. (events.internal_product_id keeps its name.)
3. Keys are named after their table. v2.3’s generic internal_id becomes internal_customer_id, internal_plan_id, customer_plan_id and so on, and references use the same name, so a join reads s.internal_plan_id = p.internal_plan_id.
4. Balances have one row per view. Add scope = 'customer' to customer-level balance queries. See below.
5. Drop your balance filters. The active-plan, current-cycle and expiry filters you applied to v2.3 balances are already applied.
6. Arrays are JSON text. v2.3 had a few array columns (plan_ids, product_ids, internal_product_ids). In v2.6 every array is a JSON string; see Querying → JSON columns.

​

Tables

​

Renamed keys

​

Balances now have one row per view

​

Before and after

WITH live AS (
  SELECT bd.*
  FROM <namespace>.v2_3_breakdowns bd
  JOIN <namespace>.v2_3_subscriptions s ON s.internal_id = bd.internal_customer_product_id
  WHERE bd.env = 'live' AND bd.customer_id = 'cus_123' AND bd.feature_id = 'messages'
    AND s.status = 'active'
    AND (bd.expires_at IS NULL OR bd.expires_at > <now in epoch ms>)
    -- ...and pick the current reset cycle per plan
),
ro AS (
  SELECT internal_breakdown_id, sum(balance) AS rollover
  FROM <namespace>.v2_3_rollovers
  WHERE expires_at IS NULL OR expires_at > <now in epoch ms>
  GROUP BY internal_breakdown_id
)
SELECT sum(live.remaining) + coalesce(sum(ro.rollover), 0) AS remaining
FROM live LEFT JOIN ro ON ro.internal_breakdown_id = live.internal_id;

SELECT b.granted, b.remaining, b.usage
FROM <namespace>.v2_6_balances b
JOIN <namespace>.v2_6_customers c
  ON c.org_id = b.org_id AND c.env = b.env AND c.internal_customer_id = b.internal_customer_id
WHERE b.env = 'live' AND c.customer_id = 'cus_123'
  AND b.feature_id = 'messages' AND b.scope = 'customer';

​

Checklist

1. Run your v2.3 queries and their v2.6 versions side by side for a few customers and compare.
2. Change the table prefix, then rename keys using the table above.
3. Replace internal_product_id and internal_customer_product_id with internal_plan_id and customer_plan_id.
4. In balance queries, delete your active/current-cycle/rollover logic and add a scope filter.
5. Where you filtered status = 'scheduled' to mean “not active”, use the real statuses.
6. Parse array columns as JSON.
7. Tell us when you’ve moved, so we can retire your v2.3 tables.