api/v3/client/models_billing.go

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

package openmeter

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

// BillingCollectionAlignment specifies when the pending line items should be
// collected into an invoice.
type CollectionAlignment string

const (
	CollectionAlignmentSubscription CollectionAlignment = "subscription"
	CollectionAlignmentAnchored     CollectionAlignment = "anchored"
)

func (value CollectionAlignment) Valid() bool {
	switch value {
	case CollectionAlignmentSubscription, CollectionAlignmentAnchored:
		return true
	default:
		return false
	}
}

// BillingProfile create request.
type CreateBillingProfileRequest 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 name and contact information for the supplier this billing profile
	// represents
	Supplier Party `json:"supplier"`
	// The billing workflow settings for this profile
	Workflow Workflow `json:"workflow"`
	// The applications used by this billing profile.
	Apps ProfileAppReferences `json:"apps"`
	// Whether this is the default profile.
	Default bool `json:"default"`
}

// Party represents a person or business entity.
type Party struct {
	// Unique identifier for the party.
	ID *string `json:"id,omitempty"`
	// An optional unique key of the party.
	Key *string `json:"key,omitempty"`
	// Legal name or representation of the party.
	Name *string `json:"name,omitempty"`
	// The entity's legal identification used for tax purposes. They may have other
	// numbers, but we're only interested in those valid for tax purposes.
	TaxID *PartyTaxIdentity `json:"tax_id,omitempty"`
	// Address for where information should be sent if needed.
	Addresses *PartyAddresses `json:"addresses,omitempty"`
}

// Billing profiles contain the settings for billing and controls invoice
// generation.
type Profile 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 name and contact information for the supplier this billing profile
	// represents
	Supplier Party `json:"supplier"`
	// The billing workflow settings for this profile
	Workflow Workflow `json:"workflow"`
	// The applications used by this billing profile.
	Apps ProfileAppReferences `json:"apps"`
	// Whether this is the default profile.
	Default bool `json:"default"`
}

// References to the applications used by a billing profile.
type ProfileAppReferences struct {
	// The tax app used for this workflow.
	Tax AppReference `json:"tax"`
	// The invoicing app used for this workflow.
	Invoicing AppReference `json:"invoicing"`
	// The payment app used for this workflow.
	Payment AppReference `json:"payment"`
}

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

// Recurring period with an anchor and an interval.
type RecurringPeriod struct {
	// A date-time anchor to base the recurring period on.
	Anchor time.Time `json:"anchor"`
	// The interval duration in ISO 8601 format.
	Interval string `json:"interval"`
}

// BillingProfile upsert request.
type UpsertBillingProfileRequest 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 name and contact information for the supplier this billing profile
	// represents
	Supplier Party `json:"supplier"`
	// The billing workflow settings for this profile
	Workflow Workflow `json:"workflow"`
	// Whether this is the default profile.
	Default bool `json:"default"`
}

// Billing workflow settings.
type Workflow struct {
	// The collection settings for this workflow
	Collection *WorkflowCollectionSettings `json:"collection,omitempty"`
	// The invoicing settings for this workflow
	Invoicing *WorkflowInvoicingSettings `json:"invoicing,omitempty"`
	// The payment settings for this workflow
	Payment *WorkflowPaymentSettings `json:"payment,omitempty"`
	// The tax settings for this workflow
	Tax *WorkflowTaxSettings `json:"tax,omitempty"`
}

// The alignment for collecting the pending line items into an invoice.
//
// Defaults to subscription, which means that we are to create a new invoice every
// time the a subscription period starts (for in advance items) or ends (for in
// arrears items).
//
// WorkflowCollectionAlignment is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the WorkflowCollectionAlignmentFrom* constructors.
// The exported Type field is decode-side metadata; MarshalJSON round-trips the original payload and ignores writes to it.
type WorkflowCollectionAlignment struct {
	Type string `json:"type"`
	raw  json.RawMessage
}

func (u *WorkflowCollectionAlignment) 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 WorkflowCollectionAlignment) MarshalJSON() ([]byte, error) {
	if len(u.raw) == 0 {
		return []byte("null"), nil
	}
	return append([]byte(nil), u.raw...), nil
}

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

func WorkflowCollectionAlignmentFromWorkflowCollectionAlignmentSubscription(value WorkflowCollectionAlignmentSubscription) (WorkflowCollectionAlignment, error) {
	value.Type = "subscription"
	raw, err := json.Marshal(value)
	if err != nil {
		return WorkflowCollectionAlignment{}, err
	}
	var result WorkflowCollectionAlignment
	if err := result.UnmarshalJSON(raw); err != nil {
		return WorkflowCollectionAlignment{}, err
	}
	return result, nil
}

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

func WorkflowCollectionAlignmentFromWorkflowCollectionAlignmentAnchored(value WorkflowCollectionAlignmentAnchored) (WorkflowCollectionAlignment, error) {
	value.Type = "anchored"
	raw, err := json.Marshal(value)
	if err != nil {
		return WorkflowCollectionAlignment{}, err
	}
	var result WorkflowCollectionAlignment
	if err := result.UnmarshalJSON(raw); err != nil {
		return WorkflowCollectionAlignment{}, err
	}
	return result, nil
}

// BillingWorkflowCollectionAlignmentAnchored specifies the alignment for
// collecting the pending line items into an invoice.
type WorkflowCollectionAlignmentAnchored struct {
	// The type of alignment.
	Type CollectionAlignment `json:"type"`
	// The recurring period for the alignment.
	RecurringPeriod RecurringPeriod `json:"recurring_period"`
}

// BillingWorkflowCollectionAlignmentSubscription specifies the alignment for
// collecting the pending line items into an invoice.
type WorkflowCollectionAlignmentSubscription struct {
	// The type of alignment.
	Type CollectionAlignment `json:"type"`
}

// Workflow collection specifies how to collect the pending line items for an
// invoice.
type WorkflowCollectionSettings struct {
	// The alignment for collecting the pending line items into an invoice.
	Alignment *WorkflowCollectionAlignment `json:"alignment,omitempty"`
	// This grace period can be used to delay the collection of the pending line items
	// specified in alignment.
	//
	// This is useful, in case of multiple subscriptions having slightly different
	// billing periods.
	Interval *string `json:"interval,omitempty"`
}

// Invoice settings for a billing workflow.
type WorkflowInvoicingSettings struct {
	// Whether to automatically issue the invoice after the draftPeriod has passed.
	AutoAdvance *bool `json:"auto_advance,omitempty"`
	// The period for the invoice to be kept in draft status for manual reviews.
	DraftPeriod *string `json:"draft_period,omitempty"`
	// Should progressive billing be allowed for this workflow?
	ProgressiveBilling *bool `json:"progressive_billing,omitempty"`
	// Controls how subscription-ending shortened service periods are billed.
	SubscriptionEndProrationMode *WorkflowInvoicingSubscriptionEndProrationMode `json:"subscription_end_proration_mode,omitempty"`
}

// Billing workflow subscription end proration mode.
type WorkflowInvoicingSubscriptionEndProrationMode string

const (
	WorkflowInvoicingSubscriptionEndProrationModeBillFullPeriod   WorkflowInvoicingSubscriptionEndProrationMode = "bill_full_period"
	WorkflowInvoicingSubscriptionEndProrationModeBillActualPeriod WorkflowInvoicingSubscriptionEndProrationMode = "bill_actual_period"
)

func (value WorkflowInvoicingSubscriptionEndProrationMode) Valid() bool {
	switch value {
	case WorkflowInvoicingSubscriptionEndProrationModeBillFullPeriod, WorkflowInvoicingSubscriptionEndProrationModeBillActualPeriod:
		return true
	default:
		return false
	}
}

// Tax settings for a billing workflow.
type WorkflowTaxSettings struct {
	// Enable automatic tax calculation when tax is supported by the app. For example,
	// with Stripe Invoicing when enabled, tax is calculated via Stripe Tax.
	Enabled *bool `json:"enabled,omitempty"`
	// Enforce tax calculation when tax is supported by the app. When enabled, the
	// billing system will not allow to create an invoice without tax calculation.
	// Enforcement is different per apps, for example, Stripe app requires customer to
	// have a tax location when starting a paid subscription.
	Enforced *bool `json:"enforced,omitempty"`
	// Default tax configuration to apply to the invoices for line items.
	//
	// Setting a tax code (`stripe.code` / `taxCodeId`) on a profile's default tax
	// config is deprecated and can no longer be added or changed: the organization
	// default tax code is used instead. Existing tax-code values may still be removed,
	// and `behavior` remains fully supported.
	DefaultTaxConfig *TaxConfig `json:"default_tax_config,omitempty"`
}