feat(subs): add BillingAnchor to API and DB

Author: GAlexIHU

api/api.gen.go

@@ -3554,6 +3554,12 @@ export interface components {
       customerId?: string
       /** @description The key of the customer. Provide either the key or ID. */
       customerKey?: string
+      /**
+       * 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
+       */
+      billingAnchor?: Date
     }
     /**
      * @description A customer object.
@@ -8363,6 +8369,12 @@ export interface components {
       customerId?: string
       /** @description The key of the customer. Provide either the key or ID. */
       customerKey?: string
+      /**
+       * 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
+       */
+      billingAnchor?: Date
     }
     /** @description A consumer portal token.
      *
@@ -9312,6 +9324,13 @@ export interface components {
        *     }
        */
       readonly proRatingConfig?: components['schemas']['ProRatingConfig']
+      /**
+       * Billing anchor
+       * Format: date-time
+       * @description The normalizedbilling anchor of the subscription.
+       * @example 2023-01-01T01:01:01.001Z
+       */
+      readonly billingAnchor: Date
     }
     /** @description A subscription add-on, represents concrete instances of an add-on for a given subscription. */
     SubscriptionAddon: {
@@ -9681,6 +9700,13 @@ export interface components {
        *     }
        */
       readonly proRatingConfig?: components['schemas']['ProRatingConfig']
+      /**
+       * Billing anchor
+       * Format: date-time
+       * @description The normalizedbilling anchor of the subscription.
+       * @example 2023-01-01T01:01:01.001Z
+       */
+      readonly billingAnchor: Date
       /** @description Alignment details enriched with the current billing period. */
       alignment?: components['schemas']['SubscriptionAlignment']
       /** @description The phases of the subscription. */

api/client/go/client.gen.go

@@ -13832,6 +13832,12 @@ export const createSubscriptionBody = zod
       .describe('Alignment configuration for a plan or subscription.')
       .optional()
       .describe('What alignment settings the subscription should have.'),
+    billingAnchor: zod
+      .date()
+      .optional()
+      .describe(
+        '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.'
+      ),
     customerId: zod
       .string()
       .regex(createSubscriptionBodyCustomerIdRegExp)
@@ -13907,6 +13913,12 @@ export const createSubscriptionBody = zod
   .or(
     zod
       .object({
+        billingAnchor: zod
+          .date()
+          .optional()
+          .describe(
+            '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.'
+          ),
         customerId: zod
           .string()
           .regex(createSubscriptionBodyCustomerIdRegExpOne)

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

@@ -13255,6 +13255,11 @@ components:
           minLength: 1
           maxLength: 256
           description: The key of the customer. Provide either the key or ID.
+        billingAnchor:
+          type: string
+          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'
       description: Create a custom subscription.
     Customer:
       type: object
@@ -19747,6 +19752,11 @@ components:
           minLength: 1
           maxLength: 256
           description: The key of the customer. Provide either the key or ID.
+        billingAnchor:
+          type: string
+          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'
       description: Create subscription based on plan.
     PortalToken:
       type: object
@@ -20849,6 +20859,7 @@ components:
         - customerId
         - currency
         - billingCadence
+        - billingAnchor
       properties:
         id:
           type: string
@@ -20951,6 +20962,13 @@ components:
             enabled: true
             mode: prorate_prices
           readOnly: true
+        billingAnchor:
+          type: string
+          format: date-time
+          description: The normalizedbilling anchor of the subscription.
+          example: '2023-01-01T01:01:01.001Z'
+          title: Billing anchor
+          readOnly: true
       description: Subscription is an exact subscription instance.
     SubscriptionAddon:
       type: object
@@ -21324,6 +21342,7 @@ components:
         - customerId
         - currency
         - billingCadence
+        - billingAnchor
         - phases
       properties:
         id:
@@ -21423,6 +21442,13 @@ components:
             enabled: true
             mode: prorate_prices
           readOnly: true
+        billingAnchor:
+          type: string
+          format: date-time
+          description: The normalizedbilling anchor of the subscription.
+          example: '2023-01-01T01:01:01.001Z'
+          title: Billing anchor
+          readOnly: true
         alignment:
           allOf:
             - $ref: '#/components/schemas/SubscriptionAlignment'

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

@@ -13165,6 +13165,11 @@ components:
           minLength: 1
           maxLength: 256
           description: The key of the customer. Provide either the key or ID.
+        billingAnchor:
+          type: string
+          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'
       description: Create a custom subscription.
     Customer:
       type: object
@@ -20143,6 +20148,11 @@ components:
           minLength: 1
           maxLength: 256
           description: The key of the customer. Provide either the key or ID.
+        billingAnchor:
+          type: string
+          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'
       description: Create subscription based on plan.
     PortalToken:
       type: object
@@ -21383,6 +21393,7 @@ components:
         - customerId
         - currency
         - billingCadence
+        - billingAnchor
       properties:
         id:
           type: string
@@ -21485,6 +21496,13 @@ components:
             enabled: true
             mode: prorate_prices
           readOnly: true
+        billingAnchor:
+          type: string
+          format: date-time
+          description: The normalizedbilling anchor of the subscription.
+          example: '2023-01-01T01:01:01.001Z'
+          title: Billing anchor
+          readOnly: true
       description: Subscription is an exact subscription instance.
     SubscriptionAddon:
       type: object
@@ -21858,6 +21876,7 @@ components:
         - customerId
         - currency
         - billingCadence
+        - billingAnchor
         - phases
       properties:
         id:
@@ -21957,6 +21976,13 @@ components:
             enabled: true
             mode: prorate_prices
           readOnly: true
+        billingAnchor:
+          type: string
+          format: date-time
+          description: The normalizedbilling anchor of the subscription.
+          example: '2023-01-01T01:01:01.001Z'
+          title: Billing anchor
+          readOnly: true
         alignment:
           allOf:
             - $ref: '#/components/schemas/SubscriptionAlignment'

api/openapi.cloud.yaml

@@ -112,6 +112,13 @@ model Subscription {
     enabled: true,
     mode: ProRatingMode.proratePrices,
   };
+
+  /**
+   * The normalizedbilling anchor of the subscription.
+   */
+  @visibility(Lifecycle.Read)
+  @summary("Billing anchor")
+  billingAnchor: DateTime;
 }
 
 /**
@@ -367,6 +374,11 @@ model CustomSubscriptionCreate {
    * The key of the customer. Provide either the key or ID.
    */
   customerKey?: ExternalKey;
+
+  /**
+   * 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;
 }
 
 /**
@@ -418,6 +430,11 @@ model PlanSubscriptionCreate {
    * The key of the customer. Provide either the key or ID.
    */
   customerKey?: ExternalKey;
+
+  /**
+   * 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;
 }
 
 /**

api/openapi.yaml

@@ -417,10 +417,14 @@ func TestPlan(t *testing.T) {
 		require.NoError(t, ct.FromSubscriptionTiming1(startTime))
 
 		create := api.SubscriptionCreate{}
+
+		anchorTime := time.Now().Add(-time.Hour).Truncate(time.Millisecond).UTC()
+
 		err := create.FromCustomSubscriptionCreate(api.CustomSubscriptionCreate{
-			Timing:      ct,
-			CustomerKey: customer2.Key,   // Let's use the key
-			CustomPlan:  customPlanInput, // For simplicity we can reuse the same plan input, we know its valid
+			Timing:        ct,
+			CustomerKey:   customer2.Key,   // Let's use the key
+			CustomPlan:    customPlanInput, // For simplicity we can reuse the same plan input, we know its valid
+			BillingAnchor: lo.ToPtr(anchorTime),
 		})
 		require.Nil(t, err)
 
@@ -437,6 +441,7 @@ func TestPlan(t *testing.T) {
 
 		customSubscriptionId = subscription.Id
 		require.Equal(t, "P1M", subscription.BillingCadence)
+		require.True(t, anchorTime.UTC().Equal(subscription.BillingAnchor.UTC()), "billing anchor should be %s, got %s", anchorTime, subscription.BillingAnchor)
 		require.Equal(t, api.ProRatingModeProratePrices, subscription.ProRatingConfig.Mode)
 		require.True(t, subscription.ProRatingConfig.Enabled)
 	})