feat: expose unit_config on the v3 invoice line rate card

api/spec/packages/aip-client-javascript/src/index.ts

@@ -410,6 +410,7 @@ export type {
   CustomerStripeCreateCheckoutSessionRequestInput,
   WorkflowCollectionSettingsInput,
   RateCardInput,
+  InvoiceLineRateCardInput,
   WorkflowInput,
   SubscriptionAddonRateCardInput,
   PlanPhaseInput,

api/spec/packages/aip-client-javascript/src/models/schemas.ts

@@ -5057,6 +5057,7 @@ export const invoiceLineRateCard = z
     taxConfig: rateCardTaxConfig.optional(),
     featureKey: resourceKey.optional(),
     discounts: rateCardDiscounts.optional(),
+    unitConfig: unitConfig.optional(),
   })
   .describe('Rate card configuration snapshot for a usage-based invoice line.')
 
@@ -11722,6 +11723,7 @@ export const invoiceLineRateCardWire = z
     tax_config: rateCardTaxConfigWire.optional(),
     feature_key: resourceKeyWire.optional(),
     discounts: rateCardDiscountsWire.optional(),
+    unit_config: unitConfigWire.optional(),
   })
   .describe('Rate card configuration snapshot for a usage-based invoice line.')
 

api/spec/packages/aip-client-javascript/src/models/types.ts

@@ -4450,6 +4450,11 @@ export interface InvoiceLineRateCard {
   featureKey?: string
   /** Discount configuration from the rate card. */
   discounts?: RateCardDiscounts
+  /**
+   * Unit config snapshot applied when this line was billed, converting the raw
+   * metered quantity into the billed quantity. Frozen at billing time; read-only.
+   */
+  unitConfig?: UnitConfig
 }
 
 /** Rate card configuration snapshot for a usage-based invoice line. */
@@ -6354,6 +6359,23 @@ export interface RateCardInput {
   entitlement?: RateCardEntitlementInput
 }
 
+/** Rate card configuration snapshot for a usage-based invoice line. */
+export interface InvoiceLineRateCardInput {
+  /** The price definition used to calculate charges for this line. */
+  price: Price
+  /** Tax configuration snapshot for this line. */
+  taxConfig?: RateCardTaxConfig
+  /** The feature key associated with this line's rate card. */
+  featureKey?: string
+  /** Discount configuration from the rate card. */
+  discounts?: RateCardDiscounts
+  /**
+   * Unit config snapshot applied when this line was billed, converting the raw
+   * metered quantity into the billed quantity. Frozen at billing time; read-only.
+   */
+  unitConfig?: UnitConfigInput
+}
+
 /** Billing workflow settings. */
 export interface WorkflowInput {
   /** The collection settings for this workflow */
@@ -6575,7 +6597,7 @@ export interface InvoiceStandardLineInput {
   /** Reference to the subscription item that generated this line. */
   subscription?: SubscriptionReference
   /** The rate card configuration snapshot used to price this line item. */
-  rateCard: InvoiceLineRateCard
+  rateCard: InvoiceLineRateCardInput
   /**
    * Detailed sub-lines that this line has been broken down into.
    *

api/spec/packages/aip/src/invoices/invoice.tsp

@@ -2,6 +2,7 @@ import "../shared/index.tsp";
 import "../customers/index.tsp";
 import "../productcatalog/price.tsp";
 import "../productcatalog/ratecard.tsp";
+import "../productcatalog/unitconfig.tsp";
 import "../billing/profile.tsp";
 import "../billing/totals.tsp";
 import "../billing/tax.tsp";
@@ -803,6 +804,14 @@ model InvoiceLineRateCard {
   @visibility(Lifecycle.Read, Lifecycle.Update)
   @summary("Discounts")
   discounts?: ProductCatalog.Discounts;
+
+  /**
+   * Unit config snapshot applied when this line was billed, converting the raw
+   * metered quantity into the billed quantity. Frozen at billing time; read-only.
+   */
+  @visibility(Lifecycle.Read)
+  @summary("Unit config")
+  unit_config?: ProductCatalog.UnitConfig;
 }
 
 /**

api/v3/handlers/billinginvoices/convert.go

@@ -338,6 +338,10 @@ func mapRateCard(line *billing.StandardLine) (api.BillingInvoiceLineRateCard, er
 		TaxConfig:  addons.ToAPIBillingRateCardTaxConfig(line.TaxConfig.ToProductCatalog()),
 	}
 
+	if uc := line.GetUnitConfig(); uc != nil {
+		rc.UnitConfig = lo.ToPtr(plans.ToAPIBillingUnitConfig(*uc))
+	}
+
 	return rc, nil
 }
 

api/v3/handlers/billinginvoices/convert_test.go

@@ -74,6 +74,49 @@ func apiLineForMergeTest(t *testing.T, period timeutil.ClosedPeriod, id *string)
 	return out
 }
 
+func TestMapRateCardSurfacesUnitConfigSnapshot(t *testing.T) {
+	period := mergeTestPeriod()
+
+	// given: a standard line whose usage-based config carries a unit_config snapshot
+	// (a divide-by-1000, ceiling-rounded, "GB"-labeled conversion).
+	line := standardLineForMergeTest(t, "line-id", period)
+	line.UsageBased.Price = productcatalog.NewPriceFrom(productcatalog.UnitPrice{Amount: decimal.NewFromInt(5)})
+	line.UsageBased.UnitConfig = &productcatalog.UnitConfig{
+		Operation:        productcatalog.UnitConfigOperationDivide,
+		ConversionFactor: decimal.NewFromInt(1000),
+		Rounding:         productcatalog.UnitConfigRoundingModeCeiling,
+		Precision:        0,
+		DisplayUnit:      lo.ToPtr("GB"),
+	}
+
+	// when: mapping the line's rate card to the v3 API type.
+	rc, err := mapRateCard(line)
+	require.NoError(t, err)
+
+	// then: the snapshot surfaces field-for-field on the API rate card.
+	require.NotNil(t, rc.UnitConfig)
+	require.Equal(t, api.BillingUnitConfigOperationDivide, rc.UnitConfig.Operation)
+	require.Equal(t, "1000", rc.UnitConfig.ConversionFactor)
+	require.Equal(t, lo.ToPtr(api.BillingUnitConfigRoundingModeCeiling), rc.UnitConfig.Rounding)
+	require.Equal(t, lo.ToPtr(0), rc.UnitConfig.Precision)
+	require.Equal(t, lo.ToPtr("GB"), rc.UnitConfig.DisplayUnit)
+}
+
+func TestMapRateCardOmitsUnitConfigWhenAbsent(t *testing.T) {
+	period := mergeTestPeriod()
+
+	// given: a standard line with no unit_config snapshot (the common case).
+	line := standardLineForMergeTest(t, "line-id", period)
+	line.UsageBased.Price = productcatalog.NewPriceFrom(productcatalog.UnitPrice{Amount: decimal.NewFromInt(5)})
+
+	// when: mapping the rate card.
+	rc, err := mapRateCard(line)
+	require.NoError(t, err)
+
+	// then: the API field is nil (omitted) — identity with today's output.
+	require.Nil(t, rc.UnitConfig)
+}
+
 func TestMergeStandardInvoiceLinesFromAPITombstonesOmittedLines(t *testing.T) {
 	period := mergeTestPeriod()
 	keptLine := standardLineForMergeTest(t, "kept-line-id", period)

api/v3/openapi.yaml

@@ -6595,6 +6595,14 @@ components:
             - $ref: '#/components/schemas/BillingRateCardDiscounts'
           description: Discount configuration from the rate card.
           title: Discounts
+        unit_config:
+          allOf:
+            - $ref: '#/components/schemas/BillingUnitConfig'
+          description: |-
+            Unit config snapshot applied when this line was billed, converting the raw
+            metered quantity into the billed quantity. Frozen at billing time; read-only.
+          title: Unit config
+          readOnly: true
       additionalProperties: false
       description: Rate card configuration snapshot for a usage-based invoice line.
     BillingInvoiceLineUsageDiscount:

e2e/billinginvoices_v3_test.go

@@ -954,7 +954,7 @@ func updateLineFromStandardLine(t *testing.T, line v3sdk.InvoiceStandardLine) v3
 		Labels:        lo.EmptyableToPtr(line.Labels),
 		Type:          v3sdk.InvoiceLineTypeStandardLine,
 		ServicePeriod: line.ServicePeriod,
-		RateCard: v3sdk.InvoiceLineRateCard{
+		RateCard: v3sdk.UpdateInvoiceLineRateCard{
 			FeatureKey: line.RateCard.FeatureKey,
 			Discounts:  line.RateCard.Discounts,
 			TaxConfig:  line.RateCard.TaxConfig,
@@ -970,7 +970,7 @@ func newFlatUpdateLine(name string, period v3sdk.ClosedPeriod, amount string) v3
 		Name:          name,
 		Type:          v3sdk.InvoiceLineTypeStandardLine,
 		ServicePeriod: period,
-		RateCard: v3sdk.InvoiceLineRateCard{
+		RateCard: v3sdk.UpdateInvoiceLineRateCard{
 			Price: lo.Must(v3sdk.PriceFromPriceFlat(v3sdk.PriceFlat{Amount: amount})),
 		},
 	}