feat(api): credits v3 [WIP] by tothandras · Pull Request #3938 · openmeterio/openmeter

tothandras · 2026-03-12T17:26:00Z

No description provided.

coderabbitai · 2026-03-12T17:26:15Z

Important

Review skipped

Ignore keyword(s) in the title.

⛔ Ignored keywords (1)

WIP

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2796d47f-0c45-424e-a518-9879495b426e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/credits-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

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

api/spec/src/v3/customers/credits/credit.tsp

hekike · 2026-03-12T18:36:37Z

api/spec/packages/aip/src/customers/credits/credit.tsp

+
+  /**
+   * The charge that will be used to purchase the credit.
+   * Omit for promotional credit grants.


Add a comment: External charges should be entered to ensure correct revenue recognition.

api/spec/src/v3/customers/credits/credit.tsp

api/spec/packages/aip/src/customers/credits/grant.tsp

api/spec/src/v3/customers/credits/credit.tsp

api/spec/packages/aip/src/customers/credits/grant.tsp

api/spec/src/v3/customers/credits/credit.tsp

api/spec/packages/aip/src/customers/credits/grant.tsp

api/spec/packages/aip/src/customers/credits/credit.tsp

api/spec/src/v3/customers/credits/credit.tsp

api/spec/packages/aip/src/customers/credits/grant.tsp

turip · 2026-03-15T06:42:53Z

api/spec/packages/aip/src/customers/credits/grant.tsp

+     * Defaults to 1.0 (1:1 ratio between credit and charge currency).
+     */
+    @visibility(Lifecycle.Read, Lifecycle.Create)
+    per_unit_cost_basis?: Shared.Numeric = "1.0";


This should be > 0. If 0 then they should use the promotional settlement type.

api/spec/src/v3/customers/credits/credit.tsp

api/spec/packages/aip/src/customers/credits/grant.tsp

api/spec/packages/aip/src/customers/credits/balance.tsp

api/spec/packages/aip/src/customers/credits/grant.tsp

GAlexIHU · 2026-03-17T10:46:07Z

api/spec/packages/aip/src/customers/credits/operations.tsp

+   * Voiding is a forward-looking, irreversible operation. Credits already
+   * consumed by usage remain unaffected — only the remaining balance is
+   * forfeited. The grant transitions to `voided` status and a breakage
+   * ledger entry is recorded for the forfeited amount. Only `pending`
+   * and `active` grants can be voided.


We could change terminology as I think (based on metered entitlements) it was confusing for most ppl, in general I think customers expected

void to be retroactive

cancel to be forward looking

wdyt @hekike @tothandras ?

So void would do correction against already burned usage. Cancel would zero out available amount ?

api/spec/packages/aip/src/customers/credits/balance.tsp

api/spec/packages/aip/src/customers/credits/grant.tsp

api/spec/packages/aip/src/customers/credits/ledger.tsp

api/spec/packages/aip/src/customers/credits/operations.tsp

GAlexIHU · 2026-03-20T17:21:43Z

api/spec/packages/aip/src/customers/credits/balance.tsp

+   */
+  @visibility(Lifecycle.Read)
+  @example("200.00")
+  pending: Shared.Numeric;


This doesn't technically exist in the current accounting structure, we have numbers for receivable values, and we can create a dimension specifically for credit purchases if we want to track that separately but that would include all not yet paid balances which isn't exactly pending

GAlexIHU · 2026-03-20T17:25:16Z

api/spec/packages/aip/src/customers/credits/ledger.tsp

+ * - `adjusted`: Manual or system adjustment.
+ */
+@friendlyName("BillingCreditLedgerEntryType")
+enum CreditLedgerEntryType {


nit: if you intend this for / this is based on the history view we discussed, I'd propose changing the name, (at least for) I'd use this for more export / revrecog usecases where i'd expect this to be an almost 1:1 match with internal representations

That's an interesting point because we said UI should be more simple than ledger but ledger export is an important use-case.

GAlexIHU · 2026-03-20T17:27:45Z

api/spec/packages/aip/src/customers/credits/ledger.tsp

+ */
+@friendlyName("BillingCreditLedgerActorType")
+@summary("Credit ledger actor type")
+enum CreditLedgerActorType {


Q: should we maybe approach it in a way where

System
1.1 SubTypes (like Automation, Payment clearance...)

User
2.1 (Exact user like name, id, stg.... + type like Customer, Admin...)

hekike · 2026-03-20T20:28:54Z

api/spec/packages/aip/src/customers/credits/grant.tsp

+  ...Shared.Resource;
+
+  /**
+   * Funding or settlement method of the grant.


This has nothing to do with the settlement. Comment should be:

Funding method of the grant. e.g. paid in external system

hekike · 2026-03-20T20:34:51Z

api/spec/packages/aip/src/customers/credits/grant.tsp

+  Invoice: "invoice",
+
+  // The grant is funded outside the system
+  ExternalSettlement: "external_settlement",


I'd do:

/** * The funding method describes how the grant is funded or settled. * * - `none`: No funding workflow applies, for example promotional grants * - `invoice`: The grant is funded by an in-system invoice flow * - `external`: The grant is funded outside the system (e.g., wire transfer, external invoice, or manual reconciliation) */ @friendlyName("BillingCreditFundingMethod") @summary("Credit funding method") enum CreditFundingMethod { // No funding workflow applies None: "none", // The grant is funded by an in-system invoice flow Invoice: "invoice", // The grant is funded outside the system External: "external", }

Settlement" does carry a connotation that payment was completed, which is a stronger claim than what you actually know. All you can assert is that OpenMeter isn't managing the funding workflow for this grant.

hekike · 2026-03-20T20:41:26Z

api/spec/packages/aip/src/customers/credits/grant.tsp

+ */
+@friendlyName("BillingCreditAvailabilityPolicy")
+@summary("Credit availability policy")
+enum CreditAvailabilityPolicy {


Consider:

/** * When credits become available for consumption after a purchase. * * - `on_creation`: Credits are available as soon as the grant is created. * - `on_authorization`: Credits are available once the payment is authorized. * - `on_settlement`: Credits are available once the payment is settled. */ @friendlyName("BillingCreditAvailabilityPolicy") @summary("Credit availability policy") enum CreditAvailabilityPolicy { // Credits become eligible when the grant is created OnCreation: "on_creation", // Credits become eligible when payment is authorized OnAuthorization: "on_authorization", // Credits become eligible when payment is settled OnSettlement: "on_settlement", }

hekike · 2026-03-20T20:59:44Z

api/spec/packages/aip/src/customers/credits/grant.tsp

+   * Present when a payment or settlement workflow applies to the grant.
+   */
+  @visibility(Lifecycle.Read, Lifecycle.Create)
+  payment?: {


I find it confusing to have both purchase and payment. Move these under purchase?

hekike · 2026-03-20T21:00:57Z

api/spec/packages/aip/src/customers/credits/grant.tsp

+  @visibility(Lifecycle.Create, Lifecycle.Read)
+  @minValue(1)
+  @maxValue(1000)
+  priority: int16 = 10;


is max value aligned with ledger DB schema? cc @GAlexIHU

hekike · 2026-03-20T21:02:26Z

api/spec/packages/aip/src/customers/credits/ledger.tsp

+ * - `adjusted`: Manual or system adjustment.
+ */
+@friendlyName("BillingCreditLedgerEntryType")
+enum CreditLedgerEntryType {


That's an interesting point because we said UI should be more simple than ledger but ledger export is an important use-case.

hekike · 2026-03-20T21:03:31Z

api/spec/packages/aip/src/customers/credits/ledger.tsp

+@friendlyName("BillingCreditLedgerEntry")
+@summary("Credit ledger entry")
+model CreditLedgerEntry {
+  ...OmitProperties<Shared.Resource, "updated_at" | "deleted_at">;


Nit: add comment:

// Ledger entries are immutable

hekike · 2026-03-20T21:04:56Z

api/spec/packages/aip/src/customers/credits/operations.tsp

+   * Voiding is a forward-looking, irreversible operation. Credits already
+   * consumed by usage remain unaffected — only the remaining balance is
+   * forfeited. The grant transitions to `voided` status and a breakage
+   * ledger entry is recorded for the forfeited amount. Only `pending`
+   * and `active` grants can be voided.


So void would do correction against already burned usage. Cancel would zero out available amount ?

hekike · 2026-03-20T21:05:49Z

api/spec/packages/aip/src/customers/credits/operations.tsp

+ * External settlement of a credit grant.
+ */
+@friendlyName("UpdateCreditGrantExternalPaymentSettlementRequest")
+model CreditGrantExternalPaymentSettlement {


Shouldn't naming say it's a payload/body/create? Feels weird it's not tied to an operation

hekike reviewed Mar 12, 2026

View reviewed changes

turip reviewed Mar 15, 2026

View reviewed changes

api/spec/packages/aip/src/customers/credits/grant.tsp Show resolved Hide resolved

tothandras force-pushed the feat/credits-api branch from 64d3209 to 9453240 Compare March 16, 2026 09:47

tothandras temporarily deployed to dev March 16, 2026 09:47 — with GitHub Actions Inactive

tothandras force-pushed the feat/credits-api branch from 9453240 to 3a0aec3 Compare March 17, 2026 10:17

tothandras temporarily deployed to dev March 17, 2026 10:17 — with GitHub Actions Inactive

GAlexIHU reviewed Mar 17, 2026

View reviewed changes

tothandras force-pushed the feat/credits-api branch from 3a0aec3 to cd0d6b3 Compare March 19, 2026 21:48

tothandras temporarily deployed to dev March 19, 2026 21:48 — with GitHub Actions Inactive

hekike reviewed Mar 19, 2026

View reviewed changes

tothandras temporarily deployed to dev March 20, 2026 12:29 — with GitHub Actions Inactive

tothandras force-pushed the feat/credits-api branch from 41daf25 to 11014fc Compare March 20, 2026 13:40

tothandras temporarily deployed to dev March 20, 2026 13:40 — with GitHub Actions Inactive

tothandras force-pushed the feat/credits-api branch from 11014fc to 74cb027 Compare March 20, 2026 15:06

tothandras temporarily deployed to dev March 20, 2026 15:06 — with GitHub Actions Inactive

GAlexIHU reviewed Mar 20, 2026

View reviewed changes

hekike reviewed Mar 20, 2026

View reviewed changes

feat(api): credits v3

5a974fe

tothandras force-pushed the feat/credits-api branch from 74cb027 to 5a974fe Compare March 21, 2026 03:08

tothandras temporarily deployed to dev March 21, 2026 03:08 — with GitHub Actions Inactive

Conversation

tothandras commented Mar 12, 2026

Uh oh!

coderabbitai bot commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

coderabbitai bot commented Mar 12, 2026 •

edited

Loading