api/v3/client/models_customers.go

// Code generated by @openmeter/typespec-go. DO NOT EDIT.

package openmeter

import (
	"encoding/json"
	"fmt"
	"time"
)

// App customer data.
type AppCustomerData struct {
	// Used if the customer has a linked Stripe app.
	Stripe *AppCustomerDataStripe `json:"stripe,omitempty"`
	// Used if the customer has a linked external invoicing app.
	ExternalInvoicing *AppCustomerDataExternalInvoicing `json:"external_invoicing,omitempty"`
}

// App customer data.
type AppCustomerDataInput struct {
	// Used if the customer has a linked Stripe app.
	Stripe *AppCustomerDataStripeInput `json:"stripe,omitempty"`
	// Used if the customer has a linked external invoicing app.
	ExternalInvoicing *AppCustomerDataExternalInvoicingInput `json:"external_invoicing,omitempty"`
}

// External invoicing customer data.
type AppCustomerDataExternalInvoicing struct {
	// Labels for this external invoicing integration on the customer.
	Labels map[string]string `json:"labels,omitempty"`
}

// External invoicing customer data.
type AppCustomerDataExternalInvoicingInput struct {
	// Labels for this external invoicing integration on the customer.
	Labels *map[string]string `json:"labels,omitempty"`
}

// Stripe customer data.
type AppCustomerDataStripe struct {
	// The Stripe customer ID used.
	CustomerID *string `json:"customer_id,omitempty"`
	// The Stripe default payment method ID.
	DefaultPaymentMethodID *string `json:"default_payment_method_id,omitempty"`
	// Labels for this Stripe integration on the customer.
	Labels map[string]string `json:"labels,omitempty"`
}

// Stripe customer data.
type AppCustomerDataStripeInput struct {
	// The Stripe customer ID used.
	CustomerID *string `json:"customer_id,omitempty"`
	// The Stripe default payment method ID.
	DefaultPaymentMethodID *string `json:"default_payment_method_id,omitempty"`
	// Labels for this Stripe integration on the customer.
	Labels *map[string]string `json:"labels,omitempty"`
}

// Custom text displayed at various stages of the checkout flow.
type AppStripeCheckoutSessionCustomTextParams struct {
	// Text displayed after the payment confirmation button.
	AfterSubmit *AppStripeCheckoutSessionCustomTextParamsAfterSubmit `json:"after_submit,omitempty"`
	// Text displayed alongside shipping address collection.
	ShippingAddress *AppStripeCheckoutSessionCustomTextParamsShippingAddress `json:"shipping_address,omitempty"`
	// Text displayed alongside the payment confirmation button.
	Submit *AppStripeCheckoutSessionCustomTextParamsSubmit `json:"submit,omitempty"`
	// Text replacing the default terms of service agreement text.
	TermsOfServiceAcceptance *AppStripeCheckoutSessionCustomTextParamsTermsOfServiceAcceptance `json:"terms_of_service_acceptance,omitempty"`
}

type AppStripeCheckoutSessionCustomTextParamsAfterSubmit struct {
	// The custom message text (max 1200 characters).
	Message *string `json:"message,omitempty"`
}

type AppStripeCheckoutSessionCustomTextParamsShippingAddress struct {
	// The custom message text (max 1200 characters).
	Message *string `json:"message,omitempty"`
}

type AppStripeCheckoutSessionCustomTextParamsSubmit struct {
	// The custom message text (max 1200 characters).
	Message *string `json:"message,omitempty"`
}

type AppStripeCheckoutSessionCustomTextParamsTermsOfServiceAcceptance struct {
	// The custom message text (max 1200 characters).
	Message *string `json:"message,omitempty"`
}

// Stripe Checkout Session mode.
//
// Determines the primary purpose of the checkout session.
type AppStripeCheckoutSessionMode string

const (
	AppStripeCheckoutSessionModeSetup AppStripeCheckoutSessionMode = "setup"
)

func (value AppStripeCheckoutSessionMode) Valid() bool {
	switch value {
	case AppStripeCheckoutSessionModeSetup:
		return true
	default:
		return false
	}
}

// Checkout Session UI mode.
type AppStripeCheckoutSessionUiMode string

const (
	AppStripeCheckoutSessionUiModeEmbedded AppStripeCheckoutSessionUiMode = "embedded"
	AppStripeCheckoutSessionUiModeHosted   AppStripeCheckoutSessionUiMode = "hosted"
)

func (value AppStripeCheckoutSessionUiMode) Valid() bool {
	switch value {
	case AppStripeCheckoutSessionUiModeEmbedded, AppStripeCheckoutSessionUiModeHosted:
		return true
	default:
		return false
	}
}

// Controls whether Checkout collects the customer's billing address.
type AppStripeCreateCheckoutSessionBillingAddressCollection string

const (
	AppStripeCreateCheckoutSessionBillingAddressCollectionAuto     AppStripeCreateCheckoutSessionBillingAddressCollection = "auto"
	AppStripeCreateCheckoutSessionBillingAddressCollectionRequired AppStripeCreateCheckoutSessionBillingAddressCollection = "required"
)

func (value AppStripeCreateCheckoutSessionBillingAddressCollection) Valid() bool {
	switch value {
	case AppStripeCreateCheckoutSessionBillingAddressCollectionAuto, AppStripeCreateCheckoutSessionBillingAddressCollectionRequired:
		return true
	default:
		return false
	}
}

// Checkout Session consent collection configuration.
type AppStripeCreateCheckoutSessionConsentCollection struct {
	// Controls the visibility of payment method reuse agreement.
	PaymentMethodReuseAgreement *AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreement `json:"payment_method_reuse_agreement,omitempty"`
	// Enables collection of promotional communication consent.
	//
	// Only available to US merchants. When set to "auto", Checkout determines whether
	// to show the option based on the customer's locale.
	Promotions *AppStripeCreateCheckoutSessionConsentCollectionPromotions `json:"promotions,omitempty"`
	// Requires customers to accept terms of service before payment.
	//
	// Requires a valid terms of service URL in your Stripe Dashboard settings.
	TermsOfService *AppStripeCreateCheckoutSessionConsentCollectionTermsOfService `json:"terms_of_service,omitempty"`
}

// Payment method reuse agreement configuration.
type AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreement struct {
	// Position and visibility of the payment method reuse agreement.
	Position *AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition `json:"position,omitempty"`
}

// Position of payment method reuse agreement in the UI.
type AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition string

const (
	AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPositionAuto   AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition = "auto"
	AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPositionHidden AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition = "hidden"
)

func (value AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition) Valid() bool {
	switch value {
	case AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPositionAuto, AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPositionHidden:
		return true
	default:
		return false
	}
}

// Promotional communication consent collection setting.
type AppStripeCreateCheckoutSessionConsentCollectionPromotions string

const (
	AppStripeCreateCheckoutSessionConsentCollectionPromotionsAuto AppStripeCreateCheckoutSessionConsentCollectionPromotions = "auto"
	AppStripeCreateCheckoutSessionConsentCollectionPromotionsNone AppStripeCreateCheckoutSessionConsentCollectionPromotions = "none"
)

func (value AppStripeCreateCheckoutSessionConsentCollectionPromotions) Valid() bool {
	switch value {
	case AppStripeCreateCheckoutSessionConsentCollectionPromotionsAuto, AppStripeCreateCheckoutSessionConsentCollectionPromotionsNone:
		return true
	default:
		return false
	}
}

// Terms of service acceptance requirement.
type AppStripeCreateCheckoutSessionConsentCollectionTermsOfService string

const (
	AppStripeCreateCheckoutSessionConsentCollectionTermsOfServiceNone     AppStripeCreateCheckoutSessionConsentCollectionTermsOfService = "none"
	AppStripeCreateCheckoutSessionConsentCollectionTermsOfServiceRequired AppStripeCreateCheckoutSessionConsentCollectionTermsOfService = "required"
)

func (value AppStripeCreateCheckoutSessionConsentCollectionTermsOfService) Valid() bool {
	switch value {
	case AppStripeCreateCheckoutSessionConsentCollectionTermsOfServiceNone, AppStripeCreateCheckoutSessionConsentCollectionTermsOfServiceRequired:
		return true
	default:
		return false
	}
}

// Controls which customer fields can be updated by the checkout session.
type AppStripeCreateCheckoutSessionCustomerUpdate struct {
	// Whether to save the billing address to customer.address.
	//
	// Defaults to "never".
	Address *AppStripeCreateCheckoutSessionCustomerUpdateBehavior `json:"address,omitempty"`
	// Whether to save the customer name to customer.name.
	//
	// Defaults to "never".
	Name *AppStripeCreateCheckoutSessionCustomerUpdateBehavior `json:"name,omitempty"`
	// Whether to save shipping information to customer.shipping.
	//
	// Defaults to "never".
	Shipping *AppStripeCreateCheckoutSessionCustomerUpdateBehavior `json:"shipping,omitempty"`
}

// Behavior for updating customer fields from checkout session.
type AppStripeCreateCheckoutSessionCustomerUpdateBehavior string

const (
	AppStripeCreateCheckoutSessionCustomerUpdateBehaviorAuto  AppStripeCreateCheckoutSessionCustomerUpdateBehavior = "auto"
	AppStripeCreateCheckoutSessionCustomerUpdateBehaviorNever AppStripeCreateCheckoutSessionCustomerUpdateBehavior = "never"
)

func (value AppStripeCreateCheckoutSessionCustomerUpdateBehavior) Valid() bool {
	switch value {
	case AppStripeCreateCheckoutSessionCustomerUpdateBehaviorAuto, AppStripeCreateCheckoutSessionCustomerUpdateBehaviorNever:
		return true
	default:
		return false
	}
}

// Redirect behavior for embedded checkout sessions.
type AppStripeCreateCheckoutSessionRedirectOnCompletion string

const (
	AppStripeCreateCheckoutSessionRedirectOnCompletionAlways     AppStripeCreateCheckoutSessionRedirectOnCompletion = "always"
	AppStripeCreateCheckoutSessionRedirectOnCompletionIfRequired AppStripeCreateCheckoutSessionRedirectOnCompletion = "if_required"
	AppStripeCreateCheckoutSessionRedirectOnCompletionNever      AppStripeCreateCheckoutSessionRedirectOnCompletion = "never"
)

func (value AppStripeCreateCheckoutSessionRedirectOnCompletion) Valid() bool {
	switch value {
	case AppStripeCreateCheckoutSessionRedirectOnCompletionAlways, AppStripeCreateCheckoutSessionRedirectOnCompletionIfRequired, AppStripeCreateCheckoutSessionRedirectOnCompletionNever:
		return true
	default:
		return false
	}
}

// Configuration options for creating a Stripe Checkout Session.
//
// Based on Stripe's
// [Checkout Session API parameters](https://docs.stripe.com/api/checkout/sessions/create).
type AppStripeCreateCheckoutSessionRequestOptions struct {
	// Whether to collect the customer's billing address.
	//
	// Defaults to auto, which only collects the address when necessary for tax
	// calculation.
	BillingAddressCollection *AppStripeCreateCheckoutSessionBillingAddressCollection `json:"billing_address_collection,omitempty"`
	// URL to redirect customers who cancel the checkout session.
	//
	// Not allowed when ui_mode is "embedded".
	CancelURL *string `json:"cancel_url,omitempty"`
	// Unique reference string for reconciling sessions with internal systems.
	//
	// Can be a customer ID, cart ID, or any other identifier.
	ClientReferenceID *string `json:"client_reference_id,omitempty"`
	// Controls which customer fields can be updated by the checkout session.
	CustomerUpdate *AppStripeCreateCheckoutSessionCustomerUpdate `json:"customer_update,omitempty"`
	// Configuration for collecting customer consent during checkout.
	ConsentCollection *AppStripeCreateCheckoutSessionConsentCollection `json:"consent_collection,omitempty"`
	// Three-letter ISO 4217 currency code in uppercase.
	//
	// Required for payment mode sessions. Optional for setup mode sessions.
	Currency *string `json:"currency,omitempty"`
	// Custom text to display during checkout at various stages.
	CustomText *AppStripeCheckoutSessionCustomTextParams `json:"custom_text,omitempty"`
	// Unix timestamp when the checkout session expires.
	//
	// Can be 30 minutes to 24 hours from creation. Defaults to 24 hours.
	ExpiresAt *int64 `json:"expires_at,omitempty"`
	// IETF language tag for the checkout UI locale.
	//
	// If blank or "auto", uses the browser's locale. Example: "en", "fr", "de".
	Locale *string `json:"locale,omitempty"`
	// Set of key-value pairs to attach to the checkout session.
	//
	// Useful for storing additional structured information.
	Metadata *map[string]string `json:"metadata,omitempty"`
	// Return URL for embedded checkout sessions after payment authentication.
	//
	// Required if ui_mode is "embedded" and redirect-based payment methods are
	// enabled.
	ReturnURL *string `json:"return_url,omitempty"`
	// Success URL to redirect customers after completing payment or setup.
	//
	// Not allowed when ui_mode is "embedded". See:
	// https://docs.stripe.com/payments/checkout/custom-success-page
	SuccessURL *string `json:"success_url,omitempty"`
	// The UI mode for the checkout session.
	//
	// "hosted" displays a Stripe-hosted page. "embedded" integrates directly into your
	// app. Defaults to "hosted".
	UiMode *AppStripeCheckoutSessionUiMode `json:"ui_mode,omitempty"`
	// List of payment method types to enable (e.g., "card", "us_bank_account").
	//
	// If not specified, Stripe enables all relevant payment methods.
	PaymentMethodTypes *[]string `json:"payment_method_types,omitempty"`
	// Redirect behavior for embedded checkout sessions.
	//
	// Controls when to redirect users after completion. See:
	// https://docs.stripe.com/payments/checkout/custom-success-page?payment-ui=embedded-form
	RedirectOnCompletion *AppStripeCreateCheckoutSessionRedirectOnCompletion `json:"redirect_on_completion,omitempty"`
	// Configuration for collecting tax IDs during checkout.
	TaxIDCollection *AppStripeCreateCheckoutSessionTaxIDCollection `json:"tax_id_collection,omitempty"`
}

// Result of creating a Stripe Checkout Session.
//
// Contains all the information needed to redirect customers to the checkout or
// initialize an embedded checkout flow.
type AppStripeCreateCheckoutSessionResult struct {
	// The customer ID in the billing system.
	CustomerID string `json:"customer_id"`
	// The Stripe customer ID.
	StripeCustomerID string `json:"stripe_customer_id"`
	// The Stripe checkout session ID.
	SessionID string `json:"session_id"`
	// The setup intent ID created for collecting the payment method.
	SetupIntentID string `json:"setup_intent_id"`
	// Client secret for initializing Stripe.js on the client side.
	//
	// Required for embedded checkout sessions. See:
	// https://docs.stripe.com/payments/checkout/custom-success-page
	ClientSecret *string `json:"client_secret,omitempty"`
	// The client reference ID provided in the request.
	//
	// Useful for reconciling the session with your internal systems.
	ClientReferenceID *string `json:"client_reference_id,omitempty"`
	// Customer's email address if provided to Stripe.
	CustomerEmail *string `json:"customer_email,omitempty"`
	// Currency code for the checkout session.
	Currency *string `json:"currency,omitempty"`
	// Timestamp when the checkout session was created.
	CreatedAt time.Time `json:"created_at"`
	// Timestamp when the checkout session will expire.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	// Metadata attached to the checkout session.
	Metadata map[string]string `json:"metadata,omitempty"`
	// The status of the checkout session.
	//
	// See:
	// https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-status
	Status *string `json:"status,omitempty"`
	// URL to redirect customers to the checkout page (for hosted mode).
	URL *string `json:"url,omitempty"`
	// Mode of the checkout session.
	//
	// Currently only "setup" mode is supported for collecting payment methods.
	Mode AppStripeCheckoutSessionMode `json:"mode"`
	// The cancel URL where customers are redirected if they cancel.
	CancelURL *string `json:"cancel_url,omitempty"`
	// The success URL where customers are redirected after completion.
	SuccessURL *string `json:"success_url,omitempty"`
	// The return URL for embedded sessions after authentication.
	ReturnURL *string `json:"return_url,omitempty"`
}

// Tax ID collection configuration for checkout sessions.
type AppStripeCreateCheckoutSessionTaxIDCollection struct {
	// Enable tax ID collection during checkout.
	//
	// Defaults to false.
	Enabled *bool `json:"enabled,omitempty"`
	// Whether tax ID collection is required.
	//
	// Defaults to "never".
	Required *AppStripeCreateCheckoutSessionTaxIDCollectionRequired `json:"required,omitempty"`
}

// Tax ID collection requirement level.
type AppStripeCreateCheckoutSessionTaxIDCollectionRequired string

const (
	AppStripeCreateCheckoutSessionTaxIDCollectionRequiredIfSupported AppStripeCreateCheckoutSessionTaxIDCollectionRequired = "if_supported"
	AppStripeCreateCheckoutSessionTaxIDCollectionRequiredNever       AppStripeCreateCheckoutSessionTaxIDCollectionRequired = "never"
)

func (value AppStripeCreateCheckoutSessionTaxIDCollectionRequired) Valid() bool {
	switch value {
	case AppStripeCreateCheckoutSessionTaxIDCollectionRequiredIfSupported, AppStripeCreateCheckoutSessionTaxIDCollectionRequiredNever:
		return true
	default:
		return false
	}
}

// Request to create a Stripe Customer Portal Session.
type AppStripeCreateCustomerPortalSessionOptions struct {
	// The ID of an existing
	// [Stripe configuration](https://docs.stripe.com/api/customer_portal/configurations)
	// to use for this session, describing its functionality and features. If not
	// specified, the session uses the default configuration.
	ConfigurationID *string `json:"configuration_id,omitempty"`
	// The IETF
	// [language tag](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-locale)
	// of the locale customer portal is displayed in. If blank or `auto`, the
	// customer's preferred_locales or browser's locale is used.
	Locale *string `json:"locale,omitempty"`
	// The
	// [URL to redirect](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url)
	// the customer to after they have completed their requested actions.
	ReturnURL *string `json:"return_url,omitempty"`
}

// Result of creating a
// [Stripe Customer Portal Session](https://docs.stripe.com/api/customer_portal/sessions/object).
//
// Contains all the information needed to redirect the customer to the Stripe
// Customer Portal.
type AppStripeCreateCustomerPortalSessionResult struct {
	// The ID of the customer portal session.
	//
	// See:
	// https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-id
	ID string `json:"id"`
	// The ID of the stripe customer.
	StripeCustomerID string `json:"stripe_customer_id"`
	// Configuration used to customize the customer portal.
	//
	// See:
	// https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-configuration
	ConfigurationID string `json:"configuration_id"`
	// Livemode.
	//
	// See:
	// https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-livemode
	Livemode bool `json:"livemode"`
	// Created at.
	//
	// See:
	// https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-created
	CreatedAt time.Time `json:"created_at"`
	// Return URL.
	//
	// See:
	// https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-return_url
	ReturnURL string `json:"return_url"`
	// The IETF language tag of the locale customer portal is displayed in.
	//
	// See:
	// https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-locale
	Locale string `json:"locale"`
	// The URL to redirect the customer to after they have completed their requested
	// actions.
	URL string `json:"url"`
}

// Customer reference.
type BillingCustomerReference struct {
	// The ID of the customer.
	ID string `json:"id"`
}

// Customer charge.
//
// Charge is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the ChargeFrom* constructors.
// The exported Type field is decode-side metadata; MarshalJSON round-trips the original payload and ignores writes to it.
type Charge struct {
	Type string `json:"type"`
	raw  json.RawMessage
}

func (u *Charge) UnmarshalJSON(data []byte) error {
	u.raw = append([]byte(nil), data...)
	if string(data) == "null" {
		u.Type = ""
		return nil
	}

	var envelope struct {
		Value string `json:"type"`
	}
	if err := json.Unmarshal(data, &envelope); err != nil {
		return err
	}
	u.Type = envelope.Value
	return nil
}

func (u Charge) MarshalJSON() ([]byte, error) {
	if len(u.raw) == 0 {
		return []byte("null"), nil
	}
	return append([]byte(nil), u.raw...), nil
}

func (u Charge) AsChargeFlatFee() (*ChargeFlatFee, error) {
	if u.Type != "flat_fee" {
		return nil, fmt.Errorf("Charge: expected type %q, got %q", "flat_fee", u.Type)
	}
	var value ChargeFlatFee
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func ChargeFromChargeFlatFee(value ChargeFlatFee) (Charge, error) {
	value.Type = "flat_fee"
	raw, err := json.Marshal(value)
	if err != nil {
		return Charge{}, err
	}
	var result Charge
	if err := result.UnmarshalJSON(raw); err != nil {
		return Charge{}, err
	}
	return result, nil
}

func (u Charge) AsChargeUsageBased() (*ChargeUsageBased, error) {
	if u.Type != "usage_based" {
		return nil, fmt.Errorf("Charge: expected type %q, got %q", "usage_based", u.Type)
	}
	var value ChargeUsageBased
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func ChargeFromChargeUsageBased(value ChargeUsageBased) (Charge, error) {
	value.Type = "usage_based"
	raw, err := json.Marshal(value)
	if err != nil {
		return Charge{}, err
	}
	var result Charge
	if err := result.UnmarshalJSON(raw); err != nil {
		return Charge{}, err
	}
	return result, nil
}

// A flat fee charge for a customer.
type ChargeFlatFee struct {
	ID string `json:"id"`
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// An ISO-8601 timestamp representation of entity creation date.
	CreatedAt time.Time `json:"created_at"`
	// An ISO-8601 timestamp representation of entity last update date.
	UpdatedAt time.Time `json:"updated_at"`
	// An ISO-8601 timestamp representation of entity deletion date.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	// The type of the charge.
	Type ChargeType `json:"type"`
	// The customer owning the charge.
	Customer BillingCustomerReference `json:"customer"`
	// Indicates whether the charge lifecycle is controlled by OpenMeter or manually
	// overridden by the API user.
	LifecycleController LifecycleController `json:"lifecycle_controller"`
	// The subscription that originated the charge, when the charge was created from a
	// subscription item.
	Subscription *SubscriptionReference `json:"subscription,omitempty"`
	// The currency of the charge.
	Currency string `json:"currency"`
	// The lifecycle status of the charge.
	Status ChargeStatus `json:"status"`
	// The timestamp when the charge is intended to be invoiced.
	InvoiceAt time.Time `json:"invoice_at"`
	// The effective service period covered by the charge.
	ServicePeriod ClosedPeriod `json:"service_period"`
	// The full, unprorated service period of the charge.
	FullServicePeriod ClosedPeriod `json:"full_service_period"`
	// The billing period the charge belongs to.
	BillingPeriod ClosedPeriod `json:"billing_period"`
	// The earliest time when the charge should be advanced again by background
	// processing.
	AdvanceAfter *time.Time `json:"advance_after,omitempty"`
	// Unique reference ID of the charge.
	UniqueReferenceID *string `json:"unique_reference_id,omitempty"`
	// Settlement mode of the charge.
	SettlementMode SettlementMode `json:"settlement_mode"`
	// Tax configuration of the charge.
	TaxConfig *TaxConfig `json:"tax_config,omitempty"`
	// Payment term of the flat fee charge.
	PaymentTerm PricePaymentTerm `json:"payment_term"`
	// The discounts applied to the charge.
	Discounts *ChargeFlatFeeDiscounts `json:"discounts,omitempty"`
	// The feature associated with the charge, when applicable.
	FeatureKey *string `json:"feature_key,omitempty"`
	// The proration configuration of the charge.
	ProrationConfiguration RateCardProrationConfiguration `json:"proration_configuration"`
	// The amount after proration of the charge.
	AmountAfterProration CurrencyAmount `json:"amount_after_proration"`
	// The price of the charge.
	Price Price `json:"price"`
	// Current intent from the system lifecycle controller for a charge that has an
	// active manual override. The top-level charge fields remain the effective
	// customer-facing intent.
	SystemIntent *ChargeFlatFeeSystemIntent `json:"system_intent,omitempty"`
}

// Discounts applicable to flat fee charges.
//
// This is the same as `ProductCatalog.Discounts` but without the `usage` field,
// which is not applicable to flat fee charges.
type ChargeFlatFeeDiscounts struct {
	// Percentage discount applied to the price (0–100).
	Percentage *float64 `json:"percentage,omitempty"`
}

// Flat fee intent fields from the system lifecycle controller shadowed by a manual
// override.
type ChargeFlatFeeSystemIntent struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// The timestamp when the charge is intended to be invoiced.
	InvoiceAt time.Time `json:"invoice_at"`
	// The effective service period covered by the charge.
	ServicePeriod ClosedPeriod `json:"service_period"`
	// The full, unprorated service period of the charge.
	FullServicePeriod ClosedPeriod `json:"full_service_period"`
	// The billing period the charge belongs to.
	BillingPeriod ClosedPeriod `json:"billing_period"`
	// Payment term of the flat fee charge.
	PaymentTerm PricePaymentTerm `json:"payment_term"`
	// The discounts applied to the charge.
	Discounts *ChargeFlatFeeDiscounts `json:"discounts,omitempty"`
	// The proration configuration of the charge.
	ProrationConfiguration RateCardProrationConfiguration `json:"proration_configuration"`
	// The amount before proration of the system lifecycle controller flat fee intent.
	AmountBeforeProration CurrencyAmount `json:"amount_before_proration"`
	// The timestamp when the system lifecycle controller intent was deleted. The
	// effective charge can remain visible while a manual override is active.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

// Page paginated response.
type ChargePagePaginatedResponse struct {
	Data []Charge      `json:"data"`
	Meta PaginatedMeta `json:"meta"`
}

// Lifecycle status of a charge.
//
// Values:
//
// - `created`: The charge has been created but is not active yet.
// - `active`: The charge is active.
// - `final`: The charge is fully finalized and no further changes are expected.
// - `deleted`: The charge has been deleted.
type ChargeStatus string

const (
	ChargeStatusCreated ChargeStatus = "created"
	ChargeStatusActive  ChargeStatus = "active"
	ChargeStatusFinal   ChargeStatus = "final"
	ChargeStatusDeleted ChargeStatus = "deleted"
)

func (value ChargeStatus) Valid() bool {
	switch value {
	case ChargeStatusCreated, ChargeStatusActive, ChargeStatusFinal, ChargeStatusDeleted:
		return true
	default:
		return false
	}
}

// The totals of a change.
//
// RealTime is only expanded when the `real_time_usage` expand is used.
type ChargeTotals struct {
	// The amount of the charge already booked to the internal accounting system.
	Booked Totals `json:"booked"`
	// The realtime amount of the charge.
	//
	// Requires the `realtime_usage` expand.
	Realtime *Totals `json:"realtime,omitempty"`
}

// Type of a charge.
//
// Values:
//
// - `flat_fee`: A fixed-amount charge.
// - `usage_based`: A usage-priced charge.
type ChargeType string

const (
	ChargeTypeFlatFee    ChargeType = "flat_fee"
	ChargeTypeUsageBased ChargeType = "usage_based"
)

func (value ChargeType) Valid() bool {
	switch value {
	case ChargeTypeFlatFee, ChargeTypeUsageBased:
		return true
	default:
		return false
	}
}

// A usage-based charge for a customer.
type ChargeUsageBased struct {
	ID string `json:"id"`
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// An ISO-8601 timestamp representation of entity creation date.
	CreatedAt time.Time `json:"created_at"`
	// An ISO-8601 timestamp representation of entity last update date.
	UpdatedAt time.Time `json:"updated_at"`
	// An ISO-8601 timestamp representation of entity deletion date.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	// The type of the charge.
	Type ChargeType `json:"type"`
	// The customer owning the charge.
	Customer BillingCustomerReference `json:"customer"`
	// Indicates whether the charge lifecycle is controlled by OpenMeter or manually
	// overridden by the API user.
	LifecycleController LifecycleController `json:"lifecycle_controller"`
	// The subscription that originated the charge, when the charge was created from a
	// subscription item.
	Subscription *SubscriptionReference `json:"subscription,omitempty"`
	// The currency of the charge.
	Currency string `json:"currency"`
	// The lifecycle status of the charge.
	Status ChargeStatus `json:"status"`
	// The timestamp when the charge is intended to be invoiced.
	InvoiceAt time.Time `json:"invoice_at"`
	// The effective service period covered by the charge.
	ServicePeriod ClosedPeriod `json:"service_period"`
	// The full, unprorated service period of the charge.
	FullServicePeriod ClosedPeriod `json:"full_service_period"`
	// The billing period the charge belongs to.
	BillingPeriod ClosedPeriod `json:"billing_period"`
	// The earliest time when the charge should be advanced again by background
	// processing.
	AdvanceAfter *time.Time `json:"advance_after,omitempty"`
	// Unique reference ID of the charge.
	UniqueReferenceID *string `json:"unique_reference_id,omitempty"`
	// Settlement mode of the charge.
	SettlementMode SettlementMode `json:"settlement_mode"`
	// Tax configuration of the charge.
	TaxConfig *TaxConfig `json:"tax_config,omitempty"`
	// Discounts applied to the usage-based charge.
	Discounts *RateCardDiscounts `json:"discounts,omitempty"`
	// The feature associated with the charge.
	FeatureKey string `json:"feature_key"`
	// Aggregated booked and realtime totals for the charge.
	Totals ChargeTotals `json:"totals"`
	// The price of the charge.
	Price Price `json:"price"`
	// Current intent from the system lifecycle controller for a charge that has an
	// active manual override. The top-level charge fields remain the effective
	// customer-facing intent.
	SystemIntent *ChargeUsageBasedSystemIntent `json:"system_intent,omitempty"`
}

// Usage-based intent fields from the system lifecycle controller shadowed by a
// manual override.
type ChargeUsageBasedSystemIntent struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// The timestamp when the charge is intended to be invoiced.
	InvoiceAt time.Time `json:"invoice_at"`
	// The effective service period covered by the charge.
	ServicePeriod ClosedPeriod `json:"service_period"`
	// The full, unprorated service period of the charge.
	FullServicePeriod ClosedPeriod `json:"full_service_period"`
	// The billing period the charge belongs to.
	BillingPeriod ClosedPeriod `json:"billing_period"`
	// Discounts applied to the usage-based charge.
	Discounts *RateCardDiscounts `json:"discounts,omitempty"`
	// The price of the charge.
	Price Price `json:"price"`
	// The timestamp when the system lifecycle controller intent was deleted. The
	// effective charge can remain visible while a manual override is active.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

// Expands for customer charges.
//
// Values:
//
// - `real_time_usage`: The charge's real-time usage.
type ChargesExpand string

const (
	ChargesExpandRealTimeUsage ChargesExpand = "real_time_usage"
)

func (value ChargesExpand) Valid() bool {
	switch value {
	case ChargesExpandRealTimeUsage:
		return true
	default:
		return false
	}
}

// Flat fee charge create request.
type CreateChargeFlatFeeRequest struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string            `json:"description,omitempty"`
	Labels      *map[string]string `json:"labels,omitempty"`
	// The type of the charge.
	Type ChargeType `json:"type"`
	// The currency of the charge.
	Currency string `json:"currency"`
	// The timestamp when the charge is intended to be invoiced.
	InvoiceAt time.Time `json:"invoice_at"`
	// The effective service period covered by the charge.
	ServicePeriod ClosedPeriod `json:"service_period"`
	// Unique reference ID of the charge.
	UniqueReferenceID *string `json:"unique_reference_id,omitempty"`
	// Settlement mode of the charge.
	SettlementMode SettlementMode `json:"settlement_mode"`
	// Tax configuration of the charge.
	TaxConfig *TaxConfig `json:"tax_config,omitempty"`
	// Payment term of the flat fee charge.
	PaymentTerm PricePaymentTerm `json:"payment_term"`
	// The discounts applied to the charge.
	Discounts *ChargeFlatFeeDiscounts `json:"discounts,omitempty"`
	// The feature associated with the charge, when applicable.
	FeatureKey *string `json:"feature_key,omitempty"`
	// The proration configuration of the charge.
	ProrationConfiguration RateCardProrationConfiguration `json:"proration_configuration"`
	// The amount before proration of the charge.
	AmountBeforeProration CurrencyAmount `json:"amount_before_proration"`
	// The full, unprorated service period of the charge.
	FullServicePeriod *ClosedPeriod `json:"full_service_period,omitempty"`
	// The billing period the charge belongs to.
	BillingPeriod *ClosedPeriod `json:"billing_period,omitempty"`
}

// Customer charge.
//
// CreateChargeRequest is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the CreateChargeRequestFrom* constructors.
// The exported Type field is decode-side metadata; MarshalJSON round-trips the original payload and ignores writes to it.
type CreateChargeRequest struct {
	Type string `json:"type"`
	raw  json.RawMessage
}

func (u *CreateChargeRequest) UnmarshalJSON(data []byte) error {
	u.raw = append([]byte(nil), data...)
	if string(data) == "null" {
		u.Type = ""
		return nil
	}

	var envelope struct {
		Value string `json:"type"`
	}
	if err := json.Unmarshal(data, &envelope); err != nil {
		return err
	}
	u.Type = envelope.Value
	return nil
}

func (u CreateChargeRequest) MarshalJSON() ([]byte, error) {
	if len(u.raw) == 0 {
		return []byte("null"), nil
	}
	return append([]byte(nil), u.raw...), nil
}

func (u CreateChargeRequest) AsCreateChargeFlatFeeRequest() (*CreateChargeFlatFeeRequest, error) {
	if u.Type != "flat_fee" {
		return nil, fmt.Errorf("CreateChargeRequest: expected type %q, got %q", "flat_fee", u.Type)
	}
	var value CreateChargeFlatFeeRequest
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func CreateChargeRequestFromCreateChargeFlatFeeRequest(value CreateChargeFlatFeeRequest) (CreateChargeRequest, error) {
	value.Type = "flat_fee"
	raw, err := json.Marshal(value)
	if err != nil {
		return CreateChargeRequest{}, err
	}
	var result CreateChargeRequest
	if err := result.UnmarshalJSON(raw); err != nil {
		return CreateChargeRequest{}, err
	}
	return result, nil
}

func (u CreateChargeRequest) AsCreateChargeUsageBasedRequest() (*CreateChargeUsageBasedRequest, error) {
	if u.Type != "usage_based" {
		return nil, fmt.Errorf("CreateChargeRequest: expected type %q, got %q", "usage_based", u.Type)
	}
	var value CreateChargeUsageBasedRequest
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func CreateChargeRequestFromCreateChargeUsageBasedRequest(value CreateChargeUsageBasedRequest) (CreateChargeRequest, error) {
	value.Type = "usage_based"
	raw, err := json.Marshal(value)
	if err != nil {
		return CreateChargeRequest{}, err
	}
	var result CreateChargeRequest
	if err := result.UnmarshalJSON(raw); err != nil {
		return CreateChargeRequest{}, err
	}
	return result, nil
}

// Usage-based charge create request.
type CreateChargeUsageBasedRequest struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string            `json:"description,omitempty"`
	Labels      *map[string]string `json:"labels,omitempty"`
	// The type of the charge.
	Type ChargeType `json:"type"`
	// The currency of the charge.
	Currency string `json:"currency"`
	// The timestamp when the charge is intended to be invoiced.
	InvoiceAt time.Time `json:"invoice_at"`
	// The effective service period covered by the charge.
	ServicePeriod ClosedPeriod `json:"service_period"`
	// Unique reference ID of the charge.
	UniqueReferenceID *string `json:"unique_reference_id,omitempty"`
	// Settlement mode of the charge.
	SettlementMode SettlementMode `json:"settlement_mode"`
	// Tax configuration of the charge.
	TaxConfig *TaxConfig `json:"tax_config,omitempty"`
	// Discounts applied to the usage-based charge.
	Discounts *RateCardDiscounts `json:"discounts,omitempty"`
	// The feature associated with the charge.
	FeatureKey string `json:"feature_key"`
	// The price of the charge.
	Price Price `json:"price"`
	// The full, unprorated service period of the charge.
	FullServicePeriod *ClosedPeriod `json:"full_service_period,omitempty"`
	// The billing period the charge belongs to.
	BillingPeriod *ClosedPeriod `json:"billing_period,omitempty"`
}

// CreditAdjustment create request.
type CreateCreditAdjustmentRequest struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string            `json:"description,omitempty"`
	Labels      *map[string]string `json:"labels,omitempty"`
	// The currency of the granted credits.
	Currency BillingCurrencyCode `json:"currency"`
	// Granted credit amount.
	Amount Numeric `json:"amount"`
}

// Filters for the credit grant.
type CreateCreditGrantFilters struct {
	// Limit the credit grant to specific features. If no features are specified, the
	// credit grant can be used for any feature.
	Features *[]string `json:"features,omitempty"`
}

// Purchase and payment terms of the grant.
type CreateCreditGrantPurchase struct {
	// Currency of the purchase amount.
	Currency string `json:"currency"`
	// Cost basis per credit unit used to calculate the purchase amount.
	//
	// If `per_unit_cost_basis` is 0.50 and credit amount is $100.00, the total charge
	// is $50.00. The value must be greater than 0. If the cost basis is 0, use
	// `funding_method=none` instead.
	//
	// Defaults to 1.0.
	PerUnitCostBasis *Numeric `json:"per_unit_cost_basis,omitempty"`
	// Controls when credits become available for consumption.
	//
	// Defaults to `on_creation`.
	AvailabilityPolicy *CreditAvailabilityPolicy `json:"availability_policy,omitempty"`
}

// CreditGrant create request.
type CreateCreditGrantRequest struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string            `json:"description,omitempty"`
	Labels      *map[string]string `json:"labels,omitempty"`
	// Funding method of the grant.
	FundingMethod CreditFundingMethod `json:"funding_method"`
	// The currency of the granted credits.
	Currency BillingCurrencyCode `json:"currency"`
	// Granted credit amount.
	Amount Numeric `json:"amount"`
	// Present when a funding workflow applies (funding_method is not `none`).
	Purchase *CreateCreditGrantPurchase `json:"purchase,omitempty"`
	// Tax configuration for the grant.
	//
	// For `invoice` and `external` funding methods, tax configuration should be
	// provided to ensure correct revenue recognition. When not provided, the default
	// credit grant tax code is applied, if that's not set the global default taxcode
	// is used.
	TaxConfig *CreditGrantTaxConfig     `json:"tax_config,omitempty"`
	Filters   *CreateCreditGrantFilters `json:"filters,omitempty"`
	// Draw-down priority of the grant. Lower values have higher priority.
	Priority *int16 `json:"priority,omitempty"`
	// The timestamp when the credit grant becomes effective.
	//
	// Defaults to the current date and time.
	EffectiveAt *time.Time `json:"effective_at,omitempty"`
	// The duration after which the credit grant expires.
	//
	// Defaults to never expiring.
	ExpiresAfter *string `json:"expires_after,omitempty"`
	// Idempotency key for the credit grant creation request.
	//
	// When provided, reusing the same key returns an HTTP 409 Conflict instead of
	// creating a duplicate grant, which makes create requests safe to retry.
	Key *string `json:"key,omitempty"`
}

// Customer create request.
type CreateCustomerRequest struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string            `json:"description,omitempty"`
	Labels      *map[string]string `json:"labels,omitempty"`
	Key         string             `json:"key"`
	// Mapping to attribute metered usage to the customer by the event subject.
	UsageAttribution *CustomerUsageAttribution `json:"usage_attribution,omitempty"`
	// The primary email address of the customer.
	PrimaryEmail *string `json:"primary_email,omitempty"`
	// Currency of the customer. Used for billing, tax and invoicing.
	Currency *string `json:"currency,omitempty"`
	// The billing address of the customer. Used for tax and invoicing.
	BillingAddress *Address `json:"billing_address,omitempty"`
}

// A credit adjustment can be used to make manual adjustments to a customer's
// credit balance.
//
// Supported use-cases:
//
// - Usage correction
type CreditAdjustment struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
}

// When credits become available for consumption.
//
// - `on_creation`: Credits are available as soon as the grant is created.
// - `on_authorization`: Credits are available once the payment is authorized.
// - `on_settlement`: Credits are available once the payment is settled.
type CreditAvailabilityPolicy string

const (
	CreditAvailabilityPolicyOnCreation CreditAvailabilityPolicy = "on_creation"
)

func (value CreditAvailabilityPolicy) Valid() bool {
	switch value {
	case CreditAvailabilityPolicyOnCreation:
		return true
	default:
		return false
	}
}

// The credit balance by currency.
type CreditBalance struct {
	Currency BillingCurrencyCode `json:"currency"`
	// Credits available after applying currently live charge impacts.
	Live Numeric `json:"live"`
	// Credits that have been booked on the ledger as of the balance timestamp.
	Settled Numeric `json:"settled"`
	// Credits that have been granted but are not yet written to the ledger, or are
	// written to the ledger with a future booked time.
	Pending Numeric `json:"pending"`
}

// The balances of the credits of a customer.
type CreditBalances struct {
	// The timestamp of the balance retrieval.
	RetrievedAt time.Time `json:"retrieved_at"`
	// The balances by currencies.
	Balances []CreditBalance `json:"balances"`
}

// The funding method describes how the grant is funded.
//
// - `none`: No funding workflow applies, for example promotional grants
// - `invoice`: The grant is funded by an in-system invoice flow
// - `external`: The grant is funded outside the system (e.g., wire transfer,
// external invoice, or manual reconciliation)
type CreditFundingMethod string

const (
	CreditFundingMethodNone     CreditFundingMethod = "none"
	CreditFundingMethodInvoice  CreditFundingMethod = "invoice"
	CreditFundingMethodExternal CreditFundingMethod = "external"
)

func (value CreditFundingMethod) Valid() bool {
	switch value {
	case CreditFundingMethodNone, CreditFundingMethodInvoice, CreditFundingMethodExternal:
		return true
	default:
		return false
	}
}

// A credit grant allocates credits to a customer.
//
// Credits are drawn down against charges according to the settlement mode
// configured on the rate card.
type CreditGrant struct {
	ID string `json:"id"`
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// An ISO-8601 timestamp representation of entity creation date.
	CreatedAt time.Time `json:"created_at"`
	// An ISO-8601 timestamp representation of entity last update date.
	UpdatedAt time.Time `json:"updated_at"`
	// An ISO-8601 timestamp representation of entity deletion date.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	// Funding method of the grant.
	FundingMethod CreditFundingMethod `json:"funding_method"`
	// The currency of the granted credits.
	Currency BillingCurrencyCode `json:"currency"`
	// Granted credit amount.
	Amount Numeric `json:"amount"`
	// Present when a funding workflow applies (funding_method is not `none`).
	Purchase *CreditGrantPurchase `json:"purchase,omitempty"`
	// Tax configuration for the grant.
	//
	// For `invoice` and `external` funding methods, tax configuration should be
	// provided to ensure correct revenue recognition. When not provided, the default
	// credit grant tax code is applied, if that's not set the global default taxcode
	// is used.
	TaxConfig *CreditGrantTaxConfig `json:"tax_config,omitempty"`
	// Available when `funding_method` is `invoice`.
	Invoice *CreditGrantInvoiceReference `json:"invoice,omitempty"`
	Filters *CreditGrantFilters          `json:"filters,omitempty"`
	// Draw-down priority of the grant. Lower values have higher priority.
	Priority *int16 `json:"priority,omitempty"`
	// The timestamp when the credit grant becomes effective.
	//
	// Defaults to the current date and time.
	EffectiveAt *time.Time `json:"effective_at,omitempty"`
	// Idempotency key for the credit grant creation request.
	//
	// When provided, reusing the same key returns an HTTP 409 Conflict instead of
	// creating a duplicate grant, which makes create requests safe to retry.
	Key *string `json:"key,omitempty"`
	// The timestamp when the credit grant expires.
	//
	// Calculated from the grant effective time and `expires_after` if provided.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	// Timestamp when the grant was voided.
	VoidedAt *time.Time `json:"voided_at,omitempty"`
	// Current lifecycle status of the grant.
	Status CreditGrantStatus `json:"status"`
}

// Filters for the credit grant.
type CreditGrantFilters struct {
	// Limit the credit grant to specific features. If no features are specified, the
	// credit grant can be used for any feature.
	Features []string `json:"features,omitempty"`
}

// Invoice references for the grant.
type CreditGrantInvoiceReference struct {
	// Identifier of the invoice associated with the grant.
	ID *string `json:"id,omitempty"`
	// Identifier of the invoice line associated with the grant.
	Line *CreditGrantInvoiceReferenceLine `json:"line,omitempty"`
}

type CreditGrantInvoiceReferenceLine struct {
	ID string `json:"id"`
}

// Page paginated response.
type CreditGrantPagePaginatedResponse struct {
	Data []CreditGrant `json:"data"`
	Meta PaginatedMeta `json:"meta"`
}

// Purchase and payment terms of the grant.
type CreditGrantPurchase struct {
	// Currency of the purchase amount.
	Currency string `json:"currency"`
	// Cost basis per credit unit used to calculate the purchase amount.
	//
	// If `per_unit_cost_basis` is 0.50 and credit amount is $100.00, the total charge
	// is $50.00. The value must be greater than 0. If the cost basis is 0, use
	// `funding_method=none` instead.
	//
	// Defaults to 1.0.
	PerUnitCostBasis *Numeric `json:"per_unit_cost_basis,omitempty"`
	// The purchase amount. Calculated from `per_unit_cost_basis` and credit `amount`.
	Amount Numeric `json:"amount"`
	// Controls when credits become available for consumption.
	//
	// Defaults to `on_creation`.
	AvailabilityPolicy *CreditAvailabilityPolicy `json:"availability_policy,omitempty"`
	// Current payment settlement status.
	SettlementStatus *CreditPurchasePaymentSettlementStatus `json:"settlement_status,omitempty"`
}

// Credit grant lifecycle status.
//
// - `pending`: The credit block has been created but is not yet valid.
// (`effective_at` is in the future or availability_policy is not met)
// - `active`: The credit block is currently valid and eligible for consumption.
// (`effective_at` is in the past, `expires_at` is in the future and
// availability_policy is met)
// - `expired`: The credit block expired with remaining unused balance,
// `expires_at` time has passed.
// - `voided`: The credit block was voided. Remaining balance is forfeited.
type CreditGrantStatus string

const (
	CreditGrantStatusPending CreditGrantStatus = "pending"
	CreditGrantStatusActive  CreditGrantStatus = "active"
	CreditGrantStatusExpired CreditGrantStatus = "expired"
	CreditGrantStatusVoided  CreditGrantStatus = "voided"
)

func (value CreditGrantStatus) Valid() bool {
	switch value {
	case CreditGrantStatusPending, CreditGrantStatusActive, CreditGrantStatusExpired, CreditGrantStatusVoided:
		return true
	default:
		return false
	}
}

// Tax configuration for a credit grant.
//
// Tax configuration should be provided to ensure correct revenue recognition,
// including for externally funded grants.
type CreditGrantTaxConfig struct {
	// Tax behavior applied to the invoice line item.
	Behavior *TaxBehavior `json:"behavior,omitempty"`
	// Tax code applied to the invoice line item.
	TaxCode *TaxCodeReference `json:"tax_code,omitempty"`
}

// Describes how voiding a credit grant adjusts related payment state.
//
// - `none`: Voiding does not adjust invoices, payment authorization, settlement,
// payment intents, or external collection state.
type CreditGrantVoidPaymentAdjustment string

const (
	CreditGrantVoidPaymentAdjustmentNone CreditGrantVoidPaymentAdjustment = "none"
)

func (value CreditGrantVoidPaymentAdjustment) Valid() bool {
	switch value {
	case CreditGrantVoidPaymentAdjustmentNone:
		return true
	default:
		return false
	}
}

// Credit purchase payment settlement status.
//
// - `pending`: Payment has been initiated and is not yet authorized.
// - `authorized`: Payment has been authorized.
// - `settled`: Payment has been settled.
type CreditPurchasePaymentSettlementStatus string

const (
	CreditPurchasePaymentSettlementStatusPending    CreditPurchasePaymentSettlementStatus = "pending"
	CreditPurchasePaymentSettlementStatusAuthorized CreditPurchasePaymentSettlementStatus = "authorized"
	CreditPurchasePaymentSettlementStatusSettled    CreditPurchasePaymentSettlementStatus = "settled"
)

func (value CreditPurchasePaymentSettlementStatus) Valid() bool {
	switch value {
	case CreditPurchasePaymentSettlementStatusPending, CreditPurchasePaymentSettlementStatusAuthorized, CreditPurchasePaymentSettlementStatusSettled:
		return true
	default:
		return false
	}
}

// A credit transaction represents a single credit movement on the customer's
// balance.
//
// Credit transactions are immutable.
type CreditTransaction struct {
	ID string `json:"id"`
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// An ISO-8601 timestamp representation of entity creation date.
	CreatedAt time.Time `json:"created_at"`
	// The date and time the transaction was booked.
	BookedAt time.Time `json:"booked_at"`
	// The type of credit transaction.
	Type CreditTransactionType `json:"type"`
	// Currency of the balance affected by the transaction.
	Currency BillingCurrencyCode `json:"currency"`
	// Signed amount of the credit movement. Positive values add balance, negative
	// values reduce balance.
	Amount Numeric `json:"amount"`
	// The available balance before and after the transaction.
	AvailableBalance CreditTransactionAvailableBalance `json:"available_balance"`
}

type CreditTransactionAvailableBalance struct {
	Before Numeric `json:"before"`
	After  Numeric `json:"after"`
}

// Cursor paginated response.
type CreditTransactionPaginatedResponse struct {
	Data []CreditTransaction `json:"data"`
	Meta CursorMeta          `json:"meta"`
}

// The type of the credit transaction.
//
// - `funded`: Credit granted and available for consumption.
// - `consumed`: Credit consumed by usage or fees.
// - `expired`: Credit removed because it expired before being used.
// - `voided`: Credit removed because the grant was voided before being used.
type CreditTransactionType string

const (
	CreditTransactionTypeFunded   CreditTransactionType = "funded"
	CreditTransactionTypeConsumed CreditTransactionType = "consumed"
	CreditTransactionTypeExpired  CreditTransactionType = "expired"
	CreditTransactionTypeVoided   CreditTransactionType = "voided"
)

func (value CreditTransactionType) Valid() bool {
	switch value {
	case CreditTransactionTypeFunded, CreditTransactionTypeConsumed, CreditTransactionTypeExpired, CreditTransactionTypeVoided:
		return true
	default:
		return false
	}
}

// Monetary amount in a specific currency.
type CurrencyAmount struct {
	Amount   Numeric `json:"amount"`
	Currency string  `json:"currency"`
}

// Billing customer data.
type CustomerData struct {
	// The billing profile for the customer.
	//
	// If not provided, the default billing profile will be used.
	BillingProfile *ProfileReference `json:"billing_profile,omitempty"`
	// App customer data.
	AppData *AppCustomerData `json:"app_data,omitempty"`
}

// Page paginated response.
type CustomerPagePaginatedResponse struct {
	Data []Customer    `json:"data"`
	Meta PaginatedMeta `json:"meta"`
}

// Request to create a Stripe Checkout Session for the customer.
//
// Checkout Sessions are used to collect payment method information from customers
// in a secure, Stripe-hosted interface. This integration uses setup mode to
// collect payment methods that can be charged later for subscription billing.
type CustomerStripeCreateCheckoutSessionRequest struct {
	// Options for configuring the Stripe Checkout Session.
	//
	// These options are passed directly to Stripe's
	// [checkout session creation API](https://docs.stripe.com/api/checkout/sessions/create).
	StripeOptions AppStripeCreateCheckoutSessionRequestOptions `json:"stripe_options"`
}

// Request to create a Stripe Customer Portal Session for the customer.
//
// Useful to redirect the customer to the Stripe Customer Portal to manage their
// payment methods, change their billing address and access their invoice history.
// Only returns URL if the customer billing profile is linked to a stripe app and
// customer.
type CustomerStripeCreateCustomerPortalSessionRequest struct {
	// Options for configuring the Stripe Customer Portal Session.
	StripeOptions AppStripeCreateCustomerPortalSessionOptions `json:"stripe_options"`
}

// The proration configuration of the rate card.
type RateCardProrationConfiguration struct {
	// The proration mode of the rate card.
	Mode RateCardProrationMode `json:"mode"`
}

// The proration mode of the rate card.
//
// Values:
//
// - `no_proration`: No proration.
// - `prorate_prices`: Prorate the price based on the time remaining in the billing
// period.
type RateCardProrationMode string

const (
	RateCardProrationModeNoProration   RateCardProrationMode = "no_proration"
	RateCardProrationModeProratePrices RateCardProrationMode = "prorate_prices"
)

func (value RateCardProrationMode) Valid() bool {
	switch value {
	case RateCardProrationModeNoProration, RateCardProrationModeProratePrices:
		return true
	default:
		return false
	}
}

// Request body for updating the external payment settlement status of a credit
// grant.
type UpdateCreditGrantExternalSettlementRequest struct {
	// The new payment settlement status.
	Status CreditPurchasePaymentSettlementStatus `json:"status"`
}

// AppCustomerData upsert request.
type UpsertAppCustomerDataRequest struct {
	// Used if the customer has a linked Stripe app.
	Stripe *AppCustomerDataStripeInput `json:"stripe,omitempty"`
	// Used if the customer has a linked external invoicing app.
	ExternalInvoicing *AppCustomerDataExternalInvoicingInput `json:"external_invoicing,omitempty"`
}

// CustomerBillingData upsert request.
type UpsertCustomerBillingDataRequest struct {
	// The billing profile for the customer.
	//
	// If not provided, the default billing profile will be used.
	BillingProfile *ProfileReference `json:"billing_profile,omitempty"`
	// App customer data.
	AppData *AppCustomerDataInput `json:"app_data,omitempty"`
}

// Customer upsert request.
type UpsertCustomerRequest struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string            `json:"description,omitempty"`
	Labels      *map[string]string `json:"labels,omitempty"`
	// Mapping to attribute metered usage to the customer by the event subject.
	UsageAttribution *CustomerUsageAttribution `json:"usage_attribution,omitempty"`
	// The primary email address of the customer.
	PrimaryEmail *string `json:"primary_email,omitempty"`
	// Currency of the customer. Used for billing, tax and invoicing.
	Currency *string `json:"currency,omitempty"`
	// The billing address of the customer. Used for tax and invoicing.
	BillingAddress *Address `json:"billing_address,omitempty"`
}

// Request body for voiding a credit grant.
type VoidCreditGrantRequest struct {
	// How voiding adjusts payment state related to the grant.
	//
	// Currently only `none` is supported: voiding does not adjust invoices, payment
	// authorization, settlement, payment intents, or external collection state. If
	// payment later completes, the original invoiced amount may still be collected.
	PaymentAdjustment *CreditGrantVoidPaymentAdjustment `json:"payment_adjustment,omitempty"`
}