feat: 🎸 final schema for carry over balances

[SirTenzin]

---

Summary by cubic

Adds carry-over of unused consumable balances on immediate plan upgrades (attach V2) by creating loose entitlements and inserting matching customer entitlements. Supports feature-level filtering and per-entity balances; scheduled switches and non-consumable features are blocked.

• New Features

  • Immediate upgrades convert positive remaining balances into loose entitlements and insert matching customer entitlements (expire at next reset or end of cycle).
  • Supports feature_ids filtering; per-entity features and entity-attached products carry over independently.
  • Scoped to attach API only (AttachParamsV1.carry_over_balances).

• Validation

  • Immediate-only; scheduled switches and downgrades are rejected.
  • Boolean, unlimited, and allocated features are invalid; zero or negative balances are ignored.

^{Written for commit 1bfebfb. Summary will update on new commits.}

Greptile Summary

Added schema definitions for carry over balances feature, enabling balance transfers when customers change plans.

Key Changes:

• API changes: Added carry_over_balances configuration field to BillingParamsBaseV1Schema with enabled flag and optional feature_ids array for feature-level granularity
• API changes: Added insertCustomerEntitlements field to AutumnBillingPlanSchema to support creating customer entitlements during plan operations
• Improvements: Imported CustomerEntitlementSchema to support the new insertCustomerEntitlements field

These schema changes lay the groundwork for implementing balance carryover functionality, allowing customers to retain their feature balances when switching between plans.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Simple schema additions with no logic changes, backward-compatible optional fields, and no implementation code that could cause runtime issues
• No files require special attention

Important Files Changed

Filename	Overview
shared/api/billing/common/billingParamsBase/billingParamsBaseV1.ts	Added carry_over_balances field to enable balance carryover with feature-level granularity
shared/models/billingModels/plan/autumnBillingPlan.ts	Added insertCustomerEntitlements field to support inserting customer entitlements during plan operations

_{Last reviewed commit: 363c183}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
autumn-vite	Ready	Preview, Comment	Mar 2, 2026 4:32pm

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0892d19541

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}