dto

type ActivateDraftSubscriptionRequest struct {
	// start_date is the new start date for the subscription when activating
	StartDate *time.Time `json:"start_date" validate:"required"`
}

type AddAddonRequest struct {
	SubscriptionID                string `json:"subscription_id" validate:"required"`
	AddAddonToSubscriptionRequest `json:",inline"`
}

type AddAddonToSubscriptionRequest struct {
	AddonID   string                 `json:"addon_id" validate:"required"`
	StartDate *time.Time             `json:"start_date,omitempty"`
	Metadata  map[string]interface{} `json:"metadata"`

	// LineItemCommitments allows setting commitment configuration per addon line item (keyed by price_id)
	LineItemCommitments map[string]*LineItemCommitmentConfig `json:"line_item_commitments,omitempty" validate:"omitempty,dive"`

	// SkipEntityValidation is used to skip the entitlement check for the addon
	// This is used to add an addon to a subscription without checking the entitlement compatibility
	// This is used when we are adding an addon to a subscription that already has an active instance of the addon
	// In that case we don't need to check the entitlement compatibility
	SkipEntityValidation bool `json:"-"`
}

type AddonAssociationResponse struct {
	*addonassociation.AddonAssociation
	Addon        *AddonResponse        `json:"addon,omitempty"`
	Subscription *SubscriptionResponse `json:"subscription,omitempty"`
}

type AddonResponse struct {
	*addon.Addon

	// Optional expanded fields
	Prices       []*PriceResponse       `json:"prices,omitempty"`
	Entitlements []*EntitlementResponse `json:"entitlements,omitempty"`
}

type Address struct {
	Line1      string `json:"address_line1" validate:"omitempty,max=255"`
	Line2      string `json:"address_line2" validate:"omitempty,max=255"`
	City       string `json:"address_city" validate:"omitempty,max=100"`
	State      string `json:"address_state" validate:"omitempty,max=100"`
	PostalCode string `json:"address_postal_code" validate:"omitempty,max=20"`
	Country    string `json:"address_country" validate:"omitempty,len=2,iso3166_1_alpha2"`
}

type AggregatedEntitlement struct {
	IsEnabled        bool                              `json:"is_enabled"`
	UsageLimit       *int64                            `json:"usage_limit,omitempty"`
	IsSoftLimit      bool                              `json:"is_soft_limit"`
	UsageResetPeriod types.EntitlementUsageResetPeriod `json:"usage_reset_period,omitempty"`
	StaticValues     []string                          `json:"static_values,omitempty"` // For static/SLA features
}

type AggregatedFeature struct {
	Feature     *FeatureResponse       `json:"feature"`
	Entitlement *AggregatedEntitlement `json:"entitlement"`
	Sources     []*EntitlementSource   `json:"sources"`
}

type AlertConfig struct {
	Threshold *Threshold `json:"threshold,omitempty"`
}

type AlertLogResponse struct {
	ID               string                `json:"id"`
	EntityType       types.AlertEntityType `json:"entity_type"`
	EntityID         string                `json:"entity_id"`
	ParentEntityType *string               `json:"parent_entity_type,omitempty"`
	ParentEntityID   *string               `json:"parent_entity_id,omitempty"`
	CustomerID       *string               `json:"customer_id,omitempty"`
	AlertType        types.AlertType       `json:"alert_type"`
	AlertStatus      types.AlertState      `json:"alert_status"`
	AlertInfo        types.AlertInfo       `json:"alert_info"`
	EnvironmentID    string                `json:"environment_id"`
	TenantID         string                `json:"tenant_id"`
	Status           string                `json:"status"`
	CreatedAt        time.Time             `json:"created_at"`
	UpdatedAt        time.Time             `json:"updated_at"`
	CreatedBy        string                `json:"created_by"`
	UpdatedBy        string                `json:"updated_by"`

	// Expanded fields
	Customer *CustomerResponse `json:"customer,omitempty"`
	Wallet   *WalletResponse   `json:"wallet,omitempty"`
	Feature  *FeatureResponse  `json:"feature,omitempty"`
}

type AssignTenantRequest struct {
	UserID   string `json:"user_id" validate:"required,uuid"`
	TenantID string `json:"tenant_id" validate:"required,uuid"`
}

type AuthResponse struct {
	Token    string `json:"token"`
	UserID   string `json:"user_id"`
	TenantID string `json:"tenant_id"`
}

type BillingCycleInfo struct {
	// period_start is the start of the new billing period
	PeriodStart time.Time `json:"period_start"`

	// period_end is the end of the new billing period
	PeriodEnd time.Time `json:"period_end"`

	// billing_anchor is the new billing anchor
	BillingAnchor time.Time `json:"billing_anchor"`

	// billing_cadence is the billing cadence
	BillingCadence types.BillingCadence `json:"billing_cadence"`

	// billing_period is the billing period
	BillingPeriod types.BillingPeriod `json:"billing_period"`

	// billing_period_count is the billing period count
	BillingPeriodCount int `json:"billing_period_count" default:"1"`
}

type BillingPeriodInfo struct {
	StartTime time.Time `json:"start_time"`
	EndTime   time.Time `json:"end_time"`
	Period    string    `json:"period"` // e.g., "monthly", "yearly"
}

type BulkIngestEventRequest struct {
	Events []*IngestEventRequest `json:"events" validate:"required,min=1,max=1000"`
}

type CalculateROIRequest struct {
	// SubscriptionID is required to get subscription details
	SubscriptionID string `json:"subscription_id" validate:"required"`

	// MeterID references the meter to track usage
	MeterID string `json:"meter_id,omitempty"`

	// PriceID references the price configuration
	PriceID string `json:"price_id,omitempty"`

	// Optional time range. If not provided, uses entire subscription period
	PeriodStart *time.Time `json:"period_start,omitempty"`
	PeriodEnd   *time.Time `json:"period_end,omitempty"`
}

type CancelFutureSubscriptionGrantsRequest struct {
	SubscriptionID string     `json:"subscription_id" binding:"required"`
	EffectiveDate  *time.Time `json:"effective_date,omitempty"`
}

type CancelScheduleRequest struct {
	// schedule_id is the ID of the schedule to cancel (optional if subscription_id and schedule_type are provided)
	ScheduleID *string `json:"schedule_id,omitempty"`

	// subscription_id is the ID of the subscription (required if schedule_id is not provided)
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// schedule_type is the type of schedule to cancel (required if schedule_id is not provided)
	ScheduleType *types.SubscriptionScheduleChangeType `json:"schedule_type,omitempty"`
}

type CancelScheduleResponse struct {
	// status is the new status (should be "cancelled")
	Status types.ScheduleStatus `json:"status"`

	// message is a confirmation message
	Message string `json:"message"`
}

type CancelSubscriptionRequest struct {

	// ProrationBehavior controls how proration is handled.
	ProrationBehavior types.ProrationBehavior `json:"proration_behavior,omitempty"`

	// CancellationType determines when the cancellation takes effect
	CancellationType types.CancellationType `json:"cancellation_type" validate:"required"`

	// Reason for cancellation (for audit and business intelligence)
	Reason string `json:"reason,omitempty"`

	//SuppressWebhook is an internal flag to suppress webhook events during cancellation.
	SuppressWebhook bool `json:"-,omitempty"`
}

type CancelSubscriptionResponse struct {
	// Basic cancellation info
	SubscriptionID   string                   `json:"subscription_id"`
	CancellationType types.CancellationType   `json:"cancellation_type"`
	EffectiveDate    time.Time                `json:"effective_date"`
	Status           types.SubscriptionStatus `json:"status"`
	Reason           string                   `json:"reason,omitempty"`

	// Proration details
	ProrationInvoice  *InvoiceResponse  `json:"proration_invoice,omitempty"`
	ProrationDetails  []ProrationDetail `json:"proration_details"`
	TotalCreditAmount decimal.Decimal   `json:"total_credit_amount" swaggertype:"string"`

	// Response metadata
	Message     string    `json:"message"`
	ProcessedAt time.Time `json:"processed_at"`
}

type CardDetails struct {
	Brand       string `json:"brand"`
	Last4       string `json:"last4"`
	ExpMonth    int    `json:"exp_month"`
	ExpYear     int    `json:"exp_year"`
	Fingerprint string `json:"fingerprint"`
}

type ChargeSavedPaymentMethodRequest struct {
	CustomerID      string          `json:"customer_id" binding:"required"`
	PaymentMethodID string          `json:"payment_method_id" binding:"required"`
	Amount          decimal.Decimal `json:"amount" binding:"required"`
	Currency        string          `json:"currency" binding:"required"`
	InvoiceID       string          `json:"invoice_id,omitempty"`
	PaymentID       string          `json:"payment_id,omitempty"`
}

type CompleteOAuthRequest struct {
	Provider  types.OAuthProvider `json:"provider" binding:"required"`   // e.g., "quickbooks"
	SessionID string              `json:"session_id" binding:"required"` // Session ID from initiate OAuth
	Code      string              `json:"code" binding:"required"`       // OAuth authorization code from the provider
	State     string              `json:"state" binding:"required"`      // CSRF state token
	RealmID   string              `json:"realm_id"`                      // QuickBooks realm ID (required for QuickBooks, validated in Validate())
}

type CompleteOAuthResponse struct {
	Success      bool   `json:"success"`
	ConnectionID string `json:"connection_id"`
}

type ConnectionResponse struct {
	ID            string                 `json:"id"`
	Name          string                 `json:"name"`
	ProviderType  types.SecretProvider   `json:"provider_type"`
	EnvironmentID string                 `json:"environment_id"`
	TenantID      string                 `json:"tenant_id"`
	Status        types.Status           `json:"status"`
	Metadata      map[string]interface{} `json:"metadata,omitempty"`
	SyncConfig    *types.SyncConfig      `json:"sync_config,omitempty"`
	CreatedAt     string                 `json:"created_at"`
	UpdatedAt     string                 `json:"updated_at"`
	CreatedBy     string                 `json:"created_by"`
	UpdatedBy     string                 `json:"updated_by"`
}

type CostAnalyticItem struct {
	MeterID            string            `json:"meter_id"`
	MeterName          string            `json:"meter_name,omitempty"`
	Source             string            `json:"source,omitempty"`
	CustomerID         string            `json:"customer_id,omitempty"`
	ExternalCustomerID string            `json:"external_customer_id,omitempty"`
	Properties         map[string]string `json:"properties,omitempty"`

	// Aggregated metrics
	TotalCost     decimal.Decimal `json:"total_cost" swaggertype:"string"`
	TotalQuantity decimal.Decimal `json:"total_quantity" swaggertype:"string"`
	TotalEvents   int64           `json:"total_events"`

	// Breakdown
	CostByPeriod []CostPoint `json:"cost_by_period,omitempty"` // Time-series

	// Metadata
	Currency    string `json:"currency"`
	PriceID     string `json:"price_id,omitempty"`
	CostsheetID string `json:"costsheet_id,omitempty"`

	// Expanded data (populated when expand options are specified)
	Meter *meter.Meter `json:"meter,omitempty"`
	Price *price.Price `json:"price,omitempty"`
}

type CostBreakdownItem struct {
	// MeterID identifies the meter
	MeterID string `json:"meter_id"`

	// MeterName is the display name of the meter
	MeterName string `json:"meter_name"`

	// Cost is the calculated cost for this meter
	Cost decimal.Decimal `json:"cost" swaggertype:"string"`

	// Usage is the total usage for this meter in the period
	Usage decimal.Decimal `json:"usage" swaggertype:"string"`

	// Unit is the unit of measurement
	Unit string `json:"unit"`
}

type CostBreakdownResponse struct {
	// TotalCost is the sum of all meter costs
	TotalCost decimal.Decimal `json:"total_cost" swaggertype:"string"`

	// Items contains the breakdown by meter
	Items []CostBreakdownItem `json:"items"`

	// Period shows the time range for this calculation
	Period CostPeriod `json:"period"`
}

type CostBreakup struct {
	// EffectiveUnitCost is the per-unit cost based on the applicable tier
	EffectiveUnitCost decimal.Decimal
	// SelectedTierIndex is the index of the tier that was applied (-1 if no tiers)
	SelectedTierIndex int
	// TierUnitAmount is the unit amount of the selected tier
	TierUnitAmount decimal.Decimal
	// FinalCost is the total cost for the quantity
	FinalCost decimal.Decimal
}

type CostPeriod struct {
	StartTime time.Time `json:"start_time"`
	EndTime   time.Time `json:"end_time"`
}

type CostPoint struct {
	Timestamp  time.Time       `json:"timestamp"`
	Cost       decimal.Decimal `json:"cost" swaggertype:"string"`
	Quantity   decimal.Decimal `json:"quantity" swaggertype:"string"`
	EventCount int64           `json:"event_count"`
}

type CostSheetResponse struct {
	ID       string `json:"id"`
	MeterID  string `json:"meter_id"`
	PriceID  string `json:"price_id"`
	TenantID string `json:"tenant_id"`
	Status   string `json:"status"`
}

type CostsheetResponse struct {
	ID            string            `json:"id"`
	Name          string            `json:"name"`
	LookupKey     string            `json:"lookup_key,omitempty"`
	Description   string            `json:"description,omitempty"`
	Metadata      map[string]string `json:"metadata,omitempty"`
	TenantID      string            `json:"tenant_id"`
	EnvironmentID string            `json:"environment_id"`
	Status        types.Status      `json:"status"`
	CreatedAt     time.Time         `json:"created_at"`
	UpdatedAt     time.Time         `json:"updated_at"`
	CreatedBy     string            `json:"created_by,omitempty"`
	UpdatedBy     string            `json:"updated_by,omitempty"`
	Prices        []*PriceResponse  `json:"prices,omitempty"` // Associated prices
}

type CouponApplicationResponse struct {
	*coupon_application.CouponApplication `json:",inline"`
}

type CouponAssociationResponse struct {
	*couponAssociation.CouponAssociation `json:",inline"`
}

type CouponResponse struct {
	*coupon.Coupon `json:",inline"`
}

type CreateAPIKeyRequest struct {
	Name             string           `json:"name" binding:"required" validate:"required"`
	Type             types.SecretType `json:"type" binding:"required" validate:"required"`
	ExpiresAt        *time.Time       `json:"expires_at,omitempty"`
	ServiceAccountID string           `json:"service_account_id,omitempty"`
}

type CreateAPIKeyResponse struct {
	Secret SecretResponse `json:"secret"`
	APIKey string         `json:"api_key,omitempty"`
}

type CreateAddonRequest struct {
	Name        string                 `json:"name" validate:"required"`
	LookupKey   string                 `json:"lookup_key" validate:"required"`
	Description string                 `json:"description"`
	Type        types.AddonType        `json:"type" validate:"required"`
	Metadata    map[string]interface{} `json:"metadata"`
}

type CreateAddonResponse struct {
	*AddonResponse
}

type CreateBulkEntitlementRequest struct {
	Items []CreateEntitlementRequest `json:"items" validate:"required,min=1,max=100"`
}

type CreateBulkEntitlementResponse struct {
	Items []*EntitlementResponse `json:"items"`
}

type CreateBulkPriceRequest struct {
	Items []CreatePriceRequest `json:"items" validate:"required,min=1,max=100"`
}

type CreateBulkPriceResponse struct {
	Items []*PriceResponse `json:"items"`
}

type CreateConnectionRequest struct {
	Name                string                   `json:"name" validate:"required,max=255"`
	ProviderType        types.SecretProvider     `json:"provider_type" validate:"required"`
	EncryptedSecretData types.ConnectionMetadata `json:"encrypted_secret_data,omitempty"`
	Metadata            map[string]interface{}   `json:"metadata,omitempty"`
	SyncConfig          *types.SyncConfig        `json:"sync_config,omitempty" validate:"omitempty,dive"`
}

type CreateCostSheetRequest struct {
	// MeterID references the meter to track usage
	MeterID string `json:"meter_id" validate:"required"`

	// PriceID references the price configuration
	PriceID string `json:"price_id" validate:"required"`
}

type CreateCostsheetRequest struct {
	Name        string            `json:"name" validate:"required,min=1,max=255"`
	LookupKey   string            `json:"lookup_key,omitempty" validate:"omitempty,min=1,max=255"`
	Description string            `json:"description,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type CreateCostsheetResponse struct {
	Costsheet *CostsheetResponse `json:"costsheet"`
}

type CreateCouponApplicationRequest struct {
	CouponID            string                 `json:"coupon_id" validate:"required"`
	CouponAssociationID string                 `json:"coupon_association_id,omitempty"`
	InvoiceID           string                 `json:"invoice_id" validate:"required"`
	InvoiceLineItemID   *string                `json:"invoice_line_item_id,omitempty"`
	SubscriptionID      *string                `json:"subscription_id,omitempty"`
	OriginalPrice       decimal.Decimal        `json:"original_price" validate:"required" swaggertype:"string"`
	FinalPrice          decimal.Decimal        `json:"final_price" validate:"required" swaggertype:"string"`
	DiscountedAmount    decimal.Decimal        `json:"discounted_amount" validate:"required" swaggertype:"string"`
	DiscountType        types.CouponType       `json:"discount_type" validate:"required"`
	DiscountPercentage  *decimal.Decimal       `json:"discount_percentage,omitempty" swaggertype:"string"`
	Currency            string                 `json:"currency" validate:"required"`
	CouponSnapshot      map[string]interface{} `json:"coupon_snapshot,omitempty"`
	Metadata            map[string]string      `json:"metadata,omitempty"`
}

type CreateCouponAssociationRequest struct {
	CouponID               string            `json:"coupon_id" validate:"required"`
	SubscriptionID         string            `json:"subscription_id" validate:"required"`
	SubscriptionLineItemID *string           `json:"subscription_line_item_id,omitempty"`
	SubscriptionPhaseID    *string           `json:"subscription_phase_id,omitempty"`
	StartDate              time.Time         `json:"start_date" validate:"required"`
	EndDate                *time.Time        `json:"end_date,omitempty"`
	Metadata               map[string]string `json:"metadata,omitempty"`
}

type CreateCouponRequest struct {
	Name              string                  `json:"name" validate:"required"`
	RedeemAfter       *time.Time              `json:"redeem_after,omitempty"`
	RedeemBefore      *time.Time              `json:"redeem_before,omitempty"`
	MaxRedemptions    *int                    `json:"max_redemptions,omitempty"`
	Rules             *map[string]interface{} `json:"rules,omitempty"`
	AmountOff         *decimal.Decimal        `json:"amount_off,omitempty" swaggertype:"string"`
	PercentageOff     *decimal.Decimal        `json:"percentage_off,omitempty" swaggertype:"string"`
	Type              types.CouponType        `json:"type" validate:"required,oneof=fixed percentage"`
	Cadence           types.CouponCadence     `json:"cadence" validate:"required,oneof=once repeated forever"`
	DurationInPeriods *int                    `json:"duration_in_periods,omitempty"`
	Metadata          *map[string]string      `json:"metadata,omitempty"`
	Currency          *string                 `json:"currency,omitempty"`
}

type CreateCreditGrantApplicationRequest struct {
	CreditGrantID                   string                             `json:"credit_grant_id" binding:"required"`
	SubscriptionID                  string                             `json:"subscription_id"`
	ScheduledFor                    time.Time                          `json:"scheduled_for" binding:"required"`
	PeriodStart                     time.Time                          `json:"period_start" binding:"required"`
	PeriodEnd                       *time.Time                         `json:"period_end"`
	Credits                         decimal.Decimal                    `json:"credits" swaggertype:"string" binding:"required"`
	ApplicationReason               types.CreditGrantApplicationReason `json:"application_reason"`
	SubscriptionStatusAtApplication types.SubscriptionStatus           `json:"subscription_status_at_application"`
	IdempotencyKey                  string                             `json:"idempotency_key"`
}

type CreateCreditGrantRequest struct {
	Name                   string                               `json:"name" binding:"required"`
	Scope                  types.CreditGrantScope               `json:"scope" binding:"required"`
	PlanID                 *string                              `json:"plan_id,omitempty"`
	SubscriptionID         *string                              `json:"subscription_id,omitempty"`
	Credits                decimal.Decimal                      `json:"credits" binding:"required" swaggertype:"string"`
	Cadence                types.CreditGrantCadence             `json:"cadence" binding:"required"`
	Period                 *types.CreditGrantPeriod             `json:"period,omitempty"`
	PeriodCount            *int                                 `json:"period_count,omitempty"`
	ExpirationType         types.CreditGrantExpiryType          `json:"expiration_type,omitempty"`
	ExpirationDuration     *int                                 `json:"expiration_duration,omitempty"`
	ExpirationDurationUnit *types.CreditGrantExpiryDurationUnit `json:"expiration_duration_unit,omitempty"`
	Priority               *int                                 `json:"priority,omitempty"`
	Metadata               types.Metadata                       `json:"metadata,omitempty"`
	CreditGrantAnchor      *time.Time                           `json:"-"`
	StartDate              *time.Time                           `json:"-"`
	EndDate                *time.Time                           `json:"-"`

	// amount in the currency =  number of credits * conversion_rate
	// ex if conversion_rate is 1, then 1 USD = 1 credit
	// ex if conversion_rate is 2, then 1 USD = 0.5 credits
	// ex if conversion_rate is 0.5, then 1 USD = 2 credits
	ConversionRate *decimal.Decimal `json:"conversion_rate,omitempty" swaggertype:"string"`

	// topup_conversion_rate is the conversion rate for the topup to the currency
	// ex if topup_conversion_rate is 1, then 1 USD = 1 credit
	// ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits
	// ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
	TopupConversionRate *decimal.Decimal `json:"topup_conversion_rate,omitempty" swaggertype:"string"`
}

type CreateCreditNoteLineItemRequest struct {
	// invoice_line_item_id is the unique identifier of the invoice line item being credited
	InvoiceLineItemID string `json:"invoice_line_item_id" validate:"required"`

	// display_name is an optional human-readable name for this credit note line item
	DisplayName string `json:"display_name" validate:"omitempty"`

	// amount is the monetary amount to be credited for this line item
	Amount decimal.Decimal `json:"amount" validate:"required" swaggertype:"string"`

	// metadata contains additional custom key-value pairs for storing extra information about this line item
	Metadata types.Metadata `json:"metadata" validate:"omitempty"`
}

type CreateCreditNoteRequest struct {
	// credit_note_number is an optional human-readable identifier for the credit note
	CreditNoteNumber string `json:"credit_note_number" validate:"omitempty"`

	// invoice_id is the unique identifier of the invoice this credit note is applied to
	InvoiceID string `json:"invoice_id" validate:"required"`

	// memo is an optional free-text field for additional notes about the credit note
	Memo string `json:"memo" validate:"omitempty"`

	// reason specifies the reason for creating this credit note (duplicate, fraudulent, order_change, product_unsatisfactory)
	Reason types.CreditNoteReason `json:"reason" validate:"required"`

	// metadata contains additional custom key-value pairs for storing extra information
	Metadata types.Metadata `json:"metadata" validate:"omitempty"`

	// line_items contains the individual line items that make up this credit note (minimum 1 required)
	LineItems []CreateCreditNoteLineItemRequest `json:"line_items"`

	// idempotency_key is an optional key used to prevent duplicate credit note creation
	IdempotencyKey *string `json:"idempotency_key" validate:"omitempty"`

	// process_credit_note is a flag to process the credit note after creation
	ProcessCreditNote bool `json:"process_credit_note" validate:"omitempty" default:"true"`
}

type CreateCustomerRequest struct {
	// external_id is the unique identifier from your system to reference this customer (required)
	ExternalID string `json:"external_id" validate:"required"`

	// name is the full name or company name of the customer
	Name string `json:"name"`

	// email is the customer's email address and must be a valid email format if provided
	Email string `json:"email" validate:"omitempty,email"`

	// address_line1 is the primary address line with maximum 255 characters
	AddressLine1 string `json:"address_line1" validate:"omitempty,max=255"`

	// address_line2 is the secondary address line with maximum 255 characters
	AddressLine2 string `json:"address_line2" validate:"omitempty,max=255"`

	// address_city is the city name with maximum 100 characters
	AddressCity string `json:"address_city" validate:"omitempty,max=100"`

	// address_state is the state, province, or region name with maximum 100 characters
	AddressState string `json:"address_state" validate:"omitempty,max=100"`

	// address_postal_code is the ZIP code or postal code with maximum 20 characters
	AddressPostalCode string `json:"address_postal_code" validate:"omitempty,max=20"`

	// address_country is the two-letter ISO 3166-1 alpha-2 country code
	AddressCountry string `json:"address_country" validate:"omitempty,len=2,iso3166_1_alpha2"`

	// metadata contains additional key-value pairs for storing extra information
	Metadata map[string]string `json:"metadata,omitempty"`

	// skip_onboarding_workflow when true, prevents the customer onboarding workflow from being triggered
	// This is used internally when a customer is created via a workflow to prevent infinite loops
	// Default: false
	SkipOnboardingWorkflow bool `json:"skip_onboarding_workflow,omitempty"`

	// tax_rate_overrides contains tax rate configurations to be linked to this customer
	TaxRateOverrides []*TaxRateOverride `json:"tax_rate_overrides,omitempty"`

	// integration_entity_mapping contains provider integration mappings for this customer
	IntegrationEntityMapping []*IntegrationEntityMapping `json:"integration_entity_mapping,omitempty"`

	// parent_customer_id is the internal FlexPrice ID of the parent customer
	ParentCustomerID *string `json:"parent_customer_id,omitempty"`

	// parent_customer_external_id is the external ID of the parent customer from your system
	// Exactly one of parent_customer_id or parent_customer_external_id may be provided
	ParentCustomerExternalID *string `json:"parent_customer_external_id,omitempty"`
}

type CreateEntitlementRequest struct {
	PlanID              string                            `json:"plan_id,omitempty"`
	FeatureID           string                            `json:"feature_id" binding:"required"`
	FeatureType         types.FeatureType                 `json:"feature_type" binding:"required"`
	IsEnabled           bool                              `json:"is_enabled"`
	UsageLimit          *int64                            `json:"usage_limit"`
	UsageResetPeriod    types.EntitlementUsageResetPeriod `json:"usage_reset_period"`
	IsSoftLimit         bool                              `json:"is_soft_limit"`
	StaticValue         string                            `json:"static_value"`
	EntityType          types.EntitlementEntityType       `json:"entity_type"`
	EntityID            string                            `json:"entity_id"`
	ParentEntitlementID *string                           `json:"parent_entitlement_id,omitempty"`
	StartDate           *time.Time                        `json:"start_date,omitempty"`
	EndDate             *time.Time                        `json:"end_date,omitempty"`
}

type CreateEntityIntegrationMappingRequest struct {
	EntityID         string                      `json:"entity_id" validate:"required,max=255"`
	EntityType       types.IntegrationEntityType `json:"entity_type" validate:"required"`
	ProviderType     string                      `json:"provider_type" validate:"required,max=50"`
	ProviderEntityID string                      `json:"provider_entity_id" validate:"required,max=255"`
	Metadata         map[string]interface{}      `json:"metadata,omitempty"`
}

type CreateEnvironmentRequest struct {
	Name string `json:"name" validate:"required"`
	Type string `json:"type" validate:"required"`
}

type CreateFeatureRequest struct {
	Name          string               `json:"name" binding:"required"`
	Description   string               `json:"description"`
	LookupKey     string               `json:"lookup_key"`
	Type          types.FeatureType    `json:"type" binding:"required"`
	MeterID       string               `json:"meter_id,omitempty"`
	Meter         *CreateMeterRequest  `json:"meter,omitempty"`
	Metadata      types.Metadata       `json:"metadata,omitempty"`
	UnitSingular  string               `json:"unit_singular,omitempty"`
	UnitPlural    string               `json:"unit_plural,omitempty"`
	AlertSettings *types.AlertSettings `json:"alert_settings,omitempty"`
}

type CreateGroupRequest struct {
	Name       string `json:"name" validate:"required"`
	EntityType string `json:"entity_type" validate:"required"`
	LookupKey  string `json:"lookup_key" validate:"required"`
}

type CreateIntegrationRequest struct {
	Name        string               `json:"name" binding:"required"`
	Provider    types.SecretProvider `json:"provider" binding:"required"`
	Credentials map[string]string    `json:"credentials" binding:"required"`
}

type CreateInvoiceLineItemRequest struct {
	// entity_id is the optional unique identifier of the entity associated with this line item
	EntityID *string `json:"entity_id,omitempty"`

	// entity_type is the optional type of the entity associated with this line item
	EntityType *string `json:"entity_type,omitempty"`

	// price_id is the optional unique identifier of the price associated with this line item
	PriceID *string `json:"price_id,omitempty"`

	// plan_display_name is the optional human-readable name of the plan
	PlanDisplayName *string `json:"plan_display_name,omitempty"`

	// price_type indicates the type of pricing (fixed, usage, tiered, etc.)
	PriceType *string `json:"price_type,omitempty"`

	// meter_id is the optional unique identifier of the meter used for usage tracking
	MeterID *string `json:"meter_id,omitempty"`

	// meter_display_name is the optional human-readable name of the meter
	MeterDisplayName *string `json:"meter_display_name,omitempty"`

	// price_unit is the optional 3-digit ISO code of the price unit associated with this line item
	PriceUnit *string `json:"price_unit,omitempty"`

	// price_unit_amount is the optional amount converted to the price unit currency
	PriceUnitAmount *decimal.Decimal `json:"price_unit_amount,omitempty" swaggertype:"string"`

	// display_name is the optional human-readable name for this line item
	DisplayName *string `json:"display_name,omitempty"`

	// amount is the monetary amount for this line item
	Amount decimal.Decimal `json:"amount" validate:"required" swaggertype:"string"`

	// quantity is the quantity of units for this line item
	Quantity decimal.Decimal `json:"quantity" validate:"required" swaggertype:"string"`

	// period_start is the optional start date of the period this line item covers
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the optional end date of the period this line item covers
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information about this line item
	Metadata types.Metadata `json:"metadata,omitempty"`

	// TODO: !REMOVE after migration
	// plan_id is the optional unique identifier of the plan associated with this line item
	PlanID *string `json:"plan_id,omitempty"`

	// commitment_info contains details about any commitment applied to this line item
	CommitmentInfo *types.CommitmentInfo `json:"commitment_info,omitempty"`
}

type CreateInvoiceRequest struct {
	// invoice_number is an optional human-readable identifier for the invoice
	InvoiceNumber *string `json:"invoice_number,omitempty"`

	// customer_id is the unique identifier of the customer this invoice belongs to
	CustomerID string `json:"customer_id" validate:"required"`

	// subscription_id is the optional unique identifier of the subscription associated with this invoice
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// idempotency_key is an optional key used to prevent duplicate invoice creation
	IdempotencyKey *string `json:"idempotency_key"`

	// invoice_type indicates the type of invoice (subscription, one_time, etc.)
	InvoiceType types.InvoiceType `json:"invoice_type"`

	// currency is the three-letter ISO currency code (e.g., USD, EUR) for the invoice
	Currency string `json:"currency" validate:"required"`

	// amount_due is the total amount that needs to be paid for this invoice
	AmountDue decimal.Decimal `json:"amount_due" validate:"required" swaggertype:"string"`

	// total is the total amount of the invoice including taxes and discounts
	Total decimal.Decimal `json:"total" validate:"required" swaggertype:"string"`

	// subtotal is the amount before taxes and discounts are applied
	Subtotal decimal.Decimal `json:"subtotal" validate:"required" swaggertype:"string"`

	// description is an optional text description of the invoice
	Description string `json:"description,omitempty"`

	// due_date is the date by which payment is expected
	DueDate *time.Time `json:"due_date,omitempty"`

	// billing_period is the period this invoice covers (e.g., "monthly", "yearly")
	BillingPeriod *string `json:"billing_period,omitempty"`

	// period_start is the start date of the billing period
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the end date of the billing period
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// billing_reason indicates why this invoice was created (subscription_cycle, manual, etc.)
	BillingReason types.InvoiceBillingReason `json:"billing_reason"`

	// invoice_status represents the current status of the invoice (draft, finalized, etc.)
	InvoiceStatus *types.InvoiceStatus `json:"invoice_status,omitempty"`

	// payment_status represents the payment status of the invoice (unpaid, paid, etc.)
	PaymentStatus *types.PaymentStatus `json:"payment_status,omitempty"`

	// amount_paid is the amount that has been paid towards this invoice
	AmountPaid *decimal.Decimal `json:"amount_paid,omitempty" swaggertype:"string"`

	// line_items contains the individual items that make up this invoice
	LineItems []CreateInvoiceLineItemRequest `json:"line_items,omitempty"`

	// coupons
	Coupons []string `json:"coupons,omitempty"`

	// tax_rates
	TaxRates []string `json:"tax_rates,omitempty"`

	// Invoice Coupns
	InvoiceCoupons []InvoiceCoupon `json:"invoice_coupons,omitempty"`

	// Invoice Line Item Coupons
	LineItemCoupons []InvoiceLineItemCoupon `json:"line_item_coupons,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information
	Metadata types.Metadata `json:"metadata,omitempty"`

	// tax_rate_overrides is the tax rate overrides to be applied to the invoice
	TaxRateOverrides []*TaxRateOverride `json:"tax_rate_overrides,omitempty"`

	// prepared_tax_rates contains the tax rates pre-resolved by the caller (e.g., billing service)
	// These are applied at invoice level by the invoice service without further resolution
	PreparedTaxRates []*TaxRateResponse `json:"prepared_tax_rates,omitempty"`

	// environment_id is the unique identifier of the environment this invoice belongs to
	EnvironmentID string `json:"environment_id,omitempty"`

	// invoice_pdf_url is the URL where customers can download the PDF version of this invoice
	InvoicePDFURL *string `json:"invoice_pdf_url,omitempty"`
}

type CreateMeterRequest struct {
	Name        string            `json:"name" binding:"required" example:"API Usage Meter"`
	EventName   string            `json:"event_name" binding:"required" example:"api_request"`
	Aggregation meter.Aggregation `json:"aggregation" binding:"required"`
	Filters     []meter.Filter    `json:"filters"`
	ResetUsage  types.ResetUsage  `json:"reset_usage" binding:"required"`
}

type CreatePaymentLinkRequest struct {
	InvoiceID              string                    `json:"invoice_id" binding:"required"`
	CustomerID             string                    `json:"customer_id" binding:"required"`
	Amount                 decimal.Decimal           `json:"amount" binding:"required" swaggertype:"string"`
	Currency               string                    `json:"currency" binding:"required"`
	Gateway                *types.PaymentGatewayType `json:"gateway,omitempty"` // Optional, will use preferred if not specified
	SuccessURL             string                    `json:"success_url,omitempty"`
	CancelURL              string                    `json:"cancel_url,omitempty"`
	Metadata               types.Metadata            `json:"metadata,omitempty"`
	Description            string                    `json:"description,omitempty"`
	SaveCardAndMakeDefault bool                      `json:"save_card_and_make_default" default:"false"`
}

type CreatePaymentRequest struct {
	IdempotencyKey         string                       `json:"idempotency_key,omitempty"`
	DestinationType        types.PaymentDestinationType `json:"destination_type" binding:"required"`
	DestinationID          string                       `json:"destination_id" binding:"required"`
	PaymentMethodType      types.PaymentMethodType      `json:"payment_method_type" binding:"required"`
	PaymentMethodID        string                       `json:"payment_method_id"`
	PaymentGateway         *types.PaymentGatewayType    `json:"payment_gateway,omitempty"`
	Amount                 decimal.Decimal              `json:"amount" binding:"required" swaggertype:"string"`
	Currency               string                       `json:"currency" binding:"required"`
	SuccessURL             string                       `json:"success_url,omitempty"`
	CancelURL              string                       `json:"cancel_url,omitempty"`
	Metadata               types.Metadata               `json:"metadata,omitempty"`
	ProcessPayment         bool                         `json:"process_payment" default:"true"`
	SaveCardAndMakeDefault bool                         `json:"save_card_and_make_default" default:"false"`
}

type CreatePlanEntitlementRequest struct {
	*CreateEntitlementRequest
}

type CreatePlanPriceRequest struct {
	*CreatePriceRequest
}

type CreatePlanRequest struct {
	Name         string         `json:"name" validate:"required"`
	LookupKey    string         `json:"lookup_key"`
	Description  string         `json:"description"`
	DisplayOrder *int           `json:"display_order,omitempty"`
	Metadata     types.Metadata `json:"metadata,omitempty"`
}

type CreatePlanResponse struct {
	*plan.Plan
}

type CreatePriceRequest struct {
	Amount             *decimal.Decimal         `json:"amount,omitempty" swaggertype:"string"`
	Currency           string                   `json:"currency" validate:"required,len=3"`
	EntityType         types.PriceEntityType    `json:"entity_type" validate:"required"`
	EntityID           string                   `json:"entity_id" validate:"required"`
	Type               types.PriceType          `json:"type" validate:"required"`
	PriceUnitType      types.PriceUnitType      `json:"price_unit_type" validate:"required"`
	BillingPeriod      types.BillingPeriod      `json:"billing_period" validate:"required"`
	BillingPeriodCount int                      `json:"billing_period_count" default:"1"`
	BillingModel       types.BillingModel       `json:"billing_model" validate:"required"`
	BillingCadence     types.BillingCadence     `json:"billing_cadence" validate:"required"`
	MeterID            string                   `json:"meter_id,omitempty"`
	FilterValues       map[string][]string      `json:"filter_values,omitempty"`
	LookupKey          string                   `json:"lookup_key,omitempty"`
	InvoiceCadence     types.InvoiceCadence     `json:"invoice_cadence" validate:"required"`
	TrialPeriod        int                      `json:"trial_period"`
	Description        string                   `json:"description,omitempty"`
	Metadata           map[string]string        `json:"metadata,omitempty"`
	TierMode           types.BillingTier        `json:"tier_mode,omitempty"`
	Tiers              []CreatePriceTier        `json:"tiers,omitempty"`
	TransformQuantity  *price.TransformQuantity `json:"transform_quantity,omitempty"`
	PriceUnitConfig    *PriceUnitConfig         `json:"price_unit_config,omitempty"`
	StartDate          *time.Time               `json:"start_date,omitempty"`
	EndDate            *time.Time               `json:"end_date,omitempty"`
	DisplayName        string                   `json:"display_name,omitempty"`

	// MinQuantity is the minimum quantity of the price
	MinQuantity *int64 `json:"min_quantity,omitempty"`

	// SkipEntityValidation is used to skip entity validation when creating a price from a subscription i.e. override price workflow
	// This is used when creating a subscription-scoped price
	// NOTE: This is not a public field and is used internally should be used with caution
	SkipEntityValidation bool `json:"-"`

	// ParentPriceID is the id of the parent price for this price
	ParentPriceID string `json:"-"`

	// GroupID is the id of the group to add the price to
	GroupID string `json:"group_id,omitempty"`
}

type CreatePriceTier struct {
	// up_to is the quantity up to which this tier applies. It is null for the last tier.
	// IMPORTANT: Tier boundaries are INCLUSIVE.
	// - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier
	// - This behavior is consistent across both VOLUME and SLAB tier modes
	UpTo *uint64 `json:"up_to"`

	// unit_amount is the amount per unit for the given tier
	UnitAmount decimal.Decimal `json:"unit_amount" validate:"required" swaggertype:"string"`

	// flat_amount is the flat amount for the given tier (optional)
	// Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c"
	FlatAmount *decimal.Decimal `json:"flat_amount,omitempty" swaggertype:"string"`
}

type CreatePriceUnitRequest struct {
	Name   string `json:"name" validate:"required"`
	Code   string `json:"code" validate:"required"`
	Symbol string `json:"symbol" validate:"required"`

	// base_currency  is the currency that the price unit is based on
	BaseCurrency string `json:"base_currency" validate:"required,len=3"`

	// ConversionRate defines the exchange rate from this price unit to the base currency.
	// This rate is used to convert amounts in the custom price unit to the base currency for storage and billing.
	//
	// Conversion formula:
	//   price_unit_amount * conversion_rate = base_currency_amount
	//
	// Example:
	//   If conversion_rate = "0.01" and base_currency = "usd":
	//   100 price_unit tokens * 0.01 = 1.00 USD
	//
	// Note: Rounding precision is determined by the base currency (e.g., USD uses 2 decimal places, JPY uses 0).
	ConversionRate string         `json:"conversion_rate" validate:"required"`
	Metadata       types.Metadata `json:"metadata,omitempty"`
}

type CreatePriceUnitResponse struct {
	*priceunit.PriceUnit
}

type CreateProrationInvoiceRequest struct {
	// subscription_id is the unique identifier of the subscription this proration relates to
	SubscriptionID string `json:"subscription_id" validate:"required"`

	// customer_id is the unique identifier of the customer
	CustomerID string `json:"customer_id" validate:"required"`

	// proration_result contains the calculated proration details
	ProrationResult *ProrationResult `json:"proration_result" validate:"required"`

	// description is the human-readable description for the invoice
	Description string `json:"description,omitempty"`

	// effective_date is when the proration takes effect
	EffectiveDate time.Time `json:"effective_date" validate:"required"`

	// cancellation_type indicates the type of cancellation (for metadata)
	CancellationType string `json:"cancellation_type,omitempty"`

	// cancellation_reason is the business reason for the cancellation
	CancellationReason string `json:"cancellation_reason,omitempty"`
}

type CreateScheduledTaskRequest struct {
	ConnectionID string                        `json:"connection_id" binding:"required" validate:"required"`
	EntityType   types.ScheduledTaskEntityType `json:"entity_type" binding:"required" validate:"required"`
	Interval     types.ScheduledTaskInterval   `json:"interval" binding:"required" validate:"required" enums:"hourly,daily"` // Note: "custom" is excluded from API (internal testing only)
	Enabled      bool                          `json:"enabled"`
	JobConfig    *types.S3JobConfig            `json:"job_config" binding:"required" validate:"required"`
}

type CreateSettingRequest struct {
	Key   types.SettingKey       `json:"key" validate:"required"`
	Value map[string]interface{} `json:"value,omitempty"`
}

type CreateSetupIntentRequest struct {
	Provider           string         `json:"provider" binding:"required"`    // Payment provider: "stripe", "razorpay", etc.
	Usage              string         `json:"usage,omitempty"`                // "on_session" or "off_session" (default: "off_session")
	PaymentMethodTypes []string       `json:"payment_method_types,omitempty"` // defaults to ["card"]
	SuccessURL         string         `json:"success_url,omitempty"`          // User-configurable success redirect URL
	CancelURL          string         `json:"cancel_url,omitempty"`           // User-configurable cancel redirect URL
	SetDefault         bool           `json:"set_default,omitempty"`          // Whether to set the payment method as default when setup succeeds
	Metadata           types.Metadata `json:"metadata,omitempty"`
}

type CreateStripePaymentLinkRequest struct {
	InvoiceID              string          `json:"invoice_id" binding:"required"`
	CustomerID             string          `json:"customer_id" binding:"required"`
	Amount                 decimal.Decimal `json:"amount" binding:"required" swaggertype:"string"`
	Currency               string          `json:"currency" binding:"required"`
	SuccessURL             string          `json:"success_url,omitempty"`
	CancelURL              string          `json:"cancel_url,omitempty"`
	EnvironmentID          string          `json:"environment_id" binding:"required"`
	Metadata               types.Metadata  `json:"metadata,omitempty"`
	SaveCardAndMakeDefault bool            `json:"save_card_and_make_default" default:"false"`
	PaymentID              string          `json:"payment_id" binding:"required"`
}

type CreateSubscriptionInvoiceRequest struct {
	// subscription_id is the unique identifier of the subscription to create an invoice for
	SubscriptionID string `json:"subscription_id" binding:"required"`

	// period_start is the start date of the billing period for this invoice
	PeriodStart time.Time `json:"period_start" binding:"required"`

	// period_end is the end date of the billing period for this invoice
	PeriodEnd time.Time `json:"period_end" binding:"required"`

	// is_preview indicates whether this is a preview invoice (not saved to database)
	IsPreview bool `json:"is_preview"`

	// reference_point defines the point in time used for calculating usage and charges
	ReferencePoint types.InvoiceReferencePoint `json:"reference_point"`
}

type CreateSubscriptionLineItemRequest struct {
	PriceID              string            `json:"price_id" validate:"required"`
	Quantity             decimal.Decimal   `json:"quantity,omitempty"`
	StartDate            *time.Time        `json:"start_date,omitempty"`
	EndDate              *time.Time        `json:"end_date,omitempty"`
	Metadata             map[string]string `json:"metadata,omitempty"`
	DisplayName          string            `json:"display_name,omitempty"`
	SubscriptionPhaseID  *string           `json:"subscription_phase_id,omitempty"`
	SkipEntitlementCheck bool              `json:"-"` // This is used to skip entitlement check when creating a subscription line item

	// Commitment fields
	CommitmentAmount        *decimal.Decimal     `json:"commitment_amount,omitempty"`
	CommitmentQuantity      *decimal.Decimal     `json:"commitment_quantity,omitempty"`
	CommitmentType          types.CommitmentType `json:"commitment_type,omitempty"`
	CommitmentOverageFactor *decimal.Decimal     `json:"commitment_overage_factor,omitempty"`
	CommitmentTrueUpEnabled bool                 `json:"commitment_true_up_enabled,omitempty"`
	CommitmentWindowed      bool                 `json:"commitment_windowed,omitempty"`
}

type CreateSubscriptionPhaseRequest struct {
	// subscription_id is the identifier for the subscription
	SubscriptionID string `json:"subscription_id" validate:"required"`

	// start_date is when the phase starts (required)
	StartDate *time.Time `json:"start_date" validate:"required"`

	// end_date is when the phase ends (nil if phase is indefinite)
	EndDate *time.Time `json:"end_date,omitempty"`

	// metadata contains additional key-value pairs
	Metadata types.Metadata `json:"metadata,omitempty"`
}

type CreateSubscriptionRequest struct {

	// customer_id is the flexprice customer id
	// and it is prioritized over external_customer_id in case both are provided.
	CustomerID string `json:"customer_id"`

	// external_customer_id is the customer id in your DB
	// and must be same as what you provided as external_id while creating the customer in flexprice.
	ExternalCustomerID string `json:"external_customer_id"`

	// invoicing_customer_id is the customer ID to use for invoicing
	// This can differ from the subscription customer (e.g., parent company invoicing for child company)
	// This field is set internally based on InvoiceBillingConfig and is not exposed in the API
	InvoicingCustomerID *string `json:"-"`

	// invoice_billing determines which customer should receive invoices for a subscription
	// "invoice_to_parent" - Invoices are sent to the parent customer
	// "invoice_to_self" - Invoices are sent to the subscription's customer
	InvoiceBilling *types.InvoiceBilling `json:"invoice_billing,omitempty"`

	PlanID             string               `json:"plan_id" validate:"required"`
	Currency           string               `json:"currency" validate:"required,len=3"`
	LookupKey          string               `json:"lookup_key"`
	StartDate          *time.Time           `json:"start_date,omitempty"`
	EndDate            *time.Time           `json:"end_date,omitempty"`
	TrialStart         *time.Time           `json:"trial_start,omitempty"`
	TrialEnd           *time.Time           `json:"trial_end,omitempty"`
	BillingCadence     types.BillingCadence `json:"billing_cadence" validate:"required"`
	BillingPeriod      types.BillingPeriod  `json:"billing_period" validate:"required"`
	BillingPeriodCount int                  `json:"billing_period_count" default:"1"`
	Metadata           map[string]string    `json:"metadata,omitempty"`

	// BillingCycle is the cycle of the billing anchor.
	// This is used to determine the billing date for the subscription (i.e set the billing anchor)
	// If not set, the default value is anniversary. Possible values are anniversary and calendar.
	// Anniversary billing means the billing anchor will be the start date of the subscription.
	// Calendar billing means the billing anchor will be the appropriate date based on the billing period.
	// For example, if the billing period is month and the start date is 2025-04-15 then in case of
	// calendar billing the billing anchor will be 2025-05-01 vs 2025-04-15 for anniversary billing.
	BillingCycle types.BillingCycle `json:"billing_cycle"`

	// Credit grants to be applied when subscription is created
	CreditGrants []CreateCreditGrantRequest `json:"credit_grants,omitempty"`

	// CommitmentAmount is the minimum amount a customer commits to paying for a billing period
	CommitmentAmount *decimal.Decimal `json:"commitment_amount,omitempty" swaggertype:"string"`

	// OverageFactor is a multiplier applied to usage beyond the commitment amount
	OverageFactor *decimal.Decimal `json:"overage_factor,omitempty" swaggertype:"string"`

	// tax_rate_overrides is the tax rate overrides	to be applied to the subscription
	TaxRateOverrides []*TaxRateOverride `json:"tax_rate_overrides,omitempty"`

	Coupons []string `json:"coupons,omitempty"`

	LineItemCoupons map[string][]string `json:"line_item_coupons,omitempty"`

	// LineItemCommitments allows setting commitment configuration per line item (keyed by price_id)
	LineItemCommitments map[string]*LineItemCommitmentConfig `json:"line_item_commitments,omitempty" validate:"omitempty,dive"`

	// OverrideLineItems allows customizing specific prices for this subscription
	OverrideLineItems []OverrideLineItemRequest `json:"override_line_items,omitempty" validate:"omitempty,dive"`
	// OverrideEntitlements allows customizing specific entitlements for this subscription
	OverrideEntitlements []OverrideEntitlementRequest `json:"override_entitlements,omitempty" validate:"omitempty,dive"`
	// Addons represents addons to be added to the subscription during creation
	Addons []AddAddonToSubscriptionRequest `json:"addons,omitempty" validate:"omitempty,dive"`

	// Phases represents subscription phases to be created with the subscription
	Phases []SubscriptionPhaseCreateRequest `json:"phases,omitempty" validate:"omitempty,dive"`

	// Payment behavior configuration
	PaymentBehavior        *types.PaymentBehavior `json:"payment_behavior,omitempty"`
	GatewayPaymentMethodID *string                `json:"gateway_payment_method_id,omitempty"`

	// collection_method determines how invoices are collected
	// "default_incomplete" - subscription waits for payment confirmation before activation
	// "send_invoice" - subscription activates immediately, invoice is sent for payment
	CollectionMethod *types.CollectionMethod `json:"collection_method,omitempty"`

	// ProrationBehavior controls how proration is handled.
	// If not set, the default value is none. Possible values are create_prorations and none.
	// create_prorations means the proration will be calculated and applied.
	// none means the proration will not be calculated.
	// This is IGNORED when the billing cycle is anniversary.
	ProrationBehavior types.ProrationBehavior `json:"proration_behavior,omitempty"`

	// Timezone of the customer.
	// If not set, the default value is UTC.
	CustomerTimezone string `json:"customer_timezone" validate:"omitempty,timezone"`

	//Billing Anchor
	BillingAnchor *time.Time `json:"-"`

	// Workflow
	Workflow *types.TemporalWorkflowType `json:"-"`

	// SubscriptionStatus determines the initial status of the subscription
	// If set to "draft", the subscription will be created as a draft (skips invoice creation and payment processing)
	SubscriptionStatus types.SubscriptionStatus `json:"subscription_status,omitempty"`

	// Enable Commitment True Up Fee
	EnableTrueUp bool `json:"enable_true_up"`
}

type CreateTaskRequest struct {
	TaskType   types.TaskType         `json:"task_type" binding:"required"`
	EntityType types.EntityType       `json:"entity_type" binding:"required"`
	FileURL    string                 `json:"file_url" binding:"required"`
	FileName   *string                `json:"file_name,omitempty"`
	FileType   types.FileType         `json:"file_type" binding:"required"`
	Metadata   map[string]interface{} `json:"metadata,omitempty"`
}

type CreateTaxAppliedRequest struct {
	TaxRateID        string                  `json:"tax_rate_id" validate:"required"`
	EntityType       types.TaxRateEntityType `json:"entity_type" validate:"required"`
	EntityID         string                  `json:"entity_id" validate:"required"`
	TaxableAmount    decimal.Decimal         `json:"taxable_amount" validate:"required" swaggertype:"string"`
	TaxAmount        decimal.Decimal         `json:"tax_amount" validate:"required" swaggertype:"string"`
	Currency         string                  `json:"currency" validate:"required"`
	TaxAssociationID *string                 `json:"tax_association_id,omitempty"`
	Metadata         map[string]string       `json:"metadata,omitempty"`
}

type CreateTaxAssociationRequest struct {
	TaxRateCode string                  `json:"tax_rate_code" binding:"required"`
	EntityType  types.TaxRateEntityType `json:"entity_type" binding:"required"`
	EntityID    string                  `json:"entity_id" binding:"required"`
	Priority    int                     `json:"priority" binding:"omitempty"`
	Currency    string                  `json:"currency" binding:"omitempty"`
	AutoApply   bool                    `json:"auto_apply" binding:"omitempty"`
	Metadata    map[string]string       `json:"metadata" binding:"omitempty"`
}

type CreateTaxRateRequest struct {
	// name is the human-readable name for the tax rate (required)
	Name string `json:"name" validate:"required"`

	// code is the unique alphanumeric case sensitive identifier for the tax rate (required)
	Code string `json:"code" validate:"required"`

	// description is an optional text description providing details about the tax rate
	Description string `json:"description,omitempty"`

	// percentage_value is the percentage value (0-100) when tax_rate_type is "percentage"
	PercentageValue *decimal.Decimal `json:"percentage_value,omitempty" swaggertype:"string"`

	// fixed_value is the fixed monetary amount when tax_rate_type is "fixed"
	FixedValue *decimal.Decimal `json:"fixed_value,omitempty" swaggertype:"string"`

	// tax_rate_type determines how the tax is calculated ("percentage" or "fixed")
	TaxRateType types.TaxRateType `json:"tax_rate_type"`

	// scope defines where this tax rate applies
	Scope *types.TaxRateScope `json:"scope,omitempty"`

	// metadata contains additional key-value pairs for storing extra information
	Metadata map[string]string `json:"metadata,omitempty"`
}

type CreateTenantRequest struct {
	Name           string                `json:"name" validate:"required"`
	BillingDetails *TenantBillingDetails `json:"billing_details,omitempty"`
	ID             string                `json:"-"`
}

type CreateUserRequest struct {
	Type  types.UserType `json:"type" binding:"required" validate:"required"`              // Must be "service_account"
	Roles []string       `json:"roles" binding:"required,min=1" validate:"required,min=1"` // Roles are required
}

type CreateWalletRequest struct {
	CustomerID string `json:"customer_id,omitempty"`

	// external_customer_id is the customer id in the external system
	ExternalCustomerID string              `json:"external_customer_id,omitempty"`
	Name               string              `json:"name,omitempty"`
	Currency           string              `json:"currency" binding:"required"`
	Description        string              `json:"description,omitempty"`
	Metadata           types.Metadata      `json:"metadata,omitempty"`
	WalletType         types.WalletType    `json:"wallet_type"`
	Config             *types.WalletConfig `json:"config,omitempty"`

	// amount in the currency =  number of credits * conversion_rate
	// ex if conversion_rate is 1, then 1 USD = 1 credit
	// ex if conversion_rate is 2, then 1 USD = 0.5 credits
	// ex if conversion_rate is 0.5, then 1 USD = 2 credits
	ConversionRate decimal.Decimal `json:"conversion_rate" default:"1" swaggertype:"string"`

	// topup_conversion_rate is the conversion rate for the topup to the currency
	// ex if topup_conversion_rate is 1, then 1 USD = 1 credit
	// ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits
	// ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
	TopupConversionRate *decimal.Decimal `json:"topup_conversion_rate,omitempty" swaggertype:"string"`

	// initial_credits_to_load is the number of credits to load to the wallet
	// if not provided, the wallet will be created with 0 balance
	// NOTE: this is not the amount in the currency, but the number of credits
	InitialCreditsToLoad decimal.Decimal `json:"initial_credits_to_load,omitempty" default:"0" swaggertype:"string"`

	// initial_credits_to_load_expiry_date YYYYMMDD format in UTC timezone (optional to set nil means no expiry)
	// for ex 20250101 means the credits will expire on 2025-01-01 00:00:00 UTC
	// hence they will be available for use until 2024-12-31 23:59:59 UTC
	InitialCreditsToLoadExpiryDate *int `json:"initial_credits_to_load_expiry_date,omitempty"`

	// initial_credits_expiry_date_utc is the expiry date in UTC timezone (optional to set nil means no expiry)
	// ex 2025-01-01 00:00:00 UTC
	InitialCreditsExpiryDateUTC *time.Time `json:"initial_credits_expiry_date_utc,omitempty"`

	// alert_enabled is the flag to enable alerts for the wallet
	// defaults to true, can be explicitly set to false to disable alerts
	AlertEnabled bool `json:"alert_enabled,omitempty"`

	// alert_config is the alert configuration for the wallet (optional)
	AlertConfig *AlertConfig `json:"alert_config,omitempty"`

	// auto top-up object
	AutoTopup *types.AutoTopup `json:"auto_topup,omitempty"`

	// price_unit is the code of the price unit to use for wallet creation
	// If provided, the price unit will be used to set the currency and conversion rate of the wallet:
	// - currency: set to price unit's base_currency
	// - conversion_rate: set to price unit's conversion_rate
	PriceUnit *string `json:"price_unit,omitempty"`
}

type CreditGrantApplicationResponse struct {
	*domainCreditGrantApplication.CreditGrantApplication
}

type CreditGrantResponse struct {
	*creditgrant.CreditGrant
}

type CreditNoteResponse struct {
	*creditnote.CreditNote

	// invoice contains the associated invoice information if requested
	Invoice *InvoiceResponse `json:"invoice,omitempty"`

	// subscription contains the associated subscription information if applicable
	Subscription *SubscriptionResponse `json:"subscription,omitempty"`

	// customer contains the customer information associated with this credit note
	Customer *customer.Customer `json:"customer,omitempty"`
}

type CurrencyRevenueWindows struct {
	Windows []types.RevenueWindow `json:"windows"`
}

type CustomerEntitlementsResponse struct {
	CustomerID string               `json:"customer_id"`
	Features   []*AggregatedFeature `json:"features"`
}

type CustomerInvoiceSummary struct {
	// customer_id is the unique identifier of the customer
	CustomerID string `json:"customer_id"`

	// currency is the three-letter ISO currency code for this summary
	Currency string `json:"currency"`

	// total_revenue_amount is the total revenue generated from this customer in this currency
	TotalRevenueAmount decimal.Decimal `json:"total_revenue_amount" swaggertype:"string"`

	// total_unpaid_amount is the total amount of unpaid invoices in this currency
	TotalUnpaidAmount decimal.Decimal `json:"total_unpaid_amount" swaggertype:"string"`

	// total_overdue_amount is the total amount of overdue invoices in this currency
	TotalOverdueAmount decimal.Decimal `json:"total_overdue_amount" swaggertype:"string"`

	// total_invoice_count is the total number of invoices for this customer in this currency
	TotalInvoiceCount int `json:"total_invoice_count"`

	// unpaid_invoice_count is the number of unpaid invoices for this customer in this currency
	UnpaidInvoiceCount int `json:"unpaid_invoice_count"`

	// overdue_invoice_count is the number of overdue invoices for this customer in this currency
	OverdueInvoiceCount int `json:"overdue_invoice_count"`

	// unpaid_usage_charges is the total amount of unpaid usage-based charges in this currency
	UnpaidUsageCharges decimal.Decimal `json:"unpaid_usage_charges" swaggertype:"string"`

	// unpaid_fixed_charges is the total amount of unpaid fixed charges in this currency
	UnpaidFixedCharges decimal.Decimal `json:"unpaid_fixed_charges" swaggertype:"string"`
}

type CustomerMultiCurrencyInvoiceSummary struct {
	// customer_id is the unique identifier of the customer
	CustomerID string `json:"customer_id"`

	// default_currency is the primary currency for this customer
	DefaultCurrency string `json:"default_currency"`

	// summaries contains the invoice summaries for each currency
	Summaries []*CustomerInvoiceSummary `json:"summaries"`
}

type CustomerResponse struct {
	*customer.Customer
	ParentCustomer *CustomerResponse `json:"parent_customer,omitempty"`
}

type CustomerUsageSummaryResponse struct {
	CustomerID string                    `json:"customer_id"`
	Features   []*FeatureUsageSummary    `json:"features"`
	Period     *BillingPeriodInfo        `json:"period"`
	Pagination *types.PaginationResponse `json:"pagination,omitempty"`
}

type DashboardRevenuesRequest struct {
	RevenueTrend *RevenueTrendRequest `json:"revenue_trend,omitempty"`
}

type DashboardRevenuesResponse struct {
	RevenueTrend         *RevenueTrendResponse         `json:"revenue_trend,omitempty"`
	RecentSubscriptions  *RecentSubscriptionsResponse  `json:"recent_subscriptions,omitempty"`
	InvoicePaymentStatus *InvoicePaymentStatusResponse `json:"invoice_payment_status,omitempty"`
}

type DeleteCostsheetResponse struct {
	Message string `json:"message"`
	ID      string `json:"id"`
}

type DeletePriceRequest struct {
	EndDate *time.Time `json:"end_date,omitempty"`
}

type DeleteSubscriptionLineItemRequest struct {
	EffectiveFrom *time.Time `json:"effective_from,omitempty"`
}

type DiscountResult struct {
	Discount   decimal.Decimal // The discount amount applied
	FinalPrice decimal.Decimal // The final price after discount
}

type EntitlementResponse struct {
	*entitlement.Entitlement
	Feature *FeatureResponse `json:"feature,omitempty"`
	Plan    *PlanResponse    `json:"plan,omitempty"`
	Addon   *AddonResponse   `json:"addon,omitempty"`

	// TODO: Remove this once we have a proper entitlement entity type
	PlanID string `json:"plan_id,omitempty"`
}

type EntitlementSource struct {
	SubscriptionID   string                      `json:"subscription_id"`
	EntityID         string                      `json:"entity_id"`
	EntityType       EntitlementSourceEntityType `json:"entity_type"`
	Quantity         int64                       `json:"quantity"`
	EntityName       string                      `json:"entity_name"`
	EntitlementID    string                      `json:"entitlement_id"`
	IsEnabled        bool                        `json:"is_enabled"`
	UsageLimit       *int64                      `json:"usage_limit,omitempty"`
	StaticValue      string                      `json:"static_value,omitempty"`
	UsageResetPeriod types.BillingPeriod         `json:"usage_reset_period,omitempty"`
}

type EntitlementSourceEntityType string

type EntityIntegrationMappingResponse struct {
	ID               string                      `json:"id"`
	EntityID         string                      `json:"entity_id"`
	EntityType       types.IntegrationEntityType `json:"entity_type"`
	ProviderType     string                      `json:"provider_type"`
	ProviderEntityID string                      `json:"provider_entity_id"`
	EnvironmentID    string                      `json:"environment_id"`
	TenantID         string                      `json:"tenant_id"`
	Status           types.Status                `json:"status"`
	CreatedAt        string                      `json:"created_at"`
	UpdatedAt        string                      `json:"updated_at"`
	CreatedBy        string                      `json:"created_by"`
	UpdatedBy        string                      `json:"updated_by"`
}

type EnvironmentResponse struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Type      string `json:"type"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

type Event struct {
	ID                 string                 `json:"id"`
	ExternalCustomerID string                 `json:"external_customer_id"`
	CustomerID         string                 `json:"customer_id"`
	EventName          string                 `json:"event_name"`
	Timestamp          time.Time              `json:"timestamp"`
	Properties         map[string]interface{} `json:"properties"`
	Source             string                 `json:"source"`
	EnvironmentID      string                 `json:"environment_id"`
}

type EventCostInfo struct {
	EventID       string          `json:"requestId"`
	CostInNanoUSD decimal.Decimal `json:"costNanoUsd" swaggertype:"string"`
}

type EventCountPoint struct {
	Timestamp  time.Time `json:"timestamp"`
	EventCount uint64    `json:"event_count"`
}

type ExpiredCreditsResponse struct {
	Items   []*ExpiredCreditsResponseItem `json:"items"`
	Total   int                           `json:"total"`
	Success int                           `json:"success"`
	Failed  int                           `json:"failed"`
}

type ExpiredCreditsResponseItem struct {
	TenantID      string `json:"tenant_id"`
	EnvironmentID string `json:"environment_id"`
	Count         int    `json:"count"`
}

type ExportRequest struct {
	EntityType   types.ScheduledTaskEntityType `json:"entity_type"`
	ConnectionID string                        `json:"connection_id"` // Connection ID for S3 credentials
	TenantID     string                        `json:"tenant_id"`
	EnvID        string                        `json:"env_id"`
	StartTime    time.Time                     `json:"start_time"`
	EndTime      time.Time                     `json:"end_time"`
	JobConfig    *types.S3JobConfig            `json:"job_config"` // S3 job configuration from scheduled_tasks
}

type ExportResponse struct {
	EntityType    types.ScheduledTaskEntityType `json:"entity_type"`
	RecordCount   int                           `json:"record_count"`
	FileURL       string                        `json:"file_url"`
	FileSizeBytes int64                         `json:"file_size_bytes"`
	ExportedAt    time.Time                     `json:"exported_at"`
}

type FeatureResponse struct {
	*feature.Feature
	Meter *MeterResponse `json:"meter,omitempty"`
}

type FeatureUsageSummary struct {
	Feature          *FeatureResponse     `json:"feature"`
	TotalLimit       *int64               `json:"total_limit"`
	IsUnlimited      bool                 `json:"is_unlimited"`
	CurrentUsage     decimal.Decimal      `json:"current_usage" swaggertype:"string"`
	UsagePercent     decimal.Decimal      `json:"usage_percent" swaggertype:"string"`
	IsEnabled        bool                 `json:"is_enabled"`
	IsSoftLimit      bool                 `json:"is_soft_limit"`
	NextUsageResetAt *time.Time           `json:"next_usage_reset_at"`
	Sources          []*EntitlementSource `json:"sources"`
}

type GatewayInfo struct {
	Type        types.PaymentGatewayType `json:"type"`
	Name        string                   `json:"name"`
	IsActive    bool                     `json:"is_active"`
	IsPreferred bool                     `json:"is_preferred"`
	Metadata    types.Metadata           `json:"metadata,omitempty"`
}

type GenericPaymentStatusResponse struct {
	SessionID       string            `json:"session_id"`
	PaymentIntentID string            `json:"payment_intent_id,omitempty"`
	Status          string            `json:"status"`
	Amount          decimal.Decimal   `json:"amount"`
	Currency        string            `json:"currency"`
	CustomerID      string            `json:"customer_id,omitempty"`
	CreatedAt       int64             `json:"created_at"`
	ExpiresAt       int64             `json:"expires_at,omitempty"`
	Metadata        map[string]string `json:"metadata,omitempty"`
	Gateway         string            `json:"gateway"`
}

type GetActiveAddonAssociationRequest struct {
	AddonIds   []string                         `json:"addon_ids,omitempty"`
	EntityID   string                           `json:"entity_id" validate:"required"`
	EntityType types.AddonAssociationEntityType `json:"entity_type" validate:"required"`
	StartDate  *time.Time                       `json:"start_date,omitempty"`
	EndDate    *time.Time                       `json:"end_date,omitempty"`
}

type GetCostAnalyticsRequest struct {
	// Time range fields (optional - defaults to last 7 days if not provided)
	StartTime time.Time `json:"start_time,omitempty"`
	EndTime   time.Time `json:"end_time,omitempty"`

	ExternalCustomerID string `json:"external_customer_id,omitempty"` // Optional - for specific customer

	// Additional filters
	FeatureIDs []string `json:"feature_ids,omitempty"`

	// Expand options - specify which entities to expand
	Expand []string `json:"expand,omitempty"` // "meter", "price"

	// Pagination
	Limit  int `json:"limit,omitempty"`
	Offset int `json:"offset,omitempty"`
}

type GetCostAnalyticsResponse struct {
	CustomerID         string    `json:"customer_id,omitempty"`
	ExternalCustomerID string    `json:"external_customer_id,omitempty"`
	CostsheetID        string    `json:"costsheet_id,omitempty"`
	StartTime          time.Time `json:"start_time"`
	EndTime            time.Time `json:"end_time"`
	Currency           string    `json:"currency"`

	// Summary
	TotalCost     decimal.Decimal `json:"total_cost" swaggertype:"string"`
	TotalQuantity decimal.Decimal `json:"total_quantity" swaggertype:"string"`
	TotalEvents   int64           `json:"total_events"`

	// Detailed breakdown
	CostAnalytics []CostAnalyticItem `json:"cost_analytics"`

	// Time-series (if requested)
	CostTimeSeries []CostPoint `json:"cost_time_series,omitempty"`

	// Pagination
	Pagination *types.PaginationResponse `json:"pagination,omitempty"`
}

type GetCostBreakdownRequest struct {
	// SubscriptionID to get the time period from if StartTime and EndTime are not provided
	SubscriptionID string `json:"subscription_id" validate:"required"`

	// Optional time range. If not provided, uses subscription period
	StartTime *time.Time `json:"start_time,omitempty"`
	EndTime   *time.Time `json:"end_time,omitempty"`
}

type GetCostsheetResponse struct {
	Costsheet *CostsheetResponse `json:"costsheet"`
}

type GetCustomerEntitlementsRequest struct {
	FeatureIDs      []string `json:"feature_ids,omitempty" form:"feature_ids"`
	SubscriptionIDs []string `json:"subscription_ids,omitempty" form:"subscription_ids"`
}

type GetCustomerPaymentMethodsRequest struct {
	CustomerID string `json:"customer_id" binding:"required"`
}

type GetCustomerUsageSummaryRequest struct {
	CustomerID        string   `json:"customer_id,omitempty" form:"customer_id"`
	CustomerLookupKey string   `json:"customer_lookup_key,omitempty" form:"customer_lookup_key"`
	FeatureIDs        []string `json:"feature_ids,omitempty" form:"feature_ids"`
	FeatureLookupKeys []string `json:"feature_lookup_keys,omitempty" form:"feature_lookup_keys"`
	SubscriptionIDs   []string `json:"subscription_ids,omitempty" form:"subscription_ids"`
}

type GetCustomerWalletsRequest struct {
	ID                     string `form:"id"`
	LookupKey              string `form:"lookup_key"`
	IncludeRealTimeBalance bool   `form:"include_real_time_balance" default:"false"`
	Expand                 string `form:"expand"`
}

type GetDefaultPaymentMethodRequest struct {
	CustomerID string `json:"customer_id" binding:"required"`
}

type GetDetailedCostAnalyticsResponse struct {
	// Cost analytics array (flattened from nested structure)
	CostAnalytics []CostAnalyticItem `json:"cost_analytics"`

	// Derived metrics
	TotalRevenue  decimal.Decimal `json:"total_revenue" swaggertype:"string"`
	TotalCost     decimal.Decimal `json:"total_cost" swaggertype:"string"`
	Margin        decimal.Decimal `json:"margin" swaggertype:"string"`         // Revenue - Cost
	MarginPercent decimal.Decimal `json:"margin_percent" swaggertype:"string"` // (Margin / Revenue) * 100
	ROI           decimal.Decimal `json:"roi" swaggertype:"string"`            // (Revenue - Cost) / Cost
	ROIPercent    decimal.Decimal `json:"roi_percent" swaggertype:"string"`    // ROI * 100

	Currency  string    `json:"currency"`
	StartTime time.Time `json:"start_time"`
	EndTime   time.Time `json:"end_time"`
}

type GetEventsRequest struct {
	// Customer ID in your system that was sent with the event
	ExternalCustomerID string `json:"external_customer_id"`
	// Event name / Unique identifier for the event in your system
	EventName string `json:"event_name"`
	// Event ID is the idempotency key for the event
	EventID string `json:"event_id"`
	// Start time of the events to be fetched in ISO 8601 format
	// Defaults to last 7 days from now if not provided
	StartTime time.Time `json:"start_time" example:"2024-11-09T00:00:00Z"`
	// End time of the events to be fetched in ISO 8601 format
	// Defaults to now if not provided
	EndTime time.Time `json:"end_time" example:"2024-12-09T00:00:00Z"`
	// First key to iterate over the events
	IterFirstKey string `json:"iter_first_key"`
	// Last key to iterate over the events
	IterLastKey string `json:"iter_last_key"`
	// Property filters to filter the events by the keys in `properties` field of the event
	PropertyFilters map[string][]string `json:"property_filters,omitempty"`
	// Page size to fetch the events and is set to 50 by default
	PageSize int `json:"page_size"`
	// Offset to fetch the events and is set to 0 by default
	Offset int `json:"offset"`
	// Source to filter the events by the source
	Source string `json:"source"`
	// Sort by the field. Allowed values (case sensitive): timestamp, event_name (default: timestamp)
	Sort *string `json:"sort,omitempty" form:"sort" example:"timestamp"`
	// Order by condition. Allowed values (case sensitive): asc, desc (default: desc)
	Order *string `json:"order,omitempty" form:"order" example:"desc"`
	// Count of total number of events
	CountTotal bool `json:"-"`
}

type GetEventsResponse struct {
	Events       []Event `json:"events"`
	HasMore      bool    `json:"has_more"`
	IterFirstKey string  `json:"iter_first_key,omitempty"`
	IterLastKey  string  `json:"iter_last_key,omitempty"`
	TotalCount   uint64  `json:"total_count,omitempty"`
	Offset       int     `json:"offset,omitempty"`
}

type GetHuggingFaceBillingDataRequest struct {
	EventIDs []string `json:"requestIds" binding:"required,min=1"`
}

type GetHuggingFaceBillingDataResponse struct {
	Data []EventCostInfo `json:"requests"`
}

type GetInvoiceWithBreakdownRequest struct {
	// ID is the unique identifier of the invoice
	ID string `json:"id" validate:"required"`

	// GroupBy contains the grouping parameters for flexible usage breakdown
	GroupBy []string `json:"group_by,omitempty"`

	// Force Runtime recalculation of usage breakdown
	ForceRuntimeRecalculation bool `json:"force_runtime_recalculation,omitempty" default:"false"`
}

type GetMonitoringDataRequest struct {
	StartTime  time.Time        `json:"start_time,omitempty" form:"start_time"`
	EndTime    time.Time        `json:"end_time,omitempty" form:"end_time"`
	WindowSize types.WindowSize `json:"window_size,omitempty" form:"window_size"`
}

type GetMonitoringDataResponse struct {
	TotalCount        uint64            `json:"total_count"`
	ConsumptionLag    int64             `json:"consumption_lag"`
	PostProcessingLag int64             `json:"post_processing_lag"`
	Points            []EventCountPoint `json:"points,omitempty"`
}

type GetPendingSchedulesResponse struct {
	// schedules is the list of pending schedules
	Schedules []*SubscriptionScheduleResponse `json:"schedules"`

	// count is the number of pending schedules
	Count int `json:"count"`
}

type GetPreviewInvoiceRequest struct {
	// subscription_id is the unique identifier of the subscription to preview invoice for
	SubscriptionID string `json:"subscription_id" binding:"required"`

	// period_start is the optional start date of the period to preview
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the optional end date of the period to preview
	PeriodEnd *time.Time `json:"period_end,omitempty"`
}

type GetPricesByPlanRequest struct {
	PlanID       string `json:"plan_id" validate:"required"`
	AllowExpired bool   `json:"allow_expired,omitempty"`
}

type GetSubscriptionEntitlementsRequest struct {
	FeatureIDs []string `json:"feature_ids,omitempty" form:"feature_ids"`
}

type GetSupportedGatewaysResponse struct {
	Gateways []GatewayInfo `json:"gateways"`
}

type GetUnpaidInvoicesToBePaidRequest struct {
	// customer_id is the unique identifier of the customer
	CustomerID string `json:"customer_id" validate:"required"`

	// currency is the three-letter ISO currency code for this request
	Currency string `json:"currency" validate:"required"`
}

type GetUnpaidInvoicesToBePaidResponse struct {
	// invoices is the list of unpaid invoices to be paid
	Invoices []*InvoiceResponse `json:"invoices"`

	// total_unpaid_amount is the total amount of unpaid invoices to be paid
	TotalUnpaidAmount decimal.Decimal `json:"total_unpaid_amount" swaggertype:"string"`

	// total_unpaid_usage_charges is the total amount of unpaid usage charges to be paid
	TotalUnpaidUsageCharges decimal.Decimal `json:"total_unpaid_usage_charges" swaggertype:"string"`

	// total_unpaid_fixed_charges is the total amount of unpaid fixed charges to be paid
	TotalUnpaidFixedCharges decimal.Decimal `json:"total_unpaid_fixed_charges" swaggertype:"string"`
}

type GetUpcomingCreditGrantApplicationsRequest struct {
	// SubscriptionIDs is a list of subscription IDs to get upcoming credit grant applications for
	// This allows querying multiple subscriptions at once, useful for customer-level queries
	SubscriptionIDs []string `json:"subscription_ids" binding:"required,min=1" validate:"required,min=1"`
}

type GetUsageAnalyticsRequest struct {
	ExternalCustomerID string           `json:"external_customer_id" binding:"required"`
	FeatureIDs         []string         `json:"feature_ids,omitempty"`
	Sources            []string         `json:"sources,omitempty"`
	StartTime          time.Time        `json:"start_time,omitempty"`
	EndTime            time.Time        `json:"end_time,omitempty"`
	GroupBy            []string         `json:"group_by,omitempty"` // allowed values: "source", "feature_id", "properties.<field_name>"
	WindowSize         types.WindowSize `json:"window_size,omitempty"`
	Expand             []string         `json:"expand,omitempty"` // allowed values: "price", "meter", "feature", "subscription_line_item","plan","addon"
	// Property filters to filter the events by the keys in `properties` field of the event
	PropertyFilters map[string][]string `json:"property_filters,omitempty"`
}

type GetUsageAnalyticsResponse struct {
	TotalCost decimal.Decimal     `json:"total_cost" swaggertype:"string"`
	Currency  string              `json:"currency"`
	Items     []UsageAnalyticItem `json:"items"`
}

type GetUsageByMeterRequest struct {
	MeterID            string              `form:"meter_id" json:"meter_id" binding:"required" example:"123"`
	PriceID            string              `form:"-" json:"-"` // this is just for internal use to store the price id
	Meter              *meter.Meter        `form:"-" json:"-"` // caller can set this in case already fetched from db to avoid extra db call
	ExternalCustomerID string              `form:"external_customer_id" json:"external_customer_id" example:"user_5"`
	CustomerID         string              `form:"customer_id" json:"customer_id" example:"customer456"`
	StartTime          time.Time           `form:"start_time" json:"start_time" example:"2024-11-09T00:00:00Z"`
	EndTime            time.Time           `form:"end_time" json:"end_time" example:"2024-12-09T00:00:00Z"`
	WindowSize         types.WindowSize    `form:"window_size" json:"window_size"`
	BucketSize         types.WindowSize    `form:"bucket_size" json:"bucket_size,omitempty" example:"HOUR"` // Optional, only used for MAX aggregation with windowing
	Filters            map[string][]string `form:"filters,omitempty" json:"filters,omitempty"`
	// BillingAnchor enables custom monthly billing periods for meter usage aggregation.
	//
	// Usage guidelines:
	// - Only effective when WindowSize = "MONTH"
	// - For other window sizes (DAY, HOUR, WEEK), this field is ignored
	// - When nil, uses standard calendar months (1st to 1st)
	// - When provided, creates custom monthly periods (e.g., 5th to 5th)
	//
	// Common use cases:
	// - Subscription billing periods that don't align with calendar months
	// - Customer-specific billing cycles (e.g., signed up on 15th)
	// - Multi-tenant systems with different billing anchor dates
	//
	// Example: If BillingAnchor = "2024-03-05T14:30:45Z" and WindowSize = "MONTH":
	//   - March period: 2024-03-05 14:30:45 to 2024-04-05 14:30:45
	//   - April period: 2024-04-05 14:30:45 to 2024-05-05 14:30:45
	BillingAnchor *time.Time `form:"billing_anchor" json:"billing_anchor,omitempty" example:"2024-03-05T14:30:45Z"`
}

type GetUsageBySubscriptionRequest struct {
	SubscriptionID string    `json:"subscription_id" binding:"required" example:"123"`
	StartTime      time.Time `json:"start_time" example:"2024-03-13T00:00:00Z"`
	EndTime        time.Time `json:"end_time" example:"2024-03-20T00:00:00Z"`
	LifetimeUsage  bool      `json:"lifetime_usage" example:"false"`
}

type GetUsageBySubscriptionResponse struct {
	Amount             float64                              `json:"amount"`
	Currency           string                               `json:"currency"`
	DisplayAmount      string                               `json:"display_amount"`
	StartTime          time.Time                            `json:"start_time"`
	EndTime            time.Time                            `json:"end_time"`
	Charges            []*SubscriptionUsageByMetersResponse `json:"charges"`
	CommitmentAmount   float64                              `json:"commitment_amount,omitempty"`
	OverageFactor      float64                              `json:"overage_factor,omitempty"`
	CommitmentUtilized float64                              `json:"commitment_utilized,omitempty"` // Amount of commitment used
	OverageAmount      float64                              `json:"overage_amount,omitempty"`      // Amount charged at overage rate
	HasOverage         bool                                 `json:"has_overage"`                   // Whether any usage exceeded commitment
}

type GetUsageRequest struct {
	ExternalCustomerID string                `form:"external_customer_id" json:"external_customer_id" example:"customer456"`
	CustomerID         string                `form:"customer_id" json:"customer_id" example:"customer456"`
	EventName          string                `form:"event_name" json:"event_name" binding:"required" required:"true" example:"api_request"`
	PropertyName       string                `form:"property_name" json:"property_name" example:"request_size"` // will be empty/ignored in case of COUNT
	AggregationType    types.AggregationType `form:"aggregation_type" json:"aggregation_type" binding:"required"`
	StartTime          time.Time             `form:"start_time" json:"start_time" example:"2024-03-13T00:00:00Z"`
	EndTime            time.Time             `form:"end_time" json:"end_time" example:"2024-03-20T00:00:00Z"`
	WindowSize         types.WindowSize      `form:"window_size" json:"window_size"`
	BucketSize         types.WindowSize      `form:"bucket_size" json:"bucket_size,omitempty" example:"HOUR"` // Optional, only used for MAX aggregation with windowing
	Filters            map[string][]string   `form:"filters,omitempty" json:"filters,omitempty"`
	PriceID            string                `form:"-" json:"-"` // this is just for internal use to store the price id
	MeterID            string                `form:"-" json:"-"` // this is just for internal use to store the meter id
	Multiplier         *decimal.Decimal      `form:"multiplier" json:"multiplier,omitempty" swaggertype:"string"`
	// BillingAnchor enables custom monthly billing periods for usage aggregation.
	//
	// When to use:
	// - WindowSize = "MONTH" AND you need custom monthly periods (not calendar months)
	// - Subscription billing that doesn't align with calendar months
	// - Example: Customer signed up on 15th, so billing periods are 15th to 15th
	//
	// When NOT to use:
	// - WindowSize != "MONTH" (ignored for DAY, HOUR, WEEK, etc.)
	// - Standard calendar-based billing (1st to 1st of each month)
	//
	// Example values:
	// - "2024-03-05T14:30:45.123456789Z" (5th of each month at 2:30:45 PM)
	// - "2024-01-15T00:00:00Z" (15th of each month at midnight)
	// - "2024-02-29T12:00:00Z" (29th of each month at noon - handles leap years)
	BillingAnchor *time.Time `form:"billing_anchor" json:"billing_anchor,omitempty" example:"2024-03-05T14:30:45.123456789Z"`
}

type GetUsageResponse struct {
	Results   []UsageResult         `json:"results,omitempty"`
	Value     float64               `json:"value,omitempty"`
	EventName string                `json:"event_name"`
	Type      types.AggregationType `json:"type"`
}

type GroupResponse struct {
	ID         string            `json:"id"`
	Name       string            `json:"name"`
	LookupKey  string            `json:"lookup_key"`
	EntityType string            `json:"entity_type"`
	EntityIDs  []string          `json:"entity_ids"`
	Status     string            `json:"status"`
	Metadata   map[string]string `json:"metadata"`
	CreatedAt  time.Time         `json:"created_at"`
	UpdatedAt  time.Time         `json:"updated_at"`
}

type IngestEventRequest struct {
	EventName          string                 `json:"event_name" validate:"required" binding:"required" example:"api_request" csv:"event_name"`
	EventID            string                 `json:"event_id" example:"event123" csv:"event_id"`
	CustomerID         string                 `json:"customer_id" example:"customer456" csv:"customer_id"`
	ExternalCustomerID string                 `json:"external_customer_id" validate:"required" binding:"required" example:"customer456" csv:"external_customer_id"`
	Timestamp          time.Time              `json:"timestamp" example:"2024-03-20T15:04:05Z" csv:"-"` // Handled separately due to parsing
	TimestampStr       string                 `json:"-" csv:"timestamp"`                                // Used for CSV parsing
	Source             string                 `json:"source" example:"api" csv:"source"`
	Properties         map[string]interface{} `json:"properties" swaggertype:"object,string,number" example:"{\"request_size\":100,\"response_status\":200}" csv:"-"` // Handled separately for dynamic columns
}

type InitiateOAuthRequest struct {
	Provider    types.OAuthProvider `json:"provider" binding:"required"`    // e.g., "quickbooks"
	Name        string              `json:"name" binding:"required"`        // Connection name
	Credentials map[string]string   `json:"credentials" binding:"required"` // Provider-specific credentials (all required for the provider)
	Metadata    map[string]string   `json:"metadata" binding:"required"`    // Provider-specific metadata (all required for the provider)
	SyncConfig  *types.SyncConfig   `json:"sync_config"`                    // Optional sync configuration for the connection
}

type InitiateOAuthResponse struct {
	OAuthURL  string `json:"oauth_url"`
	SessionID string `json:"session_id"`
}

type IntegrationEntityMapping struct {
	// provider is the integration provider name (e.g., "stripe", "razorpay")
	Provider string `json:"provider" validate:"required,oneof=stripe razorpay paypal"`

	// id is the external entity ID from the provider
	ID string `json:"id" validate:"required"`
}

type InvoiceCoupon struct {
	CouponID            string  `json:"coupon_id" validate:"required"`
	CouponAssociationID *string `json:"coupon_association_id,omitempty"`
}

type InvoiceLineItemCoupon struct {
	LineItemID          string  `json:"line_item_id" validate:"required"` // price_id used to match the line item
	CouponID            string  `json:"coupon_id" validate:"required"`
	CouponAssociationID *string `json:"coupon_association_id,omitempty"`
}

type InvoiceLineItemPreview struct {
	// description of the line item
	Description string `json:"description"`

	// amount for this line item
	Amount decimal.Decimal `json:"amount" swaggertype:"string"`

	// quantity for this line item
	Quantity decimal.Decimal `json:"quantity" swaggertype:"string"`

	// unit_price for this line item
	UnitPrice decimal.Decimal `json:"unit_price" swaggertype:"string"`

	// period_start for this line item (if applicable)
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end for this line item (if applicable)
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// is_proration indicates if this line item is a proration
	IsProration bool `json:"is_proration"`
}

type InvoiceLineItemResponse struct {
	// id is the unique identifier for this line item
	ID string `json:"id"`

	// invoice_id is the unique identifier of the invoice this line item belongs to
	InvoiceID string `json:"invoice_id"`

	// customer_id is the unique identifier of the customer associated with this line item
	CustomerID string `json:"customer_id"`

	// subscription_id is the optional unique identifier of the subscription associated with this line item
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// price_id is the optional unique identifier of the price associated with this line item
	PriceID *string `json:"price_id"`

	// plan_id is the optional unique identifier of the plan associated with this line item
	PlanID *string `json:"plan_id,omitempty"`

	// entity_id is the optional unique identifier of the entity associated with this line item
	EntityID *string `json:"entity_id,omitempty"`

	// entity_type is the optional type of the entity associated with this line item
	EntityType *string `json:"entity_type,omitempty"`

	// plan_display_name is the optional human-readable name of the plan
	PlanDisplayName *string `json:"plan_display_name,omitempty"`

	// price_type indicates the type of pricing (fixed, usage, tiered, etc.)
	PriceType *string `json:"price_type,omitempty"`

	// meter_id is the optional unique identifier of the meter used for usage tracking
	MeterID *string `json:"meter_id,omitempty"`

	// meter_display_name is the optional human-readable name of the meter
	MeterDisplayName *string `json:"meter_display_name,omitempty"`

	// price_unit_id is the optional unique identifier of the price unit associated with this line item
	PriceUnitID *string `json:"price_unit_id,omitempty"`

	// price_unit is the optional 3-digit ISO code of the price unit associated with this line item
	PriceUnit *string `json:"price_unit,omitempty"`

	// price_unit_amount is the optional amount converted to the price unit currency
	PriceUnitAmount *decimal.Decimal `json:"price_unit_amount,omitempty" swaggertype:"string"`

	// display_name is the optional human-readable name for this line item
	DisplayName *string `json:"display_name,omitempty"`

	// amount is the monetary amount for this line item
	Amount decimal.Decimal `json:"amount" swaggertype:"string"`

	// quantity is the quantity of units for this line item
	Quantity decimal.Decimal `json:"quantity" swaggertype:"string"`

	// currency is the three-letter ISO currency code for this line item
	Currency string `json:"currency"`

	// period_start is the optional start date of the period this line item covers
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the optional end date of the period this line item covers
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information about this line item
	Metadata types.Metadata `json:"metadata,omitempty"`

	// tenant_id is the unique identifier of the tenant this line item belongs to
	TenantID string `json:"tenant_id"`

	// status represents the current status of this line item
	Status string `json:"status"`

	// created_at is the timestamp when this line item was created
	CreatedAt time.Time `json:"created_at"`

	// updated_at is the timestamp when this line item was last updated
	UpdatedAt time.Time `json:"updated_at"`

	// created_by is the identifier of the user who created this line item
	CreatedBy string `json:"created_by,omitempty"`

	// updated_by is the identifier of the user who last updated this line item
	UpdatedBy string `json:"updated_by,omitempty"`

	// usage_analytics contains usage analytics for this line item (legacy - grouped by source)
	UsageAnalytics []SourceUsageItem `json:"usage_analytics,omitempty"`

	// usage_breakdown contains flexible usage breakdown for this line item (supports any grouping)
	UsageBreakdown []UsageBreakdownItem `json:"usage_breakdown,omitempty"`

	// commitment_info contains details about any commitment applied to this line item
	CommitmentInfo *types.CommitmentInfo `json:"commitment_info,omitempty"`
}

type InvoicePaymentStatusResponse struct {
	Paid        int       `json:"paid"`    // Maps to InvoicePaymentStatus.Succeeded
	Pending     int       `json:"pending"` // Maps to InvoicePaymentStatus.Pending
	Failed      int       `json:"failed"`  // Maps to InvoicePaymentStatus.Failed
	PeriodStart time.Time `json:"period_start"`
	PeriodEnd   time.Time `json:"period_end"`
}

type InvoicePreview struct {
	// subtotal is the subtotal amount before taxes
	Subtotal decimal.Decimal `json:"subtotal" swaggertype:"string"`

	// tax_amount is the total tax amount
	TaxAmount decimal.Decimal `json:"tax_amount" swaggertype:"string"`

	// total is the total amount including taxes
	Total decimal.Decimal `json:"total" swaggertype:"string"`

	// currency is the currency for all amounts
	Currency string `json:"currency"`

	// line_items contains preview of line items
	LineItems []InvoiceLineItemPreview `json:"line_items"`

	// due_date is when the invoice would be due
	DueDate *time.Time `json:"due_date,omitempty"`
}

type InvoiceResponse struct {
	// id is the unique identifier for this invoice
	ID string `json:"id"`

	// customer_id is the unique identifier of the customer this invoice belongs to
	CustomerID string `json:"customer_id"`

	// subscription_id is the optional unique identifier of the subscription associated with this invoice
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// invoice_type indicates the type of invoice (subscription, one_time, etc.)
	InvoiceType types.InvoiceType `json:"invoice_type"`

	// invoice_status represents the current status of the invoice (draft, finalized, etc.)
	InvoiceStatus types.InvoiceStatus `json:"invoice_status"`

	// payment_status represents the payment status of the invoice (unpaid, paid, etc.)
	PaymentStatus types.PaymentStatus `json:"payment_status"`

	// currency is the three-letter ISO currency code (e.g., USD, EUR) for the invoice
	Currency string `json:"currency"`

	// amount_due is the total amount that needs to be paid for this invoice
	AmountDue decimal.Decimal `json:"amount_due" swaggertype:"string"`

	// total is the total amount of the invoice including taxes and discounts
	Total decimal.Decimal `json:"total" swaggertype:"string"`

	// total_discount is the total discount amount from coupon applications
	TotalDiscount decimal.Decimal `json:"total_discount" swaggertype:"string"`

	// subtotal is the amount before taxes and discounts are applied
	Subtotal decimal.Decimal `json:"subtotal" swaggertype:"string"`

	// amount_paid is the amount that has been paid towards this invoice
	AmountPaid decimal.Decimal `json:"amount_paid" swaggertype:"string"`

	// amount_remaining is the amount still outstanding on this invoice
	AmountRemaining decimal.Decimal `json:"amount_remaining" swaggertype:"string"`

	// overpaid_amount is the amount overpaid if payment_status is OVERPAID (amount_paid - total)
	OverpaidAmount *decimal.Decimal `json:"overpaid_amount,omitempty" swaggertype:"string"`

	// invoice_number is the optional human-readable identifier for the invoice
	InvoiceNumber *string `json:"invoice_number,omitempty"`

	// idempotency_key is the optional key used to prevent duplicate invoice creation
	IdempotencyKey *string `json:"idempotency_key,omitempty"`

	// billing_sequence is the optional sequence number for billing cycles
	BillingSequence *int `json:"billing_sequence,omitempty"`

	// description is the optional text description of the invoice
	Description string `json:"description,omitempty"`

	// due_date is the date by which payment is expected
	DueDate *time.Time `json:"due_date,omitempty"`

	// billing_period is the period this invoice covers (e.g., "monthly", "yearly")
	BillingPeriod *string `json:"billing_period,omitempty"`

	// period_start is the start date of the billing period
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the end date of the billing period
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// paid_at is the timestamp when this invoice was paid
	PaidAt *time.Time `json:"paid_at,omitempty"`

	// voided_at is the timestamp when this invoice was voided
	VoidedAt *time.Time `json:"voided_at,omitempty"`

	// finalized_at is the timestamp when this invoice was finalized
	FinalizedAt *time.Time `json:"finalized_at,omitempty"`

	// invoice_pdf_url is the optional URL to the PDF version of this invoice
	InvoicePDFURL *string `json:"invoice_pdf_url,omitempty"`

	// billing_reason indicates why this invoice was created (subscription_cycle, manual, etc.)
	BillingReason string `json:"billing_reason,omitempty"`

	// line_items contains the individual items that make up this invoice
	LineItems []*InvoiceLineItemResponse `json:"line_items,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information
	Metadata types.Metadata `json:"metadata,omitempty"`

	// version is the version number of this invoice
	Version int `json:"version"`

	// tenant_id is the unique identifier of the tenant this invoice belongs to
	TenantID string `json:"tenant_id"`

	// status represents the current status of this invoice
	Status string `json:"status"`

	// created_at is the timestamp when this invoice was created
	CreatedAt time.Time `json:"created_at"`

	// updated_at is the timestamp when this invoice was last updated
	UpdatedAt time.Time `json:"updated_at"`

	// created_by is the identifier of the user who created this invoice
	CreatedBy string `json:"created_by,omitempty"`

	// updated_by is the identifier of the user who last updated this invoice
	UpdatedBy string `json:"updated_by,omitempty"`

	// subscription contains the associated subscription information if requested
	Subscription *SubscriptionResponse `json:"subscription,omitempty"`

	// customer contains the customer information associated with this invoice
	Customer *CustomerResponse `json:"customer,omitempty"`

	// total_tax is the total tax amount for this invoice
	TotalTax decimal.Decimal `json:"total_tax" swaggertype:"string"`

	// tax_applied_records contains the tax applied records associated with this invoice
	Taxes []*TaxAppliedResponse `json:"taxes,omitempty"`
	// coupon_applications contains the coupon applications associated with this invoice
	CouponApplications []*CouponApplicationResponse `json:"coupon_applications,omitempty"`
}

type InvoiceVoidRequest struct {
	// metadata will only add/override the values of key-value pairs provided in this request.
	// for a complete override of metadata field, refer update invoice (PUT /invoices) endpoint
	Metadata types.Metadata `json:"metadata,omitempty"`
}

type LineItemCommitmentConfig struct {
	// CommitmentAmount is the minimum amount committed for this line item
	CommitmentAmount *decimal.Decimal `json:"commitment_amount,omitempty"`

	// CommitmentQuantity is the minimum quantity committed for this line item
	CommitmentQuantity *decimal.Decimal `json:"commitment_quantity,omitempty"`

	// CommitmentType specifies whether commitment is based on amount or quantity
	CommitmentType types.CommitmentType `json:"commitment_type,omitempty"`

	// OverageFactor is a multiplier applied to usage beyond the commitment
	OverageFactor *decimal.Decimal `json:"overage_factor,omitempty"`

	// EnableTrueUp determines if true-up fee should be applied when usage is below commitment
	EnableTrueUp *bool `json:"enable_true_up,omitempty"`

	// IsWindowCommitment determines if commitment is applied per window (e.g., per day) rather than per billing period
	IsWindowCommitment *bool `json:"is_window_commitment,omitempty"`
}

type LineItemParams struct {
	Subscription *SubscriptionResponse
	Price        *PriceResponse
	Plan         *PlanResponse  // Optional, for plan-based line items
	Addon        *AddonResponse // Optional, for addon-based line items
	EntityType   types.SubscriptionLineItemEntityType
}

type LinkTaxRateToEntityRequest struct {
	TaxRateOverrides        []*TaxRateOverride        `json:"tax_rate_overrides" binding:"omitempty"`
	ExistingTaxAssociations []*TaxAssociationResponse `json:"existing_tax_associations" binding:"omitempty"`
	EntityType              types.TaxRateEntityType   `json:"entity_type" binding:"required" default:"tenant"`
	EntityID                string                    `json:"entity_id" binding:"required"`
}

type LinkedIntegrationsResponse struct {
	Providers []string `json:"providers"`
}

type ListAddonAssociationsResponse = types.ListResponse[*AddonAssociationResponse]