feat(api): Add settlement mode to v1 api

[mark-vass-konghq]

Add settlement mode to v1 api

Summary by CodeRabbit

• New Features
  • Added a settlement mode for plans and subscriptions with two options: "credit then invoice" (default) and "credit only".
  • Settlement mode can be specified when creating or updating plans and when creating subscriptions, and is visible when reading plan and subscription details.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new exported SettlementMode enum and an optional settlementMode property (defaulting to SettlementMode.CreditThenInvoice) to the Plan and Subscription models, with visibility annotations and a summary "Settlement mode".

Changes

Cohort / File(s)	Summary
SettlementMode enum & Plan updates api/spec/packages/legacy/src/productcatalog/plan.tsp	Add exported SettlementMode enum (CreditThenInvoice, CreditOnly) and add settlementMode?: SettlementMode = SettlementMode.CreditThenInvoice to Plan with @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update) and @summary("Settlement mode").
Subscription settlementMode api/spec/packages/legacy/src/productcatalog/subscription.tsp	Add settlementMode?: SettlementMode = SettlementMode.CreditThenInvoice to Subscription (visible on Read) and accept optional settlementMode?: SettlementMode on PlanSubscriptionCreate; add @summary("Settlement mode") docs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat(ent): Add settlement mode for subscription and plan schemas #4005 — Adds the same SettlementMode enum and settlement_mode / settlementMode fields to Plan and Subscription schemas (persistence/migration-level changes).
• fix: implement settlement mode in productcatalog #4026 — Wires persistence, defaults, and propagation for the settlementMode field across productcatalog/subscription code.
• chore(api): add create subscription type summaries #3157 — Touched PlanSubscriptionCreate/subscription model docs; related to adding/documenting the settlementMode field.

Suggested reviewers

• tothandras

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding settlement mode functionality to the v1 API across multiple TypeSpec models.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/add-settlement-mode-to-v1-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

api/spec/packages/legacy/src/productcatalog/subscription.tsp (1)

130-135: Nice addition — consider documenting the default here too for consistency

This field has a default in code, but the description doesn’t mention it (unlike the plan field). Adding that one line makes the API docs clearer for users.

✍️ Suggested doc tweak

   /**
    * The settlement mode of the subscription, which determines how the invoice is generated and payments are applied.
+   * When not specified, defaults to `credit_then_invoice`.
    */
   `@visibility`(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
   `@summary`("Settlement mode")
   settlementMode?: PlanSettlementMode = PlanSettlementMode.creditThenInvoiceSettlementMode;

As per coding guidelines **/*.tsp: "The declared API should be accurate, in parity with the actual implementation, and easy to understand for the user."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api/spec/packages/legacy/src/productcatalog/subscription.tsp` around lines
130 - 135, The JSDoc for the subscription property settlementMode omits the
default value; update the comment for settlementMode to explicitly state the
default (PlanSettlementMode.creditThenInvoiceSettlementMode) so the API docs
match the actual implementation and mirror the style used on the plan field;
locate the settlementMode property and add one sentence like "Defaults to
PlanSettlementMode.creditThenInvoiceSettlementMode." to the existing
description.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@api/spec/packages/legacy/src/productcatalog/subscription.tsp`:
- Around line 130-135: The JSDoc for the subscription property settlementMode
omits the default value; update the comment for settlementMode to explicitly
state the default (PlanSettlementMode.creditThenInvoiceSettlementMode) so the
API docs match the actual implementation and mirror the style used on the plan
field; locate the settlementMode property and add one sentence like "Defaults to
PlanSettlementMode.creditThenInvoiceSettlementMode." to the existing
description.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4b9b076e-da79-427c-8b03-4700c19b1de9

📥 Commits

Reviewing files that changed from the base of the PR and between 5ec03c3 and 815be88.

⛔ Files ignored due to path filters (8)

• api/client/go/client.gen.go is excluded by !api/client/**
• api/client/javascript/src/client/schemas.ts is excluded by !api/client/**
• api/client/javascript/src/zod/index.ts is excluded by !api/client/**
• api/client/python/openmeter/_generated/models/__init__.py is excluded by !**/_generated/**, !api/client/**
• api/client/python/openmeter/_generated/models/_enums.py is excluded by !**/_generated/**, !api/client/**
• api/client/python/openmeter/_generated/models/_models.py is excluded by !**/_generated/**, !api/client/**
• api/openapi.cloud.yaml is excluded by !**/openapi.cloud.yaml
• api/openapi.yaml is excluded by !**/openapi.yaml

📒 Files selected for processing (3)

• api/api.gen.go
• api/spec/packages/legacy/src/productcatalog/plan.tsp
• api/spec/packages/legacy/src/productcatalog/subscription.tsp

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

api/spec/packages/legacy/src/productcatalog/subscription.tsp (1)

463-467: Add summary + enum behavior docs for PlanSubscriptionCreate.settlementMode.

This works functionally, but the docs here are much thinner than the read model. Adding @summary and short value semantics will make generated OpenAPI/SDK docs clearer for users.

Suggested change

   /**
    * The settlement mode of the subscription.
+   * - credit_then_invoice: credits are applied first, then remaining balance is invoiced.
+   * - credit_only: only credits are generated and applied, no invoices are created.
    */
+  `@summary`("Settlement mode")
   settlementMode?: SettlementMode;

As per coding guidelines, "The declared API should be accurate, in parity with the actual implementation, and easy to understand for the user."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api/spec/packages/legacy/src/productcatalog/subscription.tsp` around lines
463 - 467, Add a short `@summary` and enum-value semantics to the
PlanSubscriptionCreate.settlementMode property so the OpenAPI/SDK docs match the
read model; update the JSDoc for the settlementMode field (symbol:
PlanSubscriptionCreate.settlementMode) to include a one-line `@summary` and a
brief description of each SettlementMode enum value (what each option
means/behaves like at runtime), keeping wording concise and consistent with the
read model semantics.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@api/spec/packages/legacy/src/productcatalog/subscription.tsp`:
- Around line 130-138: Subscription.read model currently declares settlementMode
as optional which makes generated clients treat it as nullable; update the
declaration for the Subscription type so settlementMode is required (remove the
optional marker) while keeping its type SettlementMode and default value
SettlementMode.CreditThenInvoice, i.e., change the field declaration for
settlementMode in this file (the symbol to edit is settlementMode on the
Subscription read model, referencing the SettlementMode enum) so the read model
always exposes a non-null value.

---

Nitpick comments:
In `@api/spec/packages/legacy/src/productcatalog/subscription.tsp`:
- Around line 463-467: Add a short `@summary` and enum-value semantics to the
PlanSubscriptionCreate.settlementMode property so the OpenAPI/SDK docs match the
read model; update the JSDoc for the settlementMode field (symbol:
PlanSubscriptionCreate.settlementMode) to include a one-line `@summary` and a
brief description of each SettlementMode enum value (what each option
means/behaves like at runtime), keeping wording concise and consistent with the
read model semantics.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5293b0f3-0995-4e6c-9de9-47af0781bb77

📥 Commits

Reviewing files that changed from the base of the PR and between c078160 and 12debf9.

⛔ Files ignored due to path filters (8)

• api/client/go/client.gen.go is excluded by !api/client/**
• api/client/javascript/src/client/schemas.ts is excluded by !api/client/**
• api/client/javascript/src/zod/index.ts is excluded by !api/client/**
• api/client/python/openmeter/_generated/models/__init__.py is excluded by !**/_generated/**, !api/client/**
• api/client/python/openmeter/_generated/models/_enums.py is excluded by !**/_generated/**, !api/client/**
• api/client/python/openmeter/_generated/models/_models.py is excluded by !**/_generated/**, !api/client/**
• api/openapi.cloud.yaml is excluded by !**/openapi.cloud.yaml
• api/openapi.yaml is excluded by !**/openapi.yaml

📒 Files selected for processing (3)

• api/api.gen.go
• api/spec/packages/legacy/src/productcatalog/plan.tsp
• api/spec/packages/legacy/src/productcatalog/subscription.tsp

🚧 Files skipped from review as they are similar to previous changes (1)

• api/spec/packages/legacy/src/productcatalog/plan.tsp