Fix/settlement mode api (#4470)

Co-authored-by: Andras Toth <4157749+tothandras@users.noreply.github.com>
Co-authored-by: Robert Boros <robert.boros@konghq.com>

Author: 3 people

api/api.gen.go

@@ -9891,6 +9891,8 @@ export interface components {
        * @example 2023-01-01T01:01:01.001Z
        */
       billingAnchor?: Date
+      /** @description The settlement mode of the subscription. */
+      settlementMode?: components['schemas']['BillingSettlementMode']
     }
     /**
      * Create from plan
@@ -9912,6 +9914,8 @@ export interface components {
       name?: string
       /** @description Description for the Subscription. */
       description?: string
+      /** @description The settlement mode of the subscription. */
+      settlementMode?: components['schemas']['BillingSettlementMode']
       /**
        * @description Timing configuration for the change, when the change should take effect.
        *     The default is immediate.
@@ -9931,8 +9935,6 @@ export interface components {
        * @example 2023-01-01T01:01:01.001Z
        */
       billingAnchor?: Date
-      /** @description The settlement mode of the subscription. */
-      settlementMode?: components['schemas']['BillingSettlementMode']
     }
     /**
      * @description A consumer portal token.

api/client/go/client.gen.go

@@ -17228,6 +17228,13 @@ export const ChangeSubscriptionBody = zod
             'References an exact plan defaulting to the current active version.',
           )
           .describe('The plan reference to change to.'),
+        settlementMode: zod
+          .enum(['credit_then_invoice', 'credit_only'])
+          .describe(
+            'The settlement mode of a plan.\nIt determines how the billing system generates invoices and credits for the subscriptions using this plan.\n- credit_then_invoice: credits from the previous billing period are applied first, then the remaining balance is invoiced. This is the default and most common settlement mode.\n- credit_only: only credits from the previous billing period are generated and applied. No invoices are generated for the subscription.',
+          )
+          .optional()
+          .describe('The settlement mode of the subscription.'),
         startingPhase: zod.coerce
           .string()
           .min(1)

api/client/javascript/src/client/schemas.ts

@@ -22589,6 +22589,10 @@ components:
           format: date-time
           description: The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the previous subscription billing anchor will be used.
           example: '2023-01-01T01:01:01.001Z'
+        settlementMode:
+          allOf:
+            - $ref: '#/components/schemas/BillingSettlementMode'
+          description: The settlement mode of the subscription.
       description: Change subscription based on plan.
     PlanSubscriptionCreate:
       type: object
@@ -22619,6 +22623,10 @@ components:
         description:
           type: string
           description: Description for the Subscription.
+        settlementMode:
+          allOf:
+            - $ref: '#/components/schemas/BillingSettlementMode'
+          description: The settlement mode of the subscription.
         timing:
           allOf:
             - $ref: '#/components/schemas/SubscriptionTiming'
@@ -22641,10 +22649,6 @@ components:
           format: date-time
           description: The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used.
           example: '2023-01-01T01:01:01.001Z'
-        settlementMode:
-          allOf:
-            - $ref: '#/components/schemas/BillingSettlementMode'
-          description: The settlement mode of the subscription.
       description: Create subscription based on plan.
       title: Create from plan
     PortalToken:

api/client/javascript/src/zod/index.ts

@@ -23372,6 +23372,10 @@ components:
           format: date-time
           description: The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the previous subscription billing anchor will be used.
           example: '2023-01-01T01:01:01.001Z'
+        settlementMode:
+          allOf:
+            - $ref: '#/components/schemas/BillingSettlementMode'
+          description: The settlement mode of the subscription.
       description: Change subscription based on plan.
     PlanSubscriptionCreate:
       type: object
@@ -23402,6 +23406,10 @@ components:
         description:
           type: string
           description: Description for the Subscription.
+        settlementMode:
+          allOf:
+            - $ref: '#/components/schemas/BillingSettlementMode'
+          description: The settlement mode of the subscription.
         timing:
           allOf:
             - $ref: '#/components/schemas/SubscriptionTiming'
@@ -23424,10 +23432,6 @@ components:
           format: date-time
           description: The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used.
           example: '2023-01-01T01:01:01.001Z'
-        settlementMode:
-          allOf:
-            - $ref: '#/components/schemas/BillingSettlementMode'
-          description: The settlement mode of the subscription.
       description: Create subscription based on plan.
       title: Create from plan
     PortalToken:

api/client/python/openmeter/_generated/models/_models.py

@@ -106,6 +106,19 @@ model Plan {
   @minItems(1)
   phases: PlanPhase[];
 
+  /**
+   * Settlement mode for plan.
+   *
+   * Values:
+   *
+   * - `credit_then_invoice`: Credits are applied first, then any remainder is
+   *   invoiced.
+   * - `credit_only`: Usage is settled exclusively against credits.
+   */
+  @visibility(Lifecycle.Read)
+  @summary("Settlement Mode")
+  settlement_mode?: ProductCatalog.SettlementMode = ProductCatalog.SettlementMode.CreditThenInvoice;
+
   /**
    * List of validation errors in `draft` state that prevent the plan from being
    * published.

api/openapi.cloud.yaml

@@ -1,5 +1,6 @@
 import "@typespec/openapi";
 import "../shared/index.tsp";
+import "../productcatalog/ratecard.tsp";
 
 using TypeSpec.OpenAPI;
 
@@ -166,4 +167,17 @@ model Subscription {
   @visibility(Lifecycle.Read)
   @summary("Status")
   status: SubscriptionStatus;
+
+  /**
+   * Settlement mode for billing.
+   *
+   * Values:
+   *
+   * - `credit_then_invoice`: Credits are applied first, then any remainder is
+   *   invoiced.
+   * - `credit_only`: Usage is settled exclusively against credits.
+   */
+  @visibility(Lifecycle.Create, Lifecycle.Read)
+  @summary("Settlement Mode")
+  settlement_mode?: ProductCatalog.SettlementMode = ProductCatalog.SettlementMode.CreditThenInvoice;
 }

api/openapi.yaml

@@ -459,11 +459,6 @@ model PlanSubscriptionCreate {
    * The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used.
    */
   billingAnchor?: DateTime;
-
-  /**
-   * The settlement mode of the subscription.
-   */
-  settlementMode?: SettlementMode;
 }
 
 /**
@@ -513,6 +508,11 @@ model PlanSubscriptionChange {
    * The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the previous subscription billing anchor will be used.
    */
   billingAnchor?: DateTime;
+
+  /**
+   * The settlement mode of the subscription.
+   */
+  settlementMode?: SettlementMode;
 }
 
 /**