@flexprice/mcp-server 2.0.9 → 2.0.11

package/src/models/dtoaddaddontosubscriptionrequest.ts

@@ -24,7 +24,9 @@ export const DtoAddAddonToSubscriptionRequest$zodSchema: z.ZodType<
   line_item_commitments: z.record(
     z.string(),
     DtoLineItemCommitmentConfig$zodSchema,
-  ).optional(),
+  ).optional().describe(
+    "LineItemCommitments allows setting commitment configuration per addon line item (keyed by price_id)",
+  ),
   metadata: z.record(z.string(), z.any()).optional(),
   start_date: z.string().optional(),
 });

package/src/models/dtoaddonresponse.ts

@@ -44,7 +44,8 @@ export const DtoAddonResponse$zodSchema: z.ZodType<DtoAddonResponse> = z.object(
     lookup_key: z.string().optional(),
     metadata: z.record(z.string(), z.any()).optional(),
     name: z.string().optional(),
-    prices: z.array(z.lazy(() => DtoPriceResponse$zodSchema)).optional(),
+    prices: z.array(z.lazy(() => DtoPriceResponse$zodSchema)).optional()
+      .describe("Optional expanded fields"),
     status: Status$zodSchema.optional(),
     tenant_id: z.string().optional(),
     type: AddonType$zodSchema.optional(),

package/src/models/dtoaggregatedentitlement.ts

@@ -21,7 +21,9 @@ export const DtoAggregatedEntitlement$zodSchema: z.ZodType<
 > = z.object({
   is_enabled: z.boolean().optional(),
   is_soft_limit: z.boolean().optional(),
-  static_values: z.array(z.string()).optional(),
+  static_values: z.array(z.string()).optional().describe(
+    "For static/SLA features",
+  ),
   usage_limit: z.int().optional(),
   usage_reset_period: EntitlementUsageResetPeriod$zodSchema.optional(),
 });

package/src/models/dtobillingcycleinfo.ts

@@ -17,10 +17,18 @@ export type DtoBillingCycleInfo = {
 
 export const DtoBillingCycleInfo$zodSchema: z.ZodType<DtoBillingCycleInfo> = z
   .object({
-    billing_anchor: z.string().optional(),
+    billing_anchor: z.string().optional().describe(
+      "billing_anchor is the new billing anchor",
+    ),
     billing_cadence: BillingCadence$zodSchema.optional(),
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: z.int().optional(),
-    period_end: z.string().optional(),
-    period_start: z.string().optional(),
+    billing_period_count: z.int().optional().describe(
+      "billing_period_count is the billing period count",
+    ),
+    period_end: z.string().optional().describe(
+      "period_end is the end of the new billing period",
+    ),
+    period_start: z.string().optional().describe(
+      "period_start is the start of the new billing period",
+    ),
   });

package/src/models/dtobillingperiodinfo.ts

@@ -13,6 +13,6 @@ export type DtoBillingPeriodInfo = {
 export const DtoBillingPeriodInfo$zodSchema: z.ZodType<DtoBillingPeriodInfo> = z
   .object({
     end_time: z.string().optional(),
-    period: z.string().optional(),
+    period: z.string().optional().describe("e.g., \"monthly\", \"yearly\""),
     start_time: z.string().optional(),
   });

package/src/models/dtocancelschedulerequest.ts

@@ -20,7 +20,11 @@ export type DtoCancelScheduleRequest = {
 export const DtoCancelScheduleRequest$zodSchema: z.ZodType<
   DtoCancelScheduleRequest
 > = z.object({
-  schedule_id: z.string().optional(),
+  schedule_id: z.string().optional().describe(
+    "schedule_id is the ID of the schedule to cancel (optional if subscription_id and schedule_type are provided)",
+  ),
   schedule_type: SubscriptionScheduleChangeType$zodSchema.optional(),
-  subscription_id: z.string().optional(),
+  subscription_id: z.string().optional().describe(
+    "subscription_id is the ID of the subscription (required if schedule_id is not provided)",
+  ),
 }).describe("Request to cancel a subscription schedule (supports two modes)");

package/src/models/dtocancelscheduleresponse.ts

@@ -16,6 +16,6 @@ export type DtoCancelScheduleResponse = {
 export const DtoCancelScheduleResponse$zodSchema: z.ZodType<
   DtoCancelScheduleResponse
 > = z.object({
-  message: z.string().optional(),
+  message: z.string().optional().describe("message is a confirmation message"),
   status: ScheduleStatus$zodSchema.optional(),
 }).describe("Confirmation of schedule cancellation");

package/src/models/dtocancelsubscriptionrequest.ts

@@ -17,6 +17,7 @@ import {
 } from "./prorationbehavior.js";
 
 export type DtoCancelSubscriptionRequest = {
+  cancel_at?: string | undefined;
   cancel_immediately_inovice_policy?:
     | CancelImmediatelyInvoicePolicy
     | undefined;
@@ -28,9 +29,14 @@ export type DtoCancelSubscriptionRequest = {
 export const DtoCancelSubscriptionRequest$zodSchema: z.ZodType<
   DtoCancelSubscriptionRequest
 > = z.object({
+  cancel_at: z.string().optional().describe(
+    "CancelAt is the custom date to cancel the subscription.\nRequired when CancellationType is \"scheduled_date\". Must be in the future.",
+  ),
   cancel_immediately_inovice_policy: CancelImmediatelyInvoicePolicy$zodSchema
     .optional(),
   cancellation_type: CancellationType$zodSchema,
   proration_behavior: ProrationBehavior$zodSchema.optional(),
-  reason: z.string().optional(),
+  reason: z.string().optional().describe(
+    "Reason for cancellation (for audit and business intelligence)",
+  ),
 });

package/src/models/dtocancelsubscriptionresponse.ts

@@ -38,12 +38,12 @@ export const DtoCancelSubscriptionResponse$zodSchema: z.ZodType<
 > = z.object({
   cancellation_type: CancellationType$zodSchema.optional(),
   effective_date: z.string().optional(),
-  message: z.string().optional(),
+  message: z.string().optional().describe("Response metadata"),
   processed_at: z.string().optional(),
   proration_details: z.array(DtoProrationDetail$zodSchema).optional(),
   proration_invoice: DtoInvoiceResponse$zodSchema.optional(),
   reason: z.string().optional(),
   status: SubscriptionStatus$zodSchema.optional(),
-  subscription_id: z.string().optional(),
+  subscription_id: z.string().optional().describe("Basic cancellation info"),
   total_credit_amount: z.string().optional(),
 });

package/src/models/dtocloneplanrequest.ts

@@ -14,9 +14,17 @@ export type DtoClonePlanRequest = {
 
 export const DtoClonePlanRequest$zodSchema: z.ZodType<DtoClonePlanRequest> = z
   .object({
-    description: z.string().optional(),
-    display_order: z.int().optional(),
-    lookup_key: z.string().optional(),
+    description: z.string().optional().describe(
+      "Description overrides the source plan's description when provided",
+    ),
+    display_order: z.int().optional().describe(
+      "DisplayOrder overrides the source plan's display order when provided",
+    ),
+    lookup_key: z.string().optional().describe(
+      "LookupKey is required and must be unique across published plans",
+    ),
     metadata: z.record(z.string(), z.string()).optional(),
-    name: z.string().optional(),
+    name: z.string().optional().describe(
+      "Name is required and must be different from the source plan's name",
+    ),
   });

package/src/models/dtocouponassociationresponse.ts

@@ -36,15 +36,15 @@ export const DtoCouponAssociationResponse$zodSchema: z.ZodType<
   coupon_id: z.string().optional(),
   created_at: z.string().optional(),
   created_by: z.string().optional(),
-  end_date: z.string().optional(),
+  end_date: z.string().optional().describe("Optional"),
   environment_id: z.string().optional(),
   id: z.string().optional(),
   metadata: z.record(z.string(), z.string()).optional(),
   start_date: z.string().optional(),
   status: Status$zodSchema.optional(),
-  subscription_id: z.string().optional(),
-  subscription_line_item_id: z.string().optional(),
-  subscription_phase_id: z.string().optional(),
+  subscription_id: z.string().optional().describe("Mandatory"),
+  subscription_line_item_id: z.string().optional().describe("Optional"),
+  subscription_phase_id: z.string().optional().describe("Optional"),
   tenant_id: z.string().optional(),
   updated_at: z.string().optional(),
   updated_by: z.string().optional(),

package/src/models/dtocreatecreditgrantrequest.ts

@@ -48,7 +48,9 @@ export const DtoCreateCreditGrantRequest$zodSchema: z.ZodType<
   DtoCreateCreditGrantRequest
 > = z.object({
   cadence: CreditGrantCadence$zodSchema,
-  conversion_rate: z.string().optional(),
+  conversion_rate: z.string().optional().describe(
+    "amount in the currency =  number of credits * conversion_rate\nex if conversion_rate is 1, then 1 USD = 1 credit\nex if conversion_rate is 2, then 1 USD = 0.5 credits\nex if conversion_rate is 0.5, then 1 USD = 2 credits",
+  ),
   credits: z.string(),
   end_date: z.string().optional(),
   expiration_duration: z.int().optional(),
@@ -63,5 +65,7 @@ export const DtoCreateCreditGrantRequest$zodSchema: z.ZodType<
   scope: CreditGrantScope$zodSchema,
   start_date: z.string().optional(),
   subscription_id: z.string().optional(),
-  topup_conversion_rate: z.string().optional(),
+  topup_conversion_rate: z.string().optional().describe(
+    "topup_conversion_rate is the conversion rate for the topup to the currency\nex if topup_conversion_rate is 1, then 1 USD = 1 credit\nex if topup_conversion_rate is 2, then 1 USD = 0.5 credits\nex if topup_conversion_rate is 0.5, then 1 USD = 2 credits",
+  ),
 });

package/src/models/dtocreatecustomerrequest.ts

@@ -36,20 +36,50 @@ export type DtoCreateCustomerRequest = {
 export const DtoCreateCustomerRequest$zodSchema: z.ZodType<
   DtoCreateCustomerRequest
 > = z.object({
-  address_city: z.string().optional(),
-  address_country: z.string().optional(),
-  address_line1: z.string().optional(),
-  address_line2: z.string().optional(),
-  address_postal_code: z.string().optional(),
-  address_state: z.string().optional(),
-  email: z.string().optional(),
-  external_id: z.string(),
+  address_city: z.string().optional().describe(
+    "address_city is the city name with maximum 100 characters",
+  ),
+  address_country: z.string().optional().describe(
+    "address_country is the two-letter ISO 3166-1 alpha-2 country code",
+  ),
+  address_line1: z.string().optional().describe(
+    "address_line1 is the primary address line with maximum 255 characters",
+  ),
+  address_line2: z.string().optional().describe(
+    "address_line2 is the secondary address line with maximum 255 characters",
+  ),
+  address_postal_code: z.string().optional().describe(
+    "address_postal_code is the ZIP code or postal code with maximum 20 characters",
+  ),
+  address_state: z.string().optional().describe(
+    "address_state is the state, province, or region name with maximum 100 characters",
+  ),
+  email: z.string().optional().describe(
+    "email is the customer's email address and must be a valid email format if provided",
+  ),
+  external_id: z.string().describe(
+    "external_id is the unique identifier from your system to reference this customer (required)",
+  ),
   integration_entity_mapping: z.array(DtoIntegrationEntityMapping$zodSchema)
-    .optional(),
-  metadata: z.record(z.string(), z.string()).optional(),
-  name: z.string().optional(),
-  parent_customer_external_id: z.string().optional(),
-  parent_customer_id: z.string().optional(),
-  skip_onboarding_workflow: z.boolean().optional(),
-  tax_rate_overrides: z.array(DtoTaxRateOverride$zodSchema).optional(),
+    .optional().describe(
+      "integration_entity_mapping contains provider integration mappings for this customer",
+    ),
+  metadata: z.record(z.string(), z.string()).optional().describe(
+    "metadata contains additional key-value pairs for storing extra information",
+  ),
+  name: z.string().optional().describe(
+    "name is the full name or company name of the customer",
+  ),
+  parent_customer_external_id: z.string().optional().describe(
+    "Deprecated: See ParentCustomerID.\nparent_customer_external_id is the external ID of the parent customer from your system.\nExactly one of parent_customer_id or parent_customer_external_id may be provided.",
+  ),
+  parent_customer_id: z.string().optional().describe(
+    "Deprecated: Customer parent hierarchy is deprecated in favor of subscription-level hierarchy.\nThis field is accepted for backward compatibility but no hierarchy validations are enforced.\nparent_customer_id is the internal FlexPrice ID of the parent customer.",
+  ),
+  skip_onboarding_workflow: z.boolean().optional().describe(
+    "skip_onboarding_workflow when true, prevents the customer onboarding workflow from being triggered\nThis is used internally when a customer is created via a workflow to prevent infinite loops\nDefault: false",
+  ),
+  tax_rate_overrides: z.array(DtoTaxRateOverride$zodSchema).optional().describe(
+    "tax_rate_overrides contains tax rate configurations to be linked to this customer",
+  ),
 }).describe("Request object for creating a new customer in the system");

package/src/models/dtocreateinvoicelineitemrequest.ts

@@ -31,24 +31,60 @@ export type DtoCreateInvoiceLineItemRequest = {
 export const DtoCreateInvoiceLineItemRequest$zodSchema: z.ZodType<
   DtoCreateInvoiceLineItemRequest
 > = z.object({
-  amount: z.string(),
+  amount: z.string().describe(
+    "amount is the monetary amount for this line item",
+  ),
   commitment_info: CommitmentInfo$zodSchema.optional(),
-  display_name: z.string().optional(),
-  entity_id: z.string().optional(),
-  entity_type: z.string().optional(),
-  invoice_level_discount: z.string().optional(),
-  line_item_discount: z.string().optional(),
+  display_name: z.string().optional().describe(
+    "display_name is the optional human-readable name for this line item",
+  ),
+  entity_id: z.string().optional().describe(
+    "entity_id is the optional unique identifier of the entity associated with this line item",
+  ),
+  entity_type: z.string().optional().describe(
+    "entity_type is the optional type of the entity associated with this line item",
+  ),
+  invoice_level_discount: z.string().optional().describe(
+    "invoice_level_discount is the discount amount in invoice currency applied to all line items on the invoice.",
+  ),
+  line_item_discount: z.string().optional().describe(
+    "line_item_discount is the discount amount in invoice currency applied directly to this line item.",
+  ),
   metadata: z.record(z.string(), z.string()).optional(),
-  meter_display_name: z.string().optional(),
-  meter_id: z.string().optional(),
-  period_end: z.string().optional(),
-  period_start: z.string().optional(),
-  plan_display_name: z.string().optional(),
-  plan_id: z.string().optional(),
-  prepaid_credits_applied: z.string().optional(),
-  price_id: z.string().optional(),
-  price_type: z.string().optional(),
-  price_unit: z.string().optional(),
-  price_unit_amount: z.string().optional(),
-  quantity: z.string(),
+  meter_display_name: z.string().optional().describe(
+    "meter_display_name is the optional human-readable name of the meter",
+  ),
+  meter_id: z.string().optional().describe(
+    "meter_id is the optional unique identifier of the meter used for usage tracking",
+  ),
+  period_end: z.string().optional().describe(
+    "period_end is the optional end date of the period this line item covers",
+  ),
+  period_start: z.string().optional().describe(
+    "period_start is the optional start date of the period this line item covers",
+  ),
+  plan_display_name: z.string().optional().describe(
+    "plan_display_name is the optional human-readable name of the plan",
+  ),
+  plan_id: z.string().optional().describe(
+    "TODO: !REMOVE after migration\nplan_id is the optional unique identifier of the plan associated with this line item",
+  ),
+  prepaid_credits_applied: z.string().optional().describe(
+    "prepaid_credits_applied is the amount in invoice currency reduced from this line item due to prepaid credits application.",
+  ),
+  price_id: z.string().optional().describe(
+    "price_id is the optional unique identifier of the price associated with this line item",
+  ),
+  price_type: z.string().optional().describe(
+    "price_type indicates the type of pricing (fixed, usage, tiered, etc.)",
+  ),
+  price_unit: z.string().optional().describe(
+    "price_unit is the optional 3-digit ISO code of the price unit associated with this line item",
+  ),
+  price_unit_amount: z.string().optional().describe(
+    "price_unit_amount is the optional amount converted to the price unit currency",
+  ),
+  quantity: z.string().describe(
+    "quantity is the quantity of units for this line item",
+  ),
 });

package/src/models/dtocreateinvoicerequest.ts

@@ -65,32 +65,74 @@ export type DtoCreateInvoiceRequest = {
 export const DtoCreateInvoiceRequest$zodSchema: z.ZodType<
   DtoCreateInvoiceRequest
 > = z.object({
-  amount_due: z.string(),
-  amount_paid: z.string().optional(),
-  billing_period: z.string().optional(),
+  amount_due: z.string().describe(
+    "amount_due is the total amount that needs to be paid for this invoice",
+  ),
+  amount_paid: z.string().optional().describe(
+    "amount_paid is the amount that has been paid towards this invoice",
+  ),
+  billing_period: z.string().optional().describe(
+    "billing_period is the period this invoice covers (e.g., \"monthly\", \"yearly\")",
+  ),
   billing_reason: InvoiceBillingReason$zodSchema.optional(),
-  coupons: z.array(z.string()).optional(),
-  currency: z.string(),
-  customer_id: z.string(),
-  description: z.string().optional(),
-  due_date: z.string().optional(),
-  idempotency_key: z.string().optional(),
-  invoice_coupons: z.array(DtoInvoiceCoupon$zodSchema).optional(),
-  invoice_number: z.string().optional(),
-  invoice_pdf_url: z.string().optional(),
+  coupons: z.array(z.string()).optional().describe("coupons"),
+  currency: z.string().describe(
+    "currency is the three-letter ISO currency code (e.g., USD, EUR) for the invoice",
+  ),
+  customer_id: z.string().describe(
+    "customer_id is the unique identifier of the customer this invoice belongs to",
+  ),
+  description: z.string().optional().describe(
+    "description is an optional text description of the invoice",
+  ),
+  due_date: z.string().optional().describe(
+    "due_date is the date by which payment is expected",
+  ),
+  idempotency_key: z.string().optional().describe(
+    "idempotency_key is an optional key used to prevent duplicate invoice creation",
+  ),
+  invoice_coupons: z.array(DtoInvoiceCoupon$zodSchema).optional().describe(
+    "Invoice Coupons",
+  ),
+  invoice_number: z.string().optional().describe(
+    "invoice_number is an optional human-readable identifier for the invoice",
+  ),
+  invoice_pdf_url: z.string().optional().describe(
+    "invoice_pdf_url is the URL where customers can download the PDF version of this invoice",
+  ),
   invoice_status: InvoiceStatus$zodSchema.optional(),
   invoice_type: InvoiceType$zodSchema.optional(),
-  line_item_coupons: z.array(DtoInvoiceLineItemCoupon$zodSchema).optional(),
-  line_items: z.array(DtoCreateInvoiceLineItemRequest$zodSchema).optional(),
+  line_item_coupons: z.array(DtoInvoiceLineItemCoupon$zodSchema).optional()
+    .describe("Invoice Line Item Coupons"),
+  line_items: z.array(DtoCreateInvoiceLineItemRequest$zodSchema).optional()
+    .describe(
+      "line_items contains the individual items that make up this invoice",
+    ),
   metadata: z.record(z.string(), z.string()).optional(),
   payment_status: PaymentStatus$zodSchema.optional(),
-  period_end: z.string().optional(),
-  period_start: z.string().optional(),
-  prepared_tax_rates: z.array(DtoTaxRateResponse$zodSchema).optional(),
-  subscription_id: z.string().optional(),
-  subtotal: z.string(),
-  tax_rate_overrides: z.array(DtoTaxRateOverride$zodSchema).optional(),
-  tax_rates: z.array(z.string()).optional(),
-  total: z.string(),
-  total_prepaid_applied: z.string().optional(),
+  period_end: z.string().optional().describe(
+    "period_end is the end date of the billing period",
+  ),
+  period_start: z.string().optional().describe(
+    "period_start is the start date of the billing period",
+  ),
+  prepared_tax_rates: z.array(DtoTaxRateResponse$zodSchema).optional().describe(
+    "prepared_tax_rates contains the tax rates pre-resolved by the caller (e.g., billing service)",
+  ),
+  subscription_id: z.string().optional().describe(
+    "subscription_id is the optional unique identifier of the subscription associated with this invoice",
+  ),
+  subtotal: z.string().describe(
+    "subtotal is the amount before taxes and discounts are applied",
+  ),
+  tax_rate_overrides: z.array(DtoTaxRateOverride$zodSchema).optional().describe(
+    "tax_rate_overrides is the tax rate overrides to be applied to the invoice",
+  ),
+  tax_rates: z.array(z.string()).optional().describe("tax_rates"),
+  total: z.string().describe(
+    "total is the total amount of the invoice including taxes and discounts",
+  ),
+  total_prepaid_applied: z.string().optional().describe(
+    "total_prepaid_applied is the total amount of prepaid applied to this invoice.",
+  ),
 });

package/src/models/dtocreatepricerequest.ts

@@ -70,12 +70,16 @@ export const DtoCreatePriceRequest$zodSchema: z.ZodType<DtoCreatePriceRequest> =
     entity_id: z.string(),
     entity_type: PriceEntityType$zodSchema,
     filter_values: z.record(z.string(), z.array(z.string())).optional(),
-    group_id: z.string().optional(),
+    group_id: z.string().optional().describe(
+      "GroupID is the id of the group to add the price to",
+    ),
     invoice_cadence: InvoiceCadence$zodSchema,
     lookup_key: z.string().optional(),
     metadata: z.record(z.string(), z.string()).optional(),
     meter_id: z.string().optional(),
-    min_quantity: z.int().optional(),
+    min_quantity: z.int().optional().describe(
+      "MinQuantity is the minimum quantity of the price",
+    ),
     price_unit_config: DtoPriceUnitConfig$zodSchema.optional(),
     price_unit_type: PriceUnitType$zodSchema,
     start_date: z.string().optional(),

package/src/models/dtocreatepricetier.ts

@@ -12,7 +12,13 @@ export type DtoCreatePriceTier = {
 
 export const DtoCreatePriceTier$zodSchema: z.ZodType<DtoCreatePriceTier> = z
   .object({
-    flat_amount: z.string().optional(),
-    unit_amount: z.string(),
-    up_to: z.int().optional(),
+    flat_amount: z.string().optional().describe(
+      "flat_amount is the flat amount for the given tier (optional)\nApplied on top of unit_amount*quantity. Useful for cases like \"2.7$ + 5c\"",
+    ),
+    unit_amount: z.string().describe(
+      "unit_amount is the amount per unit for the given tier",
+    ),
+    up_to: z.int().optional().describe(
+      "up_to is the quantity up to which this tier applies. It is null for the last tier.\nIMPORTANT: Tier boundaries are INCLUSIVE.\n- If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier\n- This behavior is consistent across both VOLUME and SLAB tier modes",
+    ),
   });

package/src/models/dtocreatesubscriptionlineitemrequest.ts

@@ -31,7 +31,7 @@ export type DtoCreateSubscriptionLineItemRequest = {
 export const DtoCreateSubscriptionLineItemRequest$zodSchema: z.ZodType<
   DtoCreateSubscriptionLineItemRequest
 > = z.object({
-  commitment_amount: z.number().optional(),
+  commitment_amount: z.number().optional().describe("Commitment fields"),
   commitment_duration: BillingPeriod$zodSchema.optional(),
   commitment_overage_factor: z.number().optional(),
   commitment_quantity: z.number().optional(),
@@ -42,7 +42,9 @@ export const DtoCreateSubscriptionLineItemRequest$zodSchema: z.ZodType<
   end_date: z.string().optional(),
   metadata: z.record(z.string(), z.string()).optional(),
   price: DtoSubscriptionPriceCreateRequest$zodSchema.optional(),
-  price_id: z.string().optional(),
+  price_id: z.string().optional().describe(
+    "PriceID references an existing price (plan, addon, or subscription-scoped). Exactly one of price_id or price must be set.",
+  ),
   quantity: z.number().optional(),
   start_date: z.string().optional(),
   subscription_phase_id: z.string().optional(),

package/src/models/dtocreatesubscriptionrequest.ts

@@ -76,6 +76,8 @@ export type DtoCreateSubscriptionRequest = {
   external_customer_id?: string | undefined;
   gateway_payment_method_id?: string | undefined;
   invoice_billing?: InvoiceBilling | undefined;
+  invoicing_customer_external_id?: string | undefined;
+  invoicing_customer_id?: string | undefined;
   line_item_commitments?:
     | { [k: string]: DtoLineItemCommitmentConfig }
     | undefined;
@@ -102,46 +104,84 @@ export type DtoCreateSubscriptionRequest = {
 export const DtoCreateSubscriptionRequest$zodSchema: z.ZodType<
   DtoCreateSubscriptionRequest
 > = z.object({
-  addons: z.array(DtoAddAddonToSubscriptionRequest$zodSchema).optional(),
+  addons: z.array(DtoAddAddonToSubscriptionRequest$zodSchema).optional()
+    .describe(
+      "Addons represents addons to be added to the subscription during creation",
+    ),
   billing_cadence: BillingCadence$zodSchema,
   billing_cycle: BillingCycle$zodSchema.optional(),
   billing_period: BillingPeriod$zodSchema,
   billing_period_count: z.int().optional(),
   collection_method: CollectionMethod$zodSchema.optional(),
-  commitment_amount: z.string().optional(),
+  commitment_amount: z.string().optional().describe(
+    "CommitmentAmount is the minimum amount a customer commits to paying for a billing period",
+  ),
   commitment_duration: BillingPeriod$zodSchema.optional(),
   coupons: z.array(z.string()).optional(),
-  credit_grants: z.array(DtoCreateCreditGrantRequest$zodSchema).optional(),
+  credit_grants: z.array(DtoCreateCreditGrantRequest$zodSchema).optional()
+    .describe("Credit grants to be applied when subscription is created"),
   currency: z.string(),
-  customer_id: z.string().optional(),
-  customer_timezone: z.string().optional(),
-  enable_true_up: z.boolean().optional(),
+  customer_id: z.string().optional().describe(
+    "customer_id is the flexprice customer id\nand it is prioritized over external_customer_id in case both are provided.",
+  ),
+  customer_timezone: z.string().optional().describe(
+    "Timezone of the customer.\nIf not set, the default value is UTC.",
+  ),
+  enable_true_up: z.boolean().optional().describe(
+    "Enable Commitment True Up Fee",
+  ),
   end_date: z.string().optional(),
-  external_customer_id: z.string().optional(),
+  external_customer_id: z.string().optional().describe(
+    "external_customer_id is the customer id in your DB\nand must be same as what you provided as external_id while creating the customer in flexprice.",
+  ),
   gateway_payment_method_id: z.string().optional(),
   invoice_billing: InvoiceBilling$zodSchema.optional(),
+  invoicing_customer_external_id: z.string().optional().describe(
+    "invoicing_customer_external_id is the external ID of the customer to use for invoicing.\nResolved internally to an internal customer ID via external ID lookup.\nMutually exclusive with invoicing_customer_id.",
+  ),
+  invoicing_customer_id: z.string().optional().describe(
+    "invoicing_customer_id is the FlexPrice customer ID to use for invoicing.\nThis can differ from the subscription customer (e.g., a billing entity invoicing on behalf of another customer).\nMutually exclusive with invoicing_customer_external_id.",
+  ),
   line_item_commitments: z.record(
     z.string(),
     DtoLineItemCommitmentConfig$zodSchema,
-  ).optional(),
+  ).optional().describe(
+    "LineItemCommitments allows setting commitment configuration per line item (keyed by price_id)",
+  ),
   line_item_coupons: z.record(z.string(), z.array(z.string())).optional(),
-  line_items: z.array(DtoCreateSubscriptionLineItemRequest$zodSchema)
-    .optional(),
+  line_items: z.array(DtoCreateSubscriptionLineItemRequest$zodSchema).optional()
+    .describe(
+      "LineItems are extra line items to add at creation (each with price_id or price), in addition to plan prices",
+    ),
   lookup_key: z.string().optional(),
   metadata: z.record(z.string(), z.string()).optional(),
-  overage_factor: z.string().optional(),
+  overage_factor: z.string().optional().describe(
+    "OverageFactor is a multiplier applied to usage beyond the commitment amount",
+  ),
   override_entitlements: z.array(DtoOverrideEntitlementRequest$zodSchema)
-    .optional(),
-  override_line_items: z.array(DtoOverrideLineItemRequest$zodSchema).optional(),
-  parent_subscription_id: z.string().optional(),
+    .optional().describe(
+      "OverrideEntitlements allows customizing specific entitlements for this subscription",
+    ),
+  override_line_items: z.array(DtoOverrideLineItemRequest$zodSchema).optional()
+    .describe(
+      "OverrideLineItems allows customizing specific prices for this subscription",
+    ),
+  parent_subscription_id: z.string().optional().describe(
+    "ParentSubscriptionID is the parent subscription ID for hierarchy (e.g. child subscription under a parent)",
+  ),
   payment_behavior: PaymentBehavior$zodSchema.optional(),
   payment_terms: PaymentTerms$zodSchema.optional(),
-  phases: z.array(DtoSubscriptionPhaseCreateRequest$zodSchema).optional(),
+  phases: z.array(DtoSubscriptionPhaseCreateRequest$zodSchema).optional()
+    .describe(
+      "Phases represents subscription phases to be created with the subscription",
+    ),
   plan_id: z.string(),
   proration_behavior: ProrationBehavior$zodSchema.optional(),
   start_date: z.string().optional(),
   subscription_status: SubscriptionStatus$zodSchema.optional(),
-  tax_rate_overrides: z.array(DtoTaxRateOverride$zodSchema).optional(),
+  tax_rate_overrides: z.array(DtoTaxRateOverride$zodSchema).optional().describe(
+    "tax_rate_overrides is the tax rate overrides\tto be applied to the subscription",
+  ),
   trial_end: z.string().optional(),
   trial_start: z.string().optional(),
 });

package/src/models/dtocreditgrantresponse.ts

@@ -58,7 +58,9 @@ export const DtoCreditGrantResponse$zodSchema: z.ZodType<
   DtoCreditGrantResponse
 > = z.object({
   cadence: CreditGrantCadence$zodSchema.optional(),
-  conversion_rate: z.string().optional(),
+  conversion_rate: z.string().optional().describe(
+    "amount in the currency =  number of credits * conversion_rate\nex if conversion_rate is 1, then 1 USD = 1 credit\nex if conversion_rate is 2, then 1 USD = 0.5 credits\nex if conversion_rate is 0.5, then 1 USD = 2 credits",
+  ),
   created_at: z.string().optional(),
   created_by: z.string().optional(),
   credit_grant_anchor: z.string().optional(),
@@ -80,7 +82,9 @@ export const DtoCreditGrantResponse$zodSchema: z.ZodType<
   status: Status$zodSchema.optional(),
   subscription_id: z.string().optional(),
   tenant_id: z.string().optional(),
-  topup_conversion_rate: z.string().optional(),
+  topup_conversion_rate: z.string().optional().describe(
+    "topup_conversion_rate is the conversion rate for the topup to the currency\nex if topup_conversion_rate is 1, then 1 USD = 1 credit\nex if topup_conversion_rate is 2, then 1 USD = 0.5 credits\nex if topup_conversion_rate is 0.5, then 1 USD = 2 credits",
+  ),
   updated_at: z.string().optional(),
   updated_by: z.string().optional(),
 });