Feat: Customer create charges (#4503)

Co-authored-by: Andras Toth <4157749+tothandras@users.noreply.github.com>

Author: borosr

api/spec/packages/aip-client-javascript/README.md

@@ -152,6 +152,7 @@ The full call path, HTTP route, and a short description are listed below.
 | `client.customers.credits.grants.updateExternalSettlement` | `POST /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/settlement/external` | Update the payment settlement status of an externally funded credit grant. Use this endpoint to synchronize the payment state of an external payment with the system so that revenue recognition and credit availability work as expected.                                                                                                                                                                                                                                                                                                     |
 | `client.customers.credits.transactions.list`               | `GET /openmeter/customers/{customerId}/credits/transactions`                                | List credit transactions for a customer. Returns an immutable, chronological record of credit movements: funded credits and consumed credits. Transactions are returned in reverse chronological order by default.                                                                                                                                                                                                                                                                                                                             |
 | `client.customers.charges.list`                            | `GET /openmeter/customers/{customerId}/charges`                                             | List customer charges. Returns the customer's charges that are represented as either flat fee or usage-based charges.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `client.customers.charges.create`                          | `POST /openmeter/customers/{customerId}/charges`                                            | Create customer charge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 ### Entitlements
 

api/spec/packages/aip-client-javascript/src/funcs/customers.ts

@@ -39,6 +39,8 @@ import type {
   ListCreditTransactionsResponse,
   ListCustomerChargesRequest,
   ListCustomerChargesResponse,
+  CreateCustomerChargesRequest,
+  CreateCustomerChargesResponse,
 } from '../models/operations/customers.js'
 
 export function createCustomer(
@@ -325,3 +327,18 @@ export function listCustomerCharges(
       .json<ListCustomerChargesResponse>(),
   )
 }
+
+export function createCustomerCharges(
+  client: Client,
+  req: CreateCustomerChargesRequest,
+  options?: RequestOptions,
+): Promise<Result<CreateCustomerChargesResponse>> {
+  const path = encodePath('openmeter/customers/{customerId}/charges', {
+    customerId: req.customerId,
+  })
+  return request(() =>
+    http(client)
+      .post(path, { ...options, json: req.body })
+      .json<CreateCustomerChargesResponse>(),
+  )
+}

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

@@ -60,10 +60,10 @@ export type {
   AppStripeCheckoutSessionCustomTextParams,
   AppStripeCreateCustomerPortalSessionOptions,
   CreateLabels,
-  PriceFree,
   TaxConfigStripe,
   TaxConfigExternalInvoicing,
   FlatFeeDiscounts,
+  PriceFree,
   WorkflowCollectionAlignmentSubscription,
   WorkflowInvoicingSettings,
   WorkflowPaymentChargeAutomaticallySettings,
@@ -87,9 +87,9 @@ export type {
   AppCustomerDataStripe,
   AppCustomerDataExternalInvoicing,
   ListCostBasesParamsFilter,
+  CurrencyAmount,
   PriceFlat,
   PriceUnit,
-  CurrencyAmount,
   RateCardDiscounts,
   Totals,
   FeatureManualUnitCost,
@@ -244,6 +244,7 @@ export type {
   PricePagePaginatedResponse,
   CreateCreditGrantRequest,
   CreditGrant,
+  CreateFlatFeeChargeRequest,
   WorkflowTaxSettings,
   SubscriptionAddonPagePaginatedResponse,
   PlanAddonPagePaginatedResponse,
@@ -268,6 +269,7 @@ export type {
   GovernanceQueryResponse,
   FlatFeeCharge,
   UsageBasedCharge,
+  CreateUsageBasedChargeRequest,
   RateCard,
   FeaturePagePaginatedResponse,
   Workflow,

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

@@ -8,6 +8,8 @@ import type {
   CreateCreditAdjustmentRequest as CreateCreditAdjustmentRequestBody,
   CreateCreditGrantRequestInput,
   CreateCustomerRequest as CreateCustomerRequestBody,
+  CreateFlatFeeChargeRequest,
+  CreateUsageBasedChargeRequest,
   CreditAdjustment,
   CreditBalances,
   CreditGrant,
@@ -167,3 +169,11 @@ export type ListCustomerChargesRequest = ListCustomerChargesQuery & {
   customerId: string
 }
 export type ListCustomerChargesResponse = ChargePagePaginatedResponse
+
+export type CreateCustomerChargesRequest = {
+  customerId: string
+  body: CreateFlatFeeChargeRequest | CreateUsageBasedChargeRequest
+}
+export type CreateCustomerChargesResponse = z.output<
+  typeof schemas.createCustomerChargesResponse
+>

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

@@ -598,12 +598,6 @@ export const chargeStatus = z
     'Lifecycle status of a charge. Values: - `created`: The charge has been created but is not active yet. - `active`: The charge is active. - `final`: The charge is fully finalized and no further changes are expected. - `deleted`: The charge has been deleted.',
   )
 
-export const priceFree = z
-  .object({
-    type: z.literal('free').describe('The type of the price.'),
-  })
-  .describe('Free price.')
-
 export const settlementMode = z
   .enum(['credit_then_invoice', 'credit_only'])
 
@@ -657,6 +651,12 @@ export const rateCardProrationMode = z
     'The proration mode of the rate card. Values: - `no_proration`: No proration. - `prorate_prices`: Prorate the price based on the time remaining in the billing period.',
   )
 
+export const priceFree = z
+  .object({
+    type: z.literal('free').describe('The type of the price.'),
+  })
+  .describe('Free price.')
+
 export const subscriptionStatus = z
   .enum(['active', 'inactive', 'canceled', 'scheduled'])
   .describe('Subscription status.')
@@ -1241,6 +1241,13 @@ export const listCostBasesParamsFilter = z
   })
   .describe('Filter options for listing cost bases.')
 
+export const currencyAmount = z
+  .object({
+    amount: numeric,
+    currency: currencyCode,
+  })
+  .describe('Monetary amount in a specific currency.')
+
 export const priceFlat = z
   .object({
     type: z.literal('flat').describe('The type of the price.'),
@@ -1258,13 +1265,6 @@ export const priceUnit = z
     'Unit price. Charges a fixed rate per billing unit. When UnitConfig is present on the rate card, billing units are the converted quantities (e.g. GB instead of bytes).',
   )
 
-export const currencyAmount = z
-  .object({
-    amount: numeric,
-    currency: currencyCode,
-  })
-  .describe('Monetary amount in a specific currency.')
-
 export const rateCardDiscounts = z
   .object({
     percentage: z
@@ -3759,6 +3759,45 @@ export const creditGrant = z
     'A credit grant allocates credits to a customer. Credits are drawn down against charges according to the settlement mode configured on the rate card.',
   )
 
+export const createFlatFeeChargeRequest = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(256)
+      .describe('Display name of the resource. Between 1 and 256 characters.'),
+    description: z
+      .string()
+      .max(1024)
+      .optional()
+
+      .describe(
+        'Optional description of the resource. Maximum 1024 characters.',
+      ),
+    labels: labels.optional(),
+    type: z.literal('flat_fee').describe('The type of the charge.'),
+    currency: currencyCode,
+    invoice_at: dateTime,
+    service_period: closedPeriod,
+    unique_reference_id: z
+      .string()
+      .optional()
+      .describe('Unique reference ID of the charge.'),
+    settlement_mode: settlementMode,
+    tax_config: taxConfig.optional(),
+    payment_term: pricePaymentTerm,
+    discounts: flatFeeDiscounts.optional(),
+    feature_key: z
+      .string()
+      .optional()
+      .describe('The feature associated with the charge, when applicable.'),
+    proration_configuration: rateCardProrationConfiguration,
+    amount_before_proration: currencyAmount,
+    full_service_period: closedPeriod.optional(),
+    billing_period: closedPeriod.optional(),
+  })
+  .describe('Flat fee charge create request.')
+
 export const workflowTaxSettings = z
   .object({
     enabled: z
@@ -4157,7 +4196,6 @@ export const flatFeeCharge = z
     full_service_period: closedPeriod,
     billing_period: closedPeriod,
     advance_after: dateTime.optional(),
-    price: price,
     unique_reference_id: z
       .string()
       .optional()
@@ -4171,7 +4209,9 @@ export const flatFeeCharge = z
       .optional()
       .describe('The feature associated with the charge, when applicable.'),
     proration_configuration: rateCardProrationConfiguration,
+    amount_before_proration: currencyAmount,
     amount_after_proration: currencyAmount,
+    price: price,
   })
   .describe('A flat fee charge for a customer.')
 
@@ -4206,7 +4246,6 @@ export const usageBasedCharge = z
     full_service_period: closedPeriod,
     billing_period: closedPeriod,
     advance_after: dateTime.optional(),
-    price: price,
     unique_reference_id: z
       .string()
       .optional()
@@ -4216,9 +4255,44 @@ export const usageBasedCharge = z
     discounts: rateCardDiscounts.optional(),
     feature_key: z.string().describe('The feature associated with the charge.'),
     totals: chargeTotals,
+    price: price,
   })
   .describe('A usage-based charge for a customer.')
 
+export const createUsageBasedChargeRequest = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(256)
+      .describe('Display name of the resource. Between 1 and 256 characters.'),
+    description: z
+      .string()
+      .max(1024)
+      .optional()
+
+      .describe(
+        'Optional description of the resource. Maximum 1024 characters.',
+      ),
+    labels: labels.optional(),
+    type: z.literal('usage_based').describe('The type of the charge.'),
+    currency: currencyCode,
+    invoice_at: dateTime,
+    service_period: closedPeriod,
+    unique_reference_id: z
+      .string()
+      .optional()
+      .describe('Unique reference ID of the charge.'),
+    settlement_mode: settlementMode,
+    tax_config: taxConfig.optional(),
+    discounts: rateCardDiscounts.optional(),
+    feature_key: z.string().describe('The feature associated with the charge.'),
+    price: price,
+    full_service_period: closedPeriod.optional(),
+    billing_period: closedPeriod.optional(),
+  })
+  .describe('Usage-based charge create request.')
+
 export const rateCard = z
   .object({
     name: z
@@ -4270,6 +4344,13 @@ export const charge = z
   .discriminatedUnion('type', [flatFeeCharge, usageBasedCharge])
   .describe('Customer charge.')
 
+export const createChargeRequest = z
+  .discriminatedUnion('type', [
+    createFlatFeeChargeRequest,
+    createUsageBasedChargeRequest,
+  ])
+  .describe('Customer charge.')
+
 export const planPhase = z
   .object({
     name: z
@@ -4887,6 +4968,14 @@ export const listCustomerChargesResponse = z.object({
   meta: paginatedMeta,
 })
 
+export const createCustomerChargesPathParams = z.object({
+  customerId: ulid,
+})
+
+export const createCustomerChargesBody = createChargeRequest
+
+export const createCustomerChargesResponse = charge
+
 export const createSubscriptionBody = subscriptionCreate
 
 export const createSubscriptionResponse = subscription