@flexprice/mcp-server 2.0.10 → 2.0.12

package/src/models/dtocustomanalyticitem.ts

@@ -14,9 +14,15 @@ export type DtoCustomAnalyticItem = {
 
 export const DtoCustomAnalyticItem$zodSchema: z.ZodType<DtoCustomAnalyticItem> =
   z.object({
-    feature_name: z.string().optional(),
+    feature_name: z.string().optional().describe(
+      "Name of the feature this applies to",
+    ),
     id: z.string().optional(),
-    name: z.string().optional(),
-    type: z.string().optional(),
+    name: z.string().optional().describe(
+      "Calculation name (e.g., \"Revenue per Minute\")",
+    ),
+    type: z.string().optional().describe(
+      "\"feature\", \"meter\", \"event_name\"",
+    ),
     value: z.string().optional(),
   });

package/src/models/dtocustomerinvoicesummary.ts

@@ -20,14 +20,34 @@ export type DtoCustomerInvoiceSummary = {
 export const DtoCustomerInvoiceSummary$zodSchema: z.ZodType<
   DtoCustomerInvoiceSummary
 > = z.object({
-  currency: z.string().optional(),
-  customer_id: z.string().optional(),
-  overdue_invoice_count: z.int().optional(),
-  total_invoice_count: z.int().optional(),
-  total_overdue_amount: z.string().optional(),
-  total_revenue_amount: z.string().optional(),
-  total_unpaid_amount: z.string().optional(),
-  unpaid_fixed_charges: z.string().optional(),
-  unpaid_invoice_count: z.int().optional(),
-  unpaid_usage_charges: z.string().optional(),
+  currency: z.string().optional().describe(
+    "currency is the three-letter ISO currency code for this summary",
+  ),
+  customer_id: z.string().optional().describe(
+    "customer_id is the unique identifier of the customer",
+  ),
+  overdue_invoice_count: z.int().optional().describe(
+    "overdue_invoice_count is the number of overdue invoices for this customer in this currency",
+  ),
+  total_invoice_count: z.int().optional().describe(
+    "total_invoice_count is the total number of invoices for this customer in this currency",
+  ),
+  total_overdue_amount: z.string().optional().describe(
+    "total_overdue_amount is the total amount of overdue invoices in this currency",
+  ),
+  total_revenue_amount: z.string().optional().describe(
+    "total_revenue_amount is the total revenue generated from this customer in this currency",
+  ),
+  total_unpaid_amount: z.string().optional().describe(
+    "total_unpaid_amount is the total amount of unpaid invoices in this currency",
+  ),
+  unpaid_fixed_charges: z.string().optional().describe(
+    "unpaid_fixed_charges is the total amount of unpaid fixed charges in this currency",
+  ),
+  unpaid_invoice_count: z.int().optional().describe(
+    "unpaid_invoice_count is the number of unpaid invoices for this customer in this currency",
+  ),
+  unpaid_usage_charges: z.string().optional().describe(
+    "unpaid_usage_charges is the total amount of unpaid usage-based charges in this currency",
+  ),
 });

package/src/models/dtocustomermulticurrencyinvoicesummary.ts

@@ -17,7 +17,13 @@ export type DtoCustomerMultiCurrencyInvoiceSummary = {
 export const DtoCustomerMultiCurrencyInvoiceSummary$zodSchema: z.ZodType<
   DtoCustomerMultiCurrencyInvoiceSummary
 > = z.object({
-  customer_id: z.string().optional(),
-  default_currency: z.string().optional(),
-  summaries: z.array(DtoCustomerInvoiceSummary$zodSchema).optional(),
+  customer_id: z.string().optional().describe(
+    "customer_id is the unique identifier of the customer",
+  ),
+  default_currency: z.string().optional().describe(
+    "default_currency is the primary currency for this customer",
+  ),
+  summaries: z.array(DtoCustomerInvoiceSummary$zodSchema).optional().describe(
+    "summaries contains the invoice summaries for each currency",
+  ),
 });

package/src/models/dtocustomerresponse.ts

@@ -33,22 +33,43 @@ export type DtoCustomerResponse = {
 
 export const DtoCustomerResponse$zodSchema: z.ZodType<DtoCustomerResponse> = 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(),
+    address_city: z.string().optional().describe(
+      "AddressCity is the city of the customer's address",
+    ),
+    address_country: z.string().optional().describe(
+      "AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2)",
+    ),
+    address_line1: z.string().optional().describe(
+      "AddressLine1 is the first line of the customer's address",
+    ),
+    address_line2: z.string().optional().describe(
+      "AddressLine2 is the second line of the customer's address",
+    ),
+    address_postal_code: z.string().optional().describe(
+      "AddressPostalCode is the postal code of the customer's address",
+    ),
+    address_state: z.string().optional().describe(
+      "AddressState is the state of the customer's address",
+    ),
     created_at: z.string().optional(),
     created_by: z.string().optional(),
-    email: z.string().optional(),
-    environment_id: z.string().optional(),
-    external_id: z.string().optional(),
-    id: z.string().optional(),
-    metadata: z.record(z.string(), z.string()).optional(),
-    name: z.string().optional(),
-    parent_customer: z.lazy(() => DtoCustomerResponse$zodSchema).optional(),
-    parent_customer_id: z.string().optional(),
+    email: z.string().optional().describe("Email is the email of the customer"),
+    environment_id: z.string().optional().describe(
+      "EnvironmentID is the environment identifier for the customer",
+    ),
+    external_id: z.string().optional().describe(
+      "ExternalID is the external identifier for the customer",
+    ),
+    id: z.string().optional().describe(
+      "ID is the unique identifier for the customer",
+    ),
+    metadata: z.record(z.string(), z.string()).optional().describe("Metadata"),
+    name: z.string().optional().describe("Name is the name of the customer"),
+    parent_customer: z.lazy(() => DtoCustomerResponse$zodSchema).optional()
+      .describe("Customer response object containing all customer information"),
+    parent_customer_id: z.string().optional().describe(
+      "Deprecated: Customer parent hierarchy is deprecated in favor of subscription-level hierarchy.\nRetained for backward compatibility; no hierarchy rules are enforced at the service layer.\nParentCustomerID is the parent customer identifier for the customer.",
+    ),
     status: Status$zodSchema.optional(),
     tenant_id: z.string().optional(),
     updated_at: z.string().optional(),

package/src/models/dtoentitlementresponse.ts

@@ -73,7 +73,9 @@ export const DtoEntitlementResponse$zodSchema: z.ZodType<
   is_soft_limit: z.boolean().optional(),
   parent_entitlement_id: z.string().optional(),
   plan: z.lazy(() => DtoPlanResponse$zodSchema).optional(),
-  plan_id: z.string().optional(),
+  plan_id: z.string().optional().describe(
+    "TODO: Remove this once we have a proper entitlement entity type",
+  ),
   start_date: z.string().optional(),
   static_value: z.string().optional(),
   status: Status$zodSchema.optional(),

package/src/models/dtogeteventsrequest.ts

@@ -22,17 +22,44 @@ export type DtoGetEventsRequest = {
 
 export const DtoGetEventsRequest$zodSchema: z.ZodType<DtoGetEventsRequest> = z
   .object({
-    end_time: z.string().optional(),
-    event_id: z.string().optional(),
-    event_name: z.string().optional(),
-    external_customer_id: z.string().optional(),
-    iter_first_key: z.string().optional(),
-    iter_last_key: z.string().optional(),
-    offset: z.int().optional(),
-    order: z.string().optional(),
-    page_size: z.int().optional(),
-    property_filters: z.record(z.string(), z.array(z.string())).optional(),
-    sort: z.string().optional(),
-    source: z.string().optional(),
-    start_time: z.string().optional(),
+    end_time: z.string().optional().describe(
+      "End time of the events to be fetched in ISO 8601 format\nDefaults to now if not provided",
+    ),
+    event_id: z.string().optional().describe(
+      "Event ID is the idempotency key for the event",
+    ),
+    event_name: z.string().optional().describe(
+      "Event name / Unique identifier for the event in your system",
+    ),
+    external_customer_id: z.string().optional().describe(
+      "Customer ID in your system that was sent with the event",
+    ),
+    iter_first_key: z.string().optional().describe(
+      "First key to iterate over the events",
+    ),
+    iter_last_key: z.string().optional().describe(
+      "Last key to iterate over the events",
+    ),
+    offset: z.int().optional().describe(
+      "Offset to fetch the events and is set to 0 by default",
+    ),
+    order: z.string().optional().describe(
+      "Order by condition. Allowed values (case sensitive): asc, desc (default: desc)",
+    ),
+    page_size: z.int().optional().describe(
+      "Page size to fetch the events and is set to 50 by default",
+    ),
+    property_filters: z.record(z.string(), z.array(z.string())).optional()
+      .describe(
+        "Property filters to filter the events by the keys in `properties` field of the event",
+      ),
+    sort: z.string().optional().describe(
+      "Sort by the field. Allowed values (case sensitive): timestamp, event_name (default: timestamp)",
+    ),
+    source: z.string().optional().describe(
+      "Source to filter the events by the source",
+    ),
+    start_time: z.string().optional().describe(
+      "Start time of the events to be fetched in ISO 8601 format\nDefaults to last 7 days from now if not provided",
+    ),
   });

package/src/models/dtogetpendingschedulesresponse.ts

@@ -19,6 +19,9 @@ export type DtoGetPendingSchedulesResponse = {
 export const DtoGetPendingSchedulesResponse$zodSchema: z.ZodType<
   DtoGetPendingSchedulesResponse
 > = z.object({
-  count: z.int().optional(),
-  schedules: z.array(DtoSubscriptionScheduleResponse$zodSchema).optional(),
+  count: z.int().optional().describe(
+    "count is the number of pending schedules",
+  ),
+  schedules: z.array(DtoSubscriptionScheduleResponse$zodSchema).optional()
+    .describe("schedules is the list of pending schedules"),
 }).describe("List of pending schedules for a subscription");

package/src/models/dtogetpreviewinvoicerequest.ts

@@ -14,8 +14,16 @@ export type DtoGetPreviewInvoiceRequest = {
 export const DtoGetPreviewInvoiceRequest$zodSchema: z.ZodType<
   DtoGetPreviewInvoiceRequest
 > = z.object({
-  hide_zero_charges_line_items: z.boolean().default(false),
-  period_end: z.string().optional(),
-  period_start: z.string().optional(),
-  subscription_id: z.string(),
+  hide_zero_charges_line_items: z.boolean().default(false).describe(
+    "hide_zero_charges_line_items indicates whether to hide line items with zero cost",
+  ),
+  period_end: z.string().optional().describe(
+    "period_end is the optional end date of the period to preview",
+  ),
+  period_start: z.string().optional().describe(
+    "period_start is the optional start date of the period to preview",
+  ),
+  subscription_id: z.string().describe(
+    "subscription_id is the unique identifier of the subscription to preview invoice for",
+  ),
 });

package/src/models/dtogetusageanalyticsrequest.ts

@@ -21,11 +21,18 @@ export const DtoGetUsageAnalyticsRequest$zodSchema: z.ZodType<
   DtoGetUsageAnalyticsRequest
 > = z.object({
   end_time: z.string().optional(),
-  expand: z.array(z.string()).optional(),
+  expand: z.array(z.string()).optional().describe(
+    "allowed values: \"price\", \"meter\", \"feature\", \"subscription_line_item\",\"plan\",\"addon\"",
+  ),
   external_customer_id: z.string(),
   feature_ids: z.array(z.string()).optional(),
-  group_by: z.array(z.string()).optional(),
-  property_filters: z.record(z.string(), z.array(z.string())).optional(),
+  group_by: z.array(z.string()).optional().describe(
+    "allowed values: \"source\", \"feature_id\", \"properties.<field_name>\"",
+  ),
+  property_filters: z.record(z.string(), z.array(z.string())).optional()
+    .describe(
+      "Property filters to filter the events by the keys in `properties` field of the event",
+    ),
   sources: z.array(z.string()).optional(),
   start_time: z.string().optional(),
   window_size: WindowSize$zodSchema.optional(),

package/src/models/dtogetusagebymeterrequest.ts

@@ -20,7 +20,9 @@ export type DtoGetUsageByMeterRequest = {
 export const DtoGetUsageByMeterRequest$zodSchema: z.ZodType<
   DtoGetUsageByMeterRequest
 > = z.object({
-  billing_anchor: z.string().optional(),
+  billing_anchor: z.string().optional().describe(
+    "BillingAnchor enables custom monthly billing periods for meter usage aggregation.\n\nUsage guidelines:\n- Only effective when WindowSize = \"MONTH\"\n- For other window sizes (DAY, HOUR, WEEK), this field is ignored\n- When nil, uses standard calendar months (1st to 1st)\n- When provided, creates custom monthly periods (e.g., 5th to 5th)\n\nCommon use cases:\n- Subscription billing periods that don't align with calendar months\n- Customer-specific billing cycles (e.g., signed up on 15th)\n- Multi-tenant systems with different billing anchor dates\n\nExample: If BillingAnchor = \"2024-03-05T14:30:45Z\" and WindowSize = \"MONTH\":\n  - March period: 2024-03-05 14:30:45 to 2024-04-05 14:30:45\n  - April period: 2024-04-05 14:30:45 to 2024-05-05 14:30:45",
+  ),
   bucket_size: WindowSize$zodSchema.optional(),
   customer_id: z.string().optional(),
   end_time: z.string().optional(),

package/src/models/dtogetusagebysubscriptionresponse.ts

@@ -28,12 +28,18 @@ export const DtoGetUsageBySubscriptionResponse$zodSchema: z.ZodType<
   amount: z.number().optional(),
   charges: z.array(DtoSubscriptionUsageByMetersResponse$zodSchema).optional(),
   commitment_amount: z.number().optional(),
-  commitment_utilized: z.number().optional(),
+  commitment_utilized: z.number().optional().describe(
+    "Amount of commitment used",
+  ),
   currency: z.string().optional(),
   display_amount: z.string().optional(),
   end_time: z.string().optional(),
-  has_overage: z.boolean().optional(),
-  overage_amount: z.number().optional(),
+  has_overage: z.boolean().optional().describe(
+    "Whether any usage exceeded commitment",
+  ),
+  overage_amount: z.number().optional().describe(
+    "Amount charged at overage rate",
+  ),
   overage_factor: z.number().optional(),
   start_time: z.string().optional(),
 });

package/src/models/dtogetusagerequest.ts

@@ -28,16 +28,22 @@ export type DtoGetUsageRequest = {
 export const DtoGetUsageRequest$zodSchema: z.ZodType<DtoGetUsageRequest> = z
   .object({
     aggregation_type: AggregationType$zodSchema,
-    billing_anchor: z.string().optional(),
+    billing_anchor: z.string().optional().describe(
+      "BillingAnchor enables custom monthly billing periods for usage aggregation.\n\nWhen to use:\n- WindowSize = \"MONTH\" AND you need custom monthly periods (not calendar months)\n- Subscription billing that doesn't align with calendar months\n- Example: Customer signed up on 15th, so billing periods are 15th to 15th\n\nWhen NOT to use:\n- WindowSize != \"MONTH\" (ignored for DAY, HOUR, WEEK, etc.)\n- Standard calendar-based billing (1st to 1st of each month)\n\nExample values:\n- \"2024-03-05T14:30:45.123456789Z\" (5th of each month at 2:30:45 PM)\n- \"2024-01-15T00:00:00Z\" (15th of each month at midnight)\n- \"2024-02-29T12:00:00Z\" (29th of each month at noon - handles leap years)",
+    ),
     bucket_size: WindowSize$zodSchema.optional(),
     customer_id: z.string().optional(),
     end_time: z.string().optional(),
     event_name: z.string(),
     external_customer_id: z.string().optional(),
     filters: z.record(z.string(), z.array(z.string())).optional(),
-    group_by_property: z.string().optional(),
+    group_by_property: z.string().optional().describe(
+      "GroupByProperty is the property name in event.properties to group by before aggregating.\nWhen set, aggregation is applied per unique value of this property within each bucket,\nthen the per-group results are summed to produce the bucket total.",
+    ),
     multiplier: z.string().optional(),
-    property_name: z.string().optional(),
+    property_name: z.string().optional().describe(
+      "will be empty/ignored in case of COUNT",
+    ),
     start_time: z.string().optional(),
     window_size: WindowSize$zodSchema.optional(),
   });

package/src/models/dtoingesteventrequest.ts

@@ -20,7 +20,11 @@ export const DtoIngestEventRequest$zodSchema: z.ZodType<DtoIngestEventRequest> =
     event_id: z.string().optional(),
     event_name: z.string(),
     external_customer_id: z.string(),
-    properties: z.record(z.string(), z.string()).optional(),
+    properties: z.record(z.string(), z.string()).optional().describe(
+      "Handled separately for dynamic columns",
+    ),
     source: z.string().optional(),
-    timestamp: z.string().optional(),
+    timestamp: z.string().optional().describe(
+      "Handled separately due to parsing",
+    ),
   });

package/src/models/dtointegrationentitymapping.ts

@@ -34,6 +34,8 @@ export type DtoIntegrationEntityMapping = { id: string; provider: Provider };
 export const DtoIntegrationEntityMapping$zodSchema: z.ZodType<
   DtoIntegrationEntityMapping
 > = z.object({
-  id: z.string(),
-  provider: Provider$zodSchema,
+  id: z.string().describe("id is the external entity ID from the provider"),
+  provider: Provider$zodSchema.describe(
+    "provider is the integration provider name (e.g., \"stripe\", \"razorpay\")",
+  ),
 }).describe("Integration entity mapping for external provider systems");

package/src/models/dtoinvoicelineitemcoupon.ts

@@ -15,5 +15,5 @@ export const DtoInvoiceLineItemCoupon$zodSchema: z.ZodType<
 > = z.object({
   coupon_association_id: z.string().optional(),
   coupon_id: z.string(),
-  line_item_id: z.string(),
+  line_item_id: z.string().describe("price_id used to match the line item"),
 });

package/src/models/dtoinvoicelineitempreview.ts

@@ -17,11 +17,17 @@ export type DtoInvoiceLineItemPreview = {
 export const DtoInvoiceLineItemPreview$zodSchema: z.ZodType<
   DtoInvoiceLineItemPreview
 > = z.object({
-  amount: z.string().optional(),
-  description: z.string().optional(),
-  is_proration: z.boolean().optional(),
-  period_end: z.string().optional(),
-  period_start: z.string().optional(),
-  quantity: z.string().optional(),
-  unit_price: z.string().optional(),
+  amount: z.string().optional().describe("amount for this line item"),
+  description: z.string().optional().describe("description of the line item"),
+  is_proration: z.boolean().optional().describe(
+    "is_proration indicates if this line item is a proration",
+  ),
+  period_end: z.string().optional().describe(
+    "period_end for this line item (if applicable)",
+  ),
+  period_start: z.string().optional().describe(
+    "period_start for this line item (if applicable)",
+  ),
+  quantity: z.string().optional().describe("quantity for this line item"),
+  unit_price: z.string().optional().describe("unit_price for this line item"),
 });

package/src/models/dtoinvoicelineitemresponse.ts

@@ -66,15 +66,21 @@ export const DtoInvoiceLineItemResponse$zodSchema: z.ZodType<
   environment_id: z.string().optional(),
   id: z.string().optional(),
   invoice_id: z.string().optional(),
-  invoice_level_discount: z.string().optional(),
-  line_item_discount: z.string().optional(),
+  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(),
-  prepaid_credits_applied: z.string().optional(),
+  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(),
   price_type: z.string().optional(),
   price_unit: z.string().optional(),
@@ -86,6 +92,10 @@ export const DtoInvoiceLineItemResponse$zodSchema: z.ZodType<
   tenant_id: z.string().optional(),
   updated_at: z.string().optional(),
   updated_by: z.string().optional(),
-  usage_analytics: z.array(DtoSourceUsageItem$zodSchema).optional(),
-  usage_breakdown: z.array(DtoUsageBreakdownItem$zodSchema).optional(),
+  usage_analytics: z.array(DtoSourceUsageItem$zodSchema).optional().describe(
+    "usage_analytics contains usage analytics for this line item (legacy - grouped by source)",
+  ),
+  usage_breakdown: z.array(DtoUsageBreakdownItem$zodSchema).optional().describe(
+    "usage_breakdown contains flexible usage breakdown for this line item (supports any grouping)",
+  ),
 });

package/src/models/dtoinvoicepreview.ts

@@ -19,10 +19,21 @@ export type DtoInvoicePreview = {
 
 export const DtoInvoicePreview$zodSchema: z.ZodType<DtoInvoicePreview> = z
   .object({
-    currency: z.string().optional(),
-    due_date: z.string().optional(),
-    line_items: z.array(DtoInvoiceLineItemPreview$zodSchema).optional(),
-    subtotal: z.string().optional(),
-    tax_amount: z.string().optional(),
-    total: z.string().optional(),
+    currency: z.string().optional().describe(
+      "currency is the currency for all amounts",
+    ),
+    due_date: z.string().optional().describe(
+      "due_date is when the invoice would be due",
+    ),
+    line_items: z.array(DtoInvoiceLineItemPreview$zodSchema).optional()
+      .describe("line_items contains preview of line items"),
+    subtotal: z.string().optional().describe(
+      "subtotal is the subtotal amount before taxes",
+    ),
+    tax_amount: z.string().optional().describe(
+      "tax_amount is the total tax amount",
+    ),
+    total: z.string().optional().describe(
+      "total is the total amount including taxes",
+    ),
   });

package/src/models/dtoinvoiceresponse.ts

@@ -79,51 +79,122 @@ export type DtoInvoiceResponse = {
 
 export const DtoInvoiceResponse$zodSchema: z.ZodType<DtoInvoiceResponse> = z
   .object({
-    adjustment_amount: z.string().optional(),
-    amount_due: z.string().optional(),
-    amount_paid: z.string().optional(),
-    amount_remaining: z.string().optional(),
-    billing_period: z.string().optional(),
-    billing_reason: z.string().optional(),
-    billing_sequence: z.int().optional(),
+    adjustment_amount: z.string().optional().describe(
+      "adjustment_amount is the total sum of credit notes of type \"adjustment\".\nThese are non-cash reductions applied to the invoice (e.g. goodwill credit, billing correction).",
+    ),
+    amount_due: z.string().optional().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 already been paid towards this invoice",
+    ),
+    amount_remaining: z.string().optional().describe(
+      "amount_remaining is the outstanding amount still owed on this invoice (calculated as amount_due minus amount_paid)",
+    ),
+    billing_period: z.string().optional().describe(
+      "billing_period describes the billing period this invoice covers (e.g., \"January 2024\", \"Q1 2024\")",
+    ),
+    billing_reason: z.string().optional().describe(
+      "billing_reason indicates why this invoice was generated (e.g., \"subscription_billing\", \"manual_charge\")",
+    ),
+    billing_sequence: z.int().optional().describe(
+      "billing_sequence is the sequential number indicating the billing cycle for subscription invoices",
+    ),
     coupon_applications: z.array(DtoCouponApplicationResponse$zodSchema)
-      .optional(),
+      .optional().describe(
+        "coupon_applications contains the coupon applications associated with this invoice (overrides embedded field)",
+      ),
     created_at: z.string().optional(),
     created_by: z.string().optional(),
-    currency: z.string().optional(),
-    customer: DtoCustomerResponse$zodSchema.optional(),
-    customer_id: z.string().optional(),
-    description: z.string().optional(),
-    due_date: z.string().optional(),
-    environment_id: z.string().optional(),
-    finalized_at: z.string().optional(),
-    id: z.string().optional(),
-    idempotency_key: z.string().optional(),
-    invoice_number: z.string().optional(),
-    invoice_pdf_url: z.string().optional(),
+    currency: z.string().optional().describe(
+      "currency is the three-letter ISO currency code (e.g., USD, EUR, GBP) that applies to all monetary amounts on this invoice",
+    ),
+    customer: DtoCustomerResponse$zodSchema.optional().describe(
+      "Customer response object containing all customer information",
+    ),
+    customer_id: z.string().optional().describe(
+      "customer_id is the ID of the customer who will receive this invoice",
+    ),
+    description: z.string().optional().describe(
+      "description is an optional description or notes about this invoice",
+    ),
+    due_date: z.string().optional().describe(
+      "due_date is the date when payment for this invoice is due",
+    ),
+    environment_id: z.string().optional().describe(
+      "environment_id is the ID of the environment this invoice belongs to (for multi-environment setups)",
+    ),
+    finalized_at: z.string().optional().describe(
+      "finalized_at is the timestamp when this invoice was finalized and made ready for payment",
+    ),
+    id: z.string().optional().describe(
+      "id is the unique identifier for this invoice",
+    ),
+    idempotency_key: z.string().optional().describe(
+      "idempotency_key is a unique key used to prevent duplicate invoice creation when retrying API calls",
+    ),
+    invoice_number: z.string().optional().describe(
+      "invoice_number is the human-readable invoice number displayed to customers (e.g., INV-2024-001)",
+    ),
+    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_items: z.array(DtoInvoiceLineItemResponse$zodSchema).optional(),
+    line_items: z.array(DtoInvoiceLineItemResponse$zodSchema).optional()
+      .describe(
+        "line_items contains the individual items that make up this invoice (overrides embedded field)",
+      ),
     metadata: z.record(z.string(), z.string()).optional(),
-    overpaid_amount: z.string().optional(),
-    paid_at: z.string().optional(),
+    overpaid_amount: z.string().optional().describe(
+      "overpaid_amount is the amount overpaid if payment_status is OVERPAID (amount_paid - total)",
+    ),
+    paid_at: z.string().optional().describe(
+      "paid_at is the timestamp when this invoice was fully paid",
+    ),
     payment_status: PaymentStatus$zodSchema.optional(),
-    period_end: z.string().optional(),
-    period_start: z.string().optional(),
-    recalculated_invoice_id: z.string().optional(),
-    refunded_amount: z.string().optional(),
+    period_end: z.string().optional().describe(
+      "period_end is the end date of the billing period covered by this invoice",
+    ),
+    period_start: z.string().optional().describe(
+      "period_start is the start date of the billing period covered by this invoice",
+    ),
+    recalculated_invoice_id: z.string().optional().describe(
+      "recalculated_invoice_id is the ID of the replacement invoice created when this invoice was voided and recalculated.\nWhen set, it forms a parent→child link from this (voided) invoice to the new replacement invoice.",
+    ),
+    refunded_amount: z.string().optional().describe(
+      "refunded_amount is the total sum of credit notes of type \"refund\".\nThese are actual refunds issued to the customer.",
+    ),
     status: Status$zodSchema.optional(),
     subscription: z.lazy(() => DtoSubscriptionResponse$zodSchema).optional(),
-    subscription_id: z.string().optional(),
-    subtotal: z.string().optional(),
-    taxes: z.array(DtoTaxAppliedResponse$zodSchema).optional(),
+    subscription_id: z.string().optional().describe(
+      "subscription_id is the ID of the subscription this invoice is associated with (only present for subscription-based invoices)",
+    ),
+    subtotal: z.string().optional().describe(
+      "subtotal is the sum of all line items before any taxes, discounts, or additional fees",
+    ),
+    taxes: z.array(DtoTaxAppliedResponse$zodSchema).optional().describe(
+      "tax_applied_records contains the tax applied records associated with this invoice",
+    ),
     tenant_id: z.string().optional(),
-    total: z.string().optional(),
-    total_discount: z.string().optional(),
-    total_prepaid_credits_applied: z.string().optional(),
-    total_tax: z.string().optional(),
+    total: z.string().optional().describe(
+      "total is the final amount including taxes, fees, and discounts",
+    ),
+    total_discount: z.string().optional().describe(
+      "total_discount is the sum of all coupon discounts applied to the invoice",
+    ),
+    total_prepaid_credits_applied: z.string().optional().describe(
+      "total_prepaid_credits_applied is the total amount of prepaid credits applied to this invoice.",
+    ),
+    total_tax: z.string().optional().describe(
+      "total_tax is the sum of all taxes combined at the invoice level.",
+    ),
     updated_at: z.string().optional(),
     updated_by: z.string().optional(),
-    version: z.int().optional(),
-    voided_at: z.string().optional(),
+    version: z.int().optional().describe(
+      "version is the version number for tracking changes to this invoice",
+    ),
+    voided_at: z.string().optional().describe(
+      "voided_at is the timestamp when this invoice was voided or cancelled",
+    ),
   });