dto

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"`
	EndDate   *time.Time             `json:"end_date,omitempty"`
	Metadata  map[string]interface{} `json:"metadata"`
}

type AddSchedulePhaseRequest struct {
	Phase SubscriptionSchedulePhaseInput `json:"phase" validate:"required"`
}

type AddonAssociationResponse struct {
	*addonassociation.AddonAssociation
}

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 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"`
}

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 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"`
}

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"`

	// 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"`
}

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"`
	CreatedAt     string               `json:"created_at"`
	UpdatedAt     string               `json:"updated_at"`
	CreatedBy     string               `json:"created_by"`
	UpdatedBy     string               `json:"updated_by"`
}

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

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

	// Usage is the quantity consumed
	Usage decimal.Decimal `json:"usage"`

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

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

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

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 CostSheetResponse struct {
	ID        string       `json:"id"`
	MeterID   string       `json:"meter_id"`
	PriceID   string       `json:"price_id"`
	Status    types.Status `json:"status"`
	CreatedAt time.Time    `json:"created_at"`
	UpdatedAt time.Time    `json:"updated_at"`
}

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

type CouponAssociationResponse struct {
	*coupon_association.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"`
	Permissions []string         `json:"permissions"`
	ExpiresAt   *time.Time       `json:"expires_at,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"`
}

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 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"`
	FinalPrice          decimal.Decimal        `json:"final_price" validate:"required"`
	DiscountedAmount    decimal.Decimal        `json:"discounted_amount" validate:"required"`
	DiscountType        types.CouponType       `json:"discount_type" validate:"required"`
	DiscountPercentage  *decimal.Decimal       `json:"discount_percentage,omitempty"`
	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"`
	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"`
	PercentageOff     *decimal.Decimal        `json:"percentage_off,omitempty"`
	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 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"`
	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"`
}

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"`

	// 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"`

	// 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"`
}

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"`
}

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"`
}

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"`

	// 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"`

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

	// 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"`
}

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"`

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

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

	// 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"`

	// 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"`
	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"`
	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"`
	Prices       []CreatePlanPriceRequest       `json:"prices"`
	Entitlements []CreatePlanEntitlementRequest `json:"entitlements"`
	CreditGrants []CreateCreditGrantRequest     `json:"credit_grants"`
	Metadata     types.Metadata                 `json:"metadata"`
}

type CreatePlanResponse struct {
	*plan.Plan
}

type CreatePriceRequest struct {
	Amount             string                   `json:"amount,omitempty"`
	Currency           string                   `json:"currency" validate:"required,len=3"`
	PlanID             string                   `json:"plan_id,omitempty"`     // TODO: This is deprecated and will be removed in the future
	EntityType         types.PriceEntityType    `json:"entity_type,omitempty"` // TODO: this will be required in the future as we will not allow prices to be created without an entity type
	EntityID           string                   `json:"entity_id,omitempty"`   // TODO: this will be required in the future as we will not allow prices to be created without an entity id
	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" validate:"required,min=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"`

	// 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:"-"`
}

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 string `json:"unit_amount" validate:"required"`

	// 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 *string `json:"flat_amount" validate:"omitempty"`
}

type CreatePriceUnitRequest struct {
	Name           string           `json:"name" validate:"required"`
	Code           string           `json:"code" validate:"required,len=3"`
	Symbol         string           `json:"symbol" validate:"required,max=10"`
	BaseCurrency   string           `json:"base_currency" validate:"required,len=3"`
	ConversionRate *decimal.Decimal `json:"conversion_rate" validate:"required,gt=0"`
	Precision      int              `json:"precision" validate:"gte=0,lte=8"`
}

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 CreateSettingRequest struct {
	Key   string                 `json:"key" validate:"required,min=1,max=255"`
	Value map[string]interface{} `json:"value,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"`
	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"`
}

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"`
}

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"`
	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" validate:"required,min=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"`
	// OverageFactor is a multiplier applied to usage beyond the commitment amount
	OverageFactor *decimal.Decimal `json:"overage_factor,omitempty"`
	// Phases represents an optional timeline of subscription phases
	Phases []SubscriptionSchedulePhaseInput `json:"phases,omitempty" validate:"omitempty,dive"`
	// tax_rate_overrides is the tax rate overrides	to be applied to the subscription
	TaxRateOverrides []*TaxRateOverride `json:"tax_rate_overrides,omitempty"`
	// SubscriptionCoupons is a list of coupon IDs to be applied to the subscription
	Coupons []string `json:"coupons,omitempty"`
	// SubscriptionLineItemsCoupons is a list of coupon IDs to be applied to the subscription line items
	LineItemCoupons map[string][]string `json:"line_item_coupons,omitempty"`
	// OverrideLineItems allows customizing specific prices for this subscription
	OverrideLineItems []OverrideLineItemRequest `json:"override_line_items,omitempty" validate:"omitempty,dive"`
	// Addons represents addons to be added to the subscription during creation
	Addons []AddAddonToSubscriptionRequest `json:"addons,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:"-"`
}

type CreateSubscriptionScheduleRequest struct {
	SubscriptionID string                           `json:"subscription_id" validate:"required"`
	EndBehavior    types.ScheduleEndBehavior        `json:"end_behavior"`
	Phases         []SubscriptionSchedulePhaseInput `json:"phases" validate:"required,min=1,dive"`
}

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"`
	TaxAmount        decimal.Decimal         `json:"tax_amount" validate:"required"`
	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"`

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

	// 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 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"`
	AutoTopupTrigger    types.AutoTopupTrigger `json:"auto_topup_trigger,omitempty"`
	AutoTopupMinBalance decimal.Decimal        `json:"auto_topup_min_balance,omitempty"`
	AutoTopupAmount     decimal.Decimal        `json:"auto_topup_amount,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"`
	// 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"`
	// 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"`
}

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 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"`

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

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

	// 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"`

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

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
}

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

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

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

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"`
	EntitiyName      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 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"`
	Count    int    `json:"count"`
}

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

type FeatureUsageSummary struct {
	Feature      *FeatureResponse     `json:"feature"`
	TotalLimit   *int64               `json:"total_limit"`
	CurrentUsage decimal.Decimal      `json:"current_usage"`
	UsagePercent decimal.Decimal      `json:"usage_percent"`
	IsEnabled    bool                 `json:"is_enabled"`
	IsSoftLimit  bool                 `json:"is_soft_limit"`
	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 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 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 {
	FeatureIDs      []string `json:"feature_ids,omitempty" form:"feature_ids"`
	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"`
}

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

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 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 GetSupportedGatewaysResponse struct {
	Gateways []GatewayInfo `json:"gateways"`
}

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"`
	// 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"`
	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"`
}

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"`
}

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

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 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"`
	CouponAssociationID *string          `json:"coupon_association_id"`
	AmountOff           *decimal.Decimal `json:"amount_off,omitempty"`
	PercentageOff       *decimal.Decimal `json:"percentage_off,omitempty"`
	Type                types.CouponType `json:"type"`
}

type InvoiceLineItemCoupon struct {
	LineItemID          string           `json:"line_item_id"` // ID of the invoice line item this coupon applies to
	CouponID            string           `json:"coupon_id"`
	CouponAssociationID *string          `json:"coupon_association_id"`
	AmountOff           *decimal.Decimal `json:"amount_off,omitempty"`
	PercentageOff       *decimal.Decimal `json:"percentage_off,omitempty"`
	Type                types.CouponType `json:"type"`
}

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

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

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

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

	// 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"`

	// 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"`

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

	// 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"`
}

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

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

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

	// 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"`

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

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

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

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

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

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

	// 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"`

	// 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 LineItemParams struct {
	Subscription *subscription.Subscription
	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 ListAddonsResponse = types.ListResponse[*AddonResponse]

type ListConnectionsResponse struct {
	Connections []ConnectionResponse `json:"connections"`
	Total       int                  `json:"total"`
	Limit       int                  `json:"limit"`
	Offset      int                  `json:"offset"`
}

type ListCostSheetsResponse struct {
	Items []CostSheetResponse `json:"items"`
	Total int                 `json:"total"`
}

type ListCouponApplicationsResponse = types.ListResponse[*CouponApplicationResponse]

type ListCouponAssociationsResponse = types.ListResponse[*CouponAssociationResponse]

type ListCouponsResponse = types.ListResponse[*CouponResponse]

type ListCreditGrantsResponse = types.ListResponse[*CreditGrantResponse]

type ListCreditNotesResponse = types.ListResponse[*CreditNoteResponse]

type ListCustomersResponse = types.ListResponse[*CustomerResponse]

type ListEntitlementsResponse = types.ListResponse[*EntitlementResponse]

type ListEntityIntegrationMappingsResponse = types.ListResponse[*EntityIntegrationMappingResponse]

type ListEnvironmentsResponse struct {
	Environments []EnvironmentResponse `json:"environments"`
	Total        int                   `json:"total"`
	Offset       int                   `json:"offset"`
	Limit        int                   `json:"limit"`
}

type ListFeaturesResponse = types.ListResponse[*FeatureResponse]

type ListInvoicesResponse = types.ListResponse[*InvoiceResponse]

type ListMetersResponse = types.ListResponse[*MeterResponse]

type ListPaymentsResponse struct {
	Items      []*PaymentResponse       `json:"items"`
	Pagination types.PaginationResponse `json:"pagination"`
}

type ListPlansResponse = types.ListResponse[*PlanResponse]

type ListPriceUnitsResponse = types.ListResponse[*PriceUnitResponse]

type ListPricesResponse = types.ListResponse[*PriceResponse]

type ListSecretsResponse = types.ListResponse[*SecretResponse]

type ListSubscriptionPausesResponse struct {
	// List of subscription pause objects
	// @Description Array of subscription pauses
	Items []*SubscriptionPauseResponse `json:"items"`

	// Total number of pauses
	// @Description Total count of subscription pauses in the response
	Total int `json:"total"`
}

type ListSubscriptionsResponse = types.ListResponse[*SubscriptionResponse]

type ListTasksResponse struct {
	Items      []*TaskResponse          `json:"items"`
	Pagination types.PaginationResponse `json:"pagination"`
}

type ListTaxAppliedResponse = types.ListResponse[*TaxAppliedResponse]

type ListTaxAssociationsResponse = types.ListResponse[*TaxAssociationResponse]

type ListTaxRatesResponse = types.ListResponse[*TaxRateResponse]

type ListWalletTransactionsResponse = types.ListResponse[*WalletTransactionResponse]

type LoginRequest struct {
	Email    string `json:"email" binding:"required,email" validate:"email"`
	Password string `json:"password" binding:"required" validate:"min=8"`
	Token    string `json:"token" binding:"omitempty" validate:"omitempty"`
}

type MeterResponse struct {
	ID          string            `json:"id" example:"550e8400-e29b-41d4-a716-446655440000"`
	Name        string            `json:"name" example:"API Usage Meter"`
	TenantID    string            `json:"tenant_id" example:"tenant123"`
	EventName   string            `json:"event_name" example:"api_request"`
	Aggregation meter.Aggregation `json:"aggregation"`
	Filters     []meter.Filter    `json:"filters"`
	ResetUsage  types.ResetUsage  `json:"reset_usage"`
	CreatedAt   time.Time         `json:"created_at" example:"2024-03-20T15:04:05Z"`
	UpdatedAt   time.Time         `json:"updated_at" example:"2024-03-20T15:04:05Z"`
	Status      string            `json:"status" example:"published"`
}

type OnboardingEventsRequest struct {
	CustomerID     string `json:"customer_id" validate:"omitempty" example:"cus_01HKG8QWERTY123"`
	FeatureID      string `json:"feature_id" validate:"omitempty" example:"feat_01HKG8QWERTY123"`
	SubscriptionID string `json:"subscription_id" validate:"omitempty" example:"sub_01HKG8QWERTY123"`
	Duration       int    `json:"duration" validate:"omitempty,min=1,max=600" default:"60" example:"60"`
}

type OnboardingEventsResponse struct {
	Message        string    `json:"message"`
	StartedAt      time.Time `json:"started_at"`
	Duration       int       `json:"duration"`
	Count          int       `json:"count"`
	CustomerID     string    `json:"customer_id"`
	FeatureID      string    `json:"feature_id,omitempty"`
	SubscriptionID string    `json:"subscription_id,omitempty"`
}

type OverrideLineItemRequest struct {
	// PriceID references the plan price to override
	PriceID string `json:"price_id" validate:"required"`

	// Quantity for this line item (optional)
	Quantity *decimal.Decimal `json:"quantity,omitempty"`

	BillingModel types.BillingModel `json:"billing_model,omitempty"`

	// Amount is the new price amount that overrides the original price (optional)
	Amount *decimal.Decimal `json:"amount,omitempty"`

	// TierMode determines how to calculate the price for a given quantity
	TierMode types.BillingTier `json:"tier_mode,omitempty"`

	// Tiers determines the pricing tiers for this line item
	Tiers []CreatePriceTier `json:"tiers,omitempty"`

	// TransformQuantity determines how to transform the quantity for this line item
	TransformQuantity *price.TransformQuantity `json:"transform_quantity,omitempty"`
}

type PauseSubscriptionRequest struct {
	// Mode for pausing the subscription
	// @Description Determines when the pause takes effect. "immediate" pauses right away, "scheduled" pauses at a specified time
	// @Enum immediate,scheduled
	PauseMode types.PauseMode `json:"pause_mode" validate:"required"`

	// Start date for the subscription pause
	// @Description ISO 8601 timestamp when the pause should begin. Required when pause_mode is "scheduled"
	// @Example "2024-01-15T00:00:00Z"
	PauseStart *time.Time `json:"pause_start,omitempty" validate:"omitempty"`

	// End date for the subscription pause
	// @Description ISO 8601 timestamp when the pause should end. Cannot be used together with pause_days. Must be after pause_start
	// @Example "2024-02-15T00:00:00Z"
	PauseEnd *time.Time `json:"pause_end,omitempty" validate:"omitempty,gtfield=PauseStart"`

	// Duration of the pause in days
	// @Description Number of days to pause the subscription. Cannot be used together with pause_end. Must be greater than 0
	// @Example 30
	PauseDays *int `json:"pause_days,omitempty" validate:"omitempty,gt=0"`

	// Reason for pausing the subscription
	// @Description Optional reason for the pause. Maximum 255 characters
	// @Example "Customer requested temporary suspension"
	Reason string `json:"reason,omitempty" validate:"omitempty,max=255"`

	// Whether to perform a dry run
	// @Description If true, validates the request and shows impact without actually pausing the subscription
	// @Example false
	DryRun bool `json:"dry_run,omitempty"`

	// Additional metadata as key-value pairs
	// @Description Optional metadata for storing additional information about the pause
	// @Example {"requested_by": "customer", "channel": "support_ticket"}
	Metadata map[string]string `json:"metadata,omitempty"`
}

type PauseSubscriptionResponse struct {
	// The subscription that was paused
	// @Description Updated subscription object after the pause operation
	Subscription *SubscriptionResponse `json:"subscription,omitempty"`

	// Details of the pause operation
	// @Description Information about the subscription pause that was created
	Pause *SubscriptionPauseResponse `json:"pause,omitempty"`

	// Impact on billing and charges
	// @Description Details about how this pause affects billing, prorations, and upcoming charges
	BillingImpact *types.BillingImpactDetails `json:"billing_impact"`

	// Whether this was a dry run
	// @Description Indicates if this was a simulation (true) or actual pause (false)
	DryRun bool `json:"dry_run"`
}

type PaymentAttemptResponse struct {
	ID            string         `json:"id"`
	PaymentID     string         `json:"payment_id"`
	AttemptNumber int            `json:"attempt_number"`
	ErrorMessage  *string        `json:"error_message,omitempty"`
	Metadata      types.Metadata `json:"metadata,omitempty"`
	TenantID      string         `json:"tenant_id"`
	CreatedAt     time.Time      `json:"created_at"`
	UpdatedAt     time.Time      `json:"updated_at"`
	CreatedBy     string         `json:"created_by"`
	UpdatedBy     string         `json:"updated_by"`
}

type PaymentIntentResponse struct {
	ID            string          `json:"id"`
	Status        string          `json:"status"`
	Amount        decimal.Decimal `json:"amount"`
	Currency      string          `json:"currency"`
	CustomerID    string          `json:"customer_id"`
	PaymentMethod string          `json:"payment_method"`
	CreatedAt     int64           `json:"created_at"`
}

type PaymentLinkResponse struct {
	ID              string          `json:"id"`
	PaymentURL      string          `json:"payment_url"`
	PaymentIntentID string          `json:"payment_intent_id,omitempty"`
	Amount          decimal.Decimal `json:"amount"`
	Currency        string          `json:"currency"`
	Status          string          `json:"status"`
	CreatedAt       int64           `json:"created_at"`
	PaymentID       string          `json:"payment_id,omitempty"`
	Gateway         string          `json:"gateway"`
	ExpiresAt       *int64          `json:"expires_at,omitempty"`
}

type PaymentMethodResponse struct {
	ID       string                 `json:"id"`
	Type     string                 `json:"type"`
	Customer string                 `json:"customer"`
	Created  int64                  `json:"created"`
	Card     *CardDetails           `json:"card,omitempty"`
	Metadata map[string]interface{} `json:"metadata"`
}

type PaymentParameters struct {
	// CollectionMethod defines how the payment should be collected (charge_automatically or send_invoice)
	CollectionMethod *types.CollectionMethod `json:"collection_method,omitempty"`

	// PaymentBehavior defines the behavior when payment fails (default_active, error_if_incomplete, etc.)
	PaymentBehavior *types.PaymentBehavior `json:"payment_behavior,omitempty"`

	// PaymentMethodID is the optional ID of the payment method to use for automatic charges
	PaymentMethodID *string `json:"payment_method_id,omitempty"`
}

type PaymentResponse struct {
	ID                     string                       `json:"id"`
	IdempotencyKey         string                       `json:"idempotency_key"`
	DestinationType        types.PaymentDestinationType `json:"destination_type"`
	DestinationID          string                       `json:"destination_id"`
	PaymentMethodType      types.PaymentMethodType      `json:"payment_method_type"`
	PaymentMethodID        string                       `json:"payment_method_id"`
	Amount                 decimal.Decimal              `json:"amount"`
	Currency               string                       `json:"currency"`
	PaymentStatus          types.PaymentStatus          `json:"payment_status"`
	TrackAttempts          bool                         `json:"track_attempts"`
	PaymentGateway         *string                      `json:"payment_gateway,omitempty"`
	GatewayPaymentID       *string                      `json:"gateway_payment_id,omitempty"`
	GatewayTrackingID      *string                      `json:"gateway_tracking_id,omitempty"`
	GatewayMetadata        types.Metadata               `json:"gateway_metadata,omitempty"`
	PaymentURL             *string                      `json:"payment_url,omitempty"`
	Metadata               types.Metadata               `json:"metadata,omitempty"`
	SucceededAt            *time.Time                   `json:"succeeded_at,omitempty"`
	FailedAt               *time.Time                   `json:"failed_at,omitempty"`
	RefundedAt             *time.Time                   `json:"refunded_at,omitempty"`
	ErrorMessage           *string                      `json:"error_message,omitempty"`
	Attempts               []*PaymentAttemptResponse    `json:"attempts,omitempty"`
	InvoiceNumber          *string                      `json:"invoice_number,omitempty"`
	TenantID               string                       `json:"tenant_id"`
	SaveCardAndMakeDefault bool                         `json:"save_card_and_make_default"`
	CreatedAt              time.Time                    `json:"created_at"`
	UpdatedAt              time.Time                    `json:"updated_at"`
	CreatedBy              string                       `json:"created_by"`
	UpdatedBy              string                       `json:"updated_by"`
}

type PaymentStatusRequest struct {
	SessionID string `json:"session_id" binding:"required"`
	PaymentID string `json:"payment_id,omitempty"`
}

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

type PlanResponse struct {
	*plan.Plan
	// TODO: Add inline addons
	Prices       []*PriceResponse       `json:"prices,omitempty"`
	Entitlements []*EntitlementResponse `json:"entitlements,omitempty"`
	CreditGrants []*CreditGrantResponse `json:"credit_grants,omitempty"`
}

type PlanSummary struct {
	// id of the plan
	ID string `json:"id"`

	// name of the plan
	Name string `json:"name"`

	// lookup_key of the plan
	LookupKey string `json:"lookup_key,omitempty"`

	// description of the plan
	Description string `json:"description,omitempty"`
}

type PriceResponse struct {
	*price.Price
	Meter       *MeterResponse     `json:"meter,omitempty"`
	PricingUnit *PriceUnitResponse `json:"pricing_unit,omitempty"`

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

type PriceUnitConfig struct {
	Amount         string            `json:"amount,omitempty"`
	PriceUnit      string            `json:"price_unit" validate:"required,len=3"`
	PriceUnitTiers []CreatePriceTier `json:"price_unit_tiers,omitempty"`
}

type PriceUnitResponse struct {
	*domainPriceUnit.PriceUnit
}

type ProcessScheduledCreditGrantApplicationsResponse struct {
	SuccessApplicationsCount int `json:"success_applications_count"`
	FailedApplicationsCount  int `json:"failed_applications_count"`
	TotalApplicationsCount   int `json:"total_applications_count"`
}

type ProrationDetail struct {
	LineItemID     string          `json:"line_item_id"`
	PriceID        string          `json:"price_id"`
	PlanName       string          `json:"plan_name,omitempty"`
	OriginalAmount decimal.Decimal `json:"original_amount"`
	CreditAmount   decimal.Decimal `json:"credit_amount"`
	ChargeAmount   decimal.Decimal `json:"charge_amount"`
	ProrationDays  int             `json:"proration_days"`
	Description    string          `json:"description,omitempty"`
}

type ProrationDetails struct {
	// credit_amount is the credit amount from the old subscription
	CreditAmount decimal.Decimal `json:"credit_amount"`

	// credit_description describes what the credit is for
	CreditDescription string `json:"credit_description"`

	// charge_amount is the charge amount for the new subscription
	ChargeAmount decimal.Decimal `json:"charge_amount"`

	// charge_description describes what the charge is for
	ChargeDescription string `json:"charge_description"`

	// net_amount is the net amount (charge - credit)
	NetAmount decimal.Decimal `json:"net_amount"`

	// proration_date is the date used for proration calculations
	ProrationDate time.Time `json:"proration_date"`

	// current_period_start is the start of the current billing period
	CurrentPeriodStart time.Time `json:"current_period_start"`

	// current_period_end is the end of the current billing period
	CurrentPeriodEnd time.Time `json:"current_period_end"`

	// days_used is the number of days used in the current period
	DaysUsed int `json:"days_used"`

	// days_remaining is the number of days remaining in the current period
	DaysRemaining int `json:"days_remaining"`

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

type ProrationLineItem struct {
	// description is the human-readable description
	Description string `json:"description"`

	// amount is the monetary amount (positive for charge, negative for credit)
	Amount decimal.Decimal `json:"amount"`

	// start_date is the period start this item covers
	StartDate time.Time `json:"start_date"`

	// end_date is the period end this item covers
	EndDate time.Time `json:"end_date"`

	// quantity is the quantity
	Quantity decimal.Decimal `json:"quantity"`

	// price_id is the associated price ID
	PriceID string `json:"price_id"`

	// is_credit indicates if this is a credit (true) or charge (false)
	IsCredit bool `json:"is_credit"`
}

type ProrationLineItemResult struct {
	// credit_items are the credit line items
	CreditItems []ProrationLineItem `json:"credit_items"`

	// charge_items are the charge line items
	ChargeItems []ProrationLineItem `json:"charge_items"`

	// net_amount is the net amount for this line item
	NetAmount decimal.Decimal `json:"net_amount"`

	// proration_date is when the proration takes effect
	ProrationDate time.Time `json:"proration_date"`

	// line_item_id is the subscription line item ID
	LineItemID string `json:"line_item_id"`
}

type ProrationResult struct {
	// total_proration_amount is the net amount (credits - charges)
	TotalProrationAmount decimal.Decimal `json:"total_proration_amount"`

	// line_item_results contains per-line-item proration details
	LineItemResults map[string]*ProrationLineItemResult `json:"line_item_results"`

	// currency is the currency code
	Currency string `json:"currency"`
}

type ROIResponse struct {
	// Cost and Revenue
	Cost    decimal.Decimal `json:"cost"`
	Revenue decimal.Decimal `json:"revenue"`

	// Net Revenue (Revenue - Cost)
	NetRevenue decimal.Decimal `json:"net_revenue"`

	// Markup (Revenue - Cost / Cost)
	Markup           decimal.Decimal `json:"markup"`
	MarkupPercentage decimal.Decimal `json:"markup_percentage"`

	// Net Margin (ROI)
	NetMargin           decimal.Decimal `json:"net_margin"`
	NetMarginPercentage decimal.Decimal `json:"net_margin_percentage"`

	// Cost breakdown by meter
	CostBreakdown []CostBreakdownItem `json:"cost_breakdown"`
}

type RemoveAddonRequest struct {
	SubscriptionID string `json:"subscription_id" validate:"required"`
	AddonID        string `json:"addon_id" validate:"required"`
	Reason         string `json:"reason"`
}

type ResumeSubscriptionRequest struct {
	// Mode for resuming the subscription
	// @Description Determines how the subscription should be resumed
	// @Enum immediate,scheduled
	ResumeMode types.ResumeMode `json:"resume_mode" validate:"required"`

	// Whether to perform a dry run
	// @Description If true, validates the request and shows impact without actually resuming the subscription
	// @Example false
	DryRun bool `json:"dry_run,omitempty"`

	// Additional metadata as key-value pairs
	// @Description Optional metadata for storing additional information about the resume operation
	// @Example {"resumed_by": "admin", "reason": "issue_resolved"}
	Metadata map[string]string `json:"metadata,omitempty"`
}

type ResumeSubscriptionResponse struct {
	// The subscription that was resumed
	// @Description Updated subscription object after the resume operation (only included if not a dry run)
	Subscription *SubscriptionResponse `json:"subscription,omitempty"`

	// Details of the pause that was ended
	// @Description Information about the subscription pause that was terminated
	Pause *SubscriptionPauseResponse `json:"pause,omitempty"`

	// Impact on billing and charges
	// @Description Details about how resuming affects billing, prorations, and upcoming charges
	BillingImpact *types.BillingImpactDetails `json:"billing_impact"`

	// Whether this was a dry run
	// @Description Indicates if this was a simulation (true) or actual resume (false)
	DryRun bool `json:"dry_run"`
}

type SecretResponse struct {
	ID          string               `json:"id"`
	Name        string               `json:"name"`
	Type        types.SecretType     `json:"type"`
	Provider    types.SecretProvider `json:"provider"`
	DisplayID   string               `json:"display_id"`
	Permissions []string             `json:"permissions"`
	ExpiresAt   *time.Time           `json:"expires_at,omitempty"`
	LastUsedAt  *time.Time           `json:"last_used_at,omitempty"`
	Status      types.Status         `json:"status"`
	CreatedAt   time.Time            `json:"created_at"`
	UpdatedAt   time.Time            `json:"updated_at"`
}

type SetDefaultPaymentMethodRequest struct {
	CustomerID      string `json:"customer_id" binding:"required"`
	PaymentMethodID string `json:"payment_method_id" binding:"required"`
}

type SettingResponse struct {
	ID            string                 `json:"id"`
	Key           string                 `json:"key"`
	Value         map[string]interface{} `json:"value"`
	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,omitempty"`
	UpdatedBy     string                 `json:"updated_by,omitempty"`
}

type SignUpRequest struct {
	Email      string `json:"email" binding:"required,email" validate:"email"`
	Password   string `json:"password" binding:"omitempty,min=8" validate:"omitempty,min=8"`
	TenantName string `json:"tenant_name" binding:"omitempty" validate:"omitempty"`
	Token      string `json:"token" binding:"omitempty" validate:"omitempty"`
}

type SourceUsageItem struct {
	// source is the name of the event source
	Source string `json:"source"`

	// cost is the cost attributed to this source for the line item
	Cost string `json:"cost"`

	// usage is the total usage amount from this source (optional, for additional context)
	Usage *string `json:"usage,omitempty"`

	// percentage is the percentage of total line item cost from this source (optional)
	Percentage *string `json:"percentage,omitempty"`

	// event_count is the number of events from this source (optional)
	EventCount *int `json:"event_count,omitempty"`
}

type StripePaymentLinkResponse struct {
	ID              string          `json:"id"`
	PaymentURL      string          `json:"payment_url"`
	PaymentIntentID string          `json:"payment_intent_id"`
	Amount          decimal.Decimal `json:"amount"`
	Currency        string          `json:"currency"`
	Status          string          `json:"status"`
	CreatedAt       int64           `json:"created_at"`
	PaymentID       string          `json:"payment_id,omitempty"`
}

type SubscriptionChangeExecuteResponse struct {
	// old_subscription contains the archived subscription details
	OldSubscription SubscriptionSummary `json:"old_subscription"`

	// new_subscription contains the new subscription details
	NewSubscription SubscriptionSummary `json:"new_subscription"`

	// change_type indicates whether this was an upgrade, downgrade, or lateral change
	ChangeType types.SubscriptionChangeType `json:"change_type"`

	// invoice contains the immediate invoice generated for the change (if any)
	Invoice *InvoiceResponse `json:"invoice,omitempty"`

	// proration_applied contains details of the proration that was applied
	ProrationApplied *ProrationDetails `json:"proration_applied,omitempty"`

	// credit_grants contains any credit grants created for proration credits
	CreditGrants []*CreditGrantResponse `json:"credit_grants,omitempty"`

	// effective_date is when the change took effect
	EffectiveDate time.Time `json:"effective_date"`

	// metadata from the request
	Metadata map[string]string `json:"metadata,omitempty"`
}

type SubscriptionChangePreviewResponse struct {
	// subscription_id is the ID of the subscription being changed
	SubscriptionID string `json:"subscription_id"`

	// current_plan contains information about the current plan
	CurrentPlan PlanSummary `json:"current_plan"`

	// target_plan contains information about the target plan
	TargetPlan PlanSummary `json:"target_plan"`

	// change_type indicates whether this is an upgrade, downgrade, or lateral change
	ChangeType types.SubscriptionChangeType `json:"change_type"`

	// proration_details contains the calculated proration amounts
	ProrationDetails *ProrationDetails `json:"proration_details,omitempty"`

	// next_invoice_preview shows how the next regular invoice would be affected
	NextInvoicePreview *InvoicePreview `json:"next_invoice_preview,omitempty"`

	// effective_date is when the change would take effect
	EffectiveDate time.Time `json:"effective_date"`

	// new_billing_cycle shows the new billing cycle details
	NewBillingCycle BillingCycleInfo `json:"new_billing_cycle"`

	// warnings contains any warnings about the change
	Warnings []string `json:"warnings,omitempty"`

	// metadata from the request
	Metadata map[string]string `json:"metadata,omitempty"`
}

type SubscriptionChangeRequest struct {
	// target_plan_id is the ID of the new plan to change to (required)
	TargetPlanID string `json:"target_plan_id" validate:"required" binding:"required"`

	// proration_behavior controls how proration is handled for the change
	// Options: create_prorations, none
	ProrationBehavior types.ProrationBehavior `json:"proration_behavior" validate:"required" binding:"required"`

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

	// billing_cadence is the billing cadence for the new subscription
	BillingCadence types.BillingCadence `json:"billing_cadence" validate:"required" binding:"required"`

	// billing_period is the billing period for the new subscription
	BillingPeriod types.BillingPeriod `json:"billing_period" validate:"required" binding:"required"`

	// billing_period_count is the billing period count for the new subscription
	BillingPeriodCount int `json:"billing_period_count" validate:"required" binding:"required"`

	// billing_cycle is the billing cycle for the new subscription
	BillingCycle types.BillingCycle `json:"billing_cycle" validate:"required" binding:"required"`
}

type SubscriptionLineItemRequest struct {
	PriceID     string            `json:"price_id" validate:"required"`
	Quantity    decimal.Decimal   `json:"quantity" validate:"required"`
	DisplayName string            `json:"display_name,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type SubscriptionLineItemResponse struct {
	*subscription.SubscriptionLineItem
}

type SubscriptionPauseResponse struct {
	*subscription.SubscriptionPause
}

type SubscriptionResponse struct {
	*subscription.Subscription
	Plan     *PlanResponse     `json:"plan"`
	Customer *CustomerResponse `json:"customer"`
	// Schedule is included when the subscription has a schedule
	Schedule *SubscriptionScheduleResponse `json:"schedule,omitempty"`
	// CouponAssociations are the coupon associations for this subscription
	CouponAssociations []*CouponAssociationResponse `json:"coupon_associations,omitempty"`

	// Latest invoice information for incomplete subscriptions
	LatestInvoice *InvoiceResponse `json:"latest_invoice,omitempty"`
}

type SubscriptionSchedulePhaseInput struct {
	BillingCycle     types.BillingCycle            `json:"billing_cycle"`
	StartDate        time.Time                     `json:"start_date" validate:"required"`
	EndDate          *time.Time                    `json:"end_date,omitempty"`
	LineItems        []SubscriptionLineItemRequest `json:"line_items"`
	CreditGrants     []CreateCreditGrantRequest    `json:"credit_grants"`
	CommitmentAmount decimal.Decimal               `json:"commitment_amount"`
	OverageFactor    decimal.Decimal               `json:"overage_factor"`
	Metadata         map[string]string             `json:"metadata,omitempty"`
}

type SubscriptionSchedulePhaseResponse struct {
	ID               string                         `json:"id"`
	ScheduleID       string                         `json:"schedule_id"`
	PhaseIndex       int                            `json:"phase_index"`
	StartDate        time.Time                      `json:"start_date"`
	EndDate          *time.Time                     `json:"end_date,omitempty"`
	CommitmentAmount *decimal.Decimal               `json:"commitment_amount"`
	OverageFactor    *decimal.Decimal               `json:"overage_factor"`
	CreditGrants     []CreditGrantResponse          `json:"credit_grants,omitempty"`
	LineItems        []SubscriptionLineItemResponse `json:"line_items,omitempty"`
	CreatedAt        time.Time                      `json:"created_at"`
	UpdatedAt        time.Time                      `json:"updated_at"`
}

type SubscriptionScheduleResponse struct {
	ID                string                               `json:"id"`
	SubscriptionID    string                               `json:"subscription_id"`
	ScheduleStatus    types.SubscriptionScheduleStatus     `json:"status"`
	CurrentPhaseIndex int                                  `json:"current_phase_index"`
	EndBehavior       types.ScheduleEndBehavior            `json:"end_behavior"`
	StartDate         time.Time                            `json:"start_date"`
	Phases            []*SubscriptionSchedulePhaseResponse `json:"phases,omitempty"`
	CreatedAt         time.Time                            `json:"created_at"`
	UpdatedAt         time.Time                            `json:"updated_at"`
}

type SubscriptionSummary struct {
	// id of the subscription
	ID string `json:"id"`

	// status of the subscription
	Status types.SubscriptionStatus `json:"status"`

	// plan_id of the subscription
	PlanID string `json:"plan_id"`

	// current_period_start of the subscription
	CurrentPeriodStart time.Time `json:"current_period_start"`

	// current_period_end of the subscription
	CurrentPeriodEnd time.Time `json:"current_period_end"`

	// billing_anchor of the subscription
	BillingAnchor time.Time `json:"billing_anchor"`

	// created_at timestamp
	CreatedAt time.Time `json:"created_at"`

	// archived_at timestamp (for old subscriptions)
	ArchivedAt *time.Time `json:"archived_at,omitempty"`
}

type SubscriptionUpdatePeriodResponse struct {
	TotalSuccess int                                     `json:"total_success"`
	TotalFailed  int                                     `json:"total_failed"`
	Items        []*SubscriptionUpdatePeriodResponseItem `json:"items"`
	StartAt      time.Time                               `json:"start_at"`
}

type SubscriptionUpdatePeriodResponseItem struct {
	SubscriptionID string    `json:"subscription_id"`
	PeriodStart    time.Time `json:"period_start"`
	PeriodEnd      time.Time `json:"period_end"`
	Success        bool      `json:"success"`
	Error          string    `json:"error"`
}

type SubscriptionUsageByMetersResponse struct {
	Amount           float64            `json:"amount"`
	Currency         string             `json:"currency"`
	DisplayAmount    string             `json:"display_amount"`
	Quantity         float64            `json:"quantity"`
	FilterValues     price.JSONBFilters `json:"filter_values"`
	MeterID          string             `json:"meter_id"`
	MeterDisplayName string             `json:"meter_display_name"`
	Price            *price.Price       `json:"price"`
	IsOverage        bool               `json:"is_overage"`               // Whether this charge is at overage rate
	OverageFactor    float64            `json:"overage_factor,omitempty"` // Factor applied to this charge if in overage
}

type SuccessResponse struct {
	Message string `json:"message"`
}

type SyncPlanPricesResponse struct {
	Message                string `json:"message"`
	PlanID                 string `json:"plan_id"`
	PlanName               string `json:"plan_name"`
	SynchronizationSummary struct {
		SubscriptionsProcessed int `json:"subscriptions_processed"`
		PricesAdded            int `json:"prices_added"`
		PricesRemoved          int `json:"prices_removed"`
		PricesSkipped          int `json:"prices_skipped"`
	} `json:"synchronization_summary"`
}

type TaskResponse struct {
	ID                string                 `json:"id"`
	TaskType          types.TaskType         `json:"task_type"`
	EntityType        types.EntityType       `json:"entity_type"`
	FileURL           string                 `json:"file_url"`
	FileName          *string                `json:"file_name,omitempty"`
	FileType          types.FileType         `json:"file_type"`
	TaskStatus        types.TaskStatus       `json:"task_status"`
	TotalRecords      *int                   `json:"total_records,omitempty"`
	ProcessedRecords  int                    `json:"processed_records"`
	SuccessfulRecords int                    `json:"successful_records"`
	FailedRecords     int                    `json:"failed_records"`
	ErrorSummary      *string                `json:"error_summary,omitempty"`
	Metadata          map[string]interface{} `json:"metadata,omitempty"`
	StartedAt         *time.Time             `json:"started_at,omitempty"`
	CompletedAt       *time.Time             `json:"completed_at,omitempty"`
	FailedAt          *time.Time             `json:"failed_at,omitempty"`
	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,omitempty"`
	UpdatedBy         string                 `json:"updated_by,omitempty"`
}