billinginvoice

package

v1.42.1 Latest Latest Go to latest Published: May 6, 2026 License: MIT Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/hanzoai/commerce

Links

Open Source Insights

Documentation ¶

Index ¶

func Query(db *datastore.Datastore) datastore.Query
type BillingInvoice
- func New(db *datastore.Datastore) *BillingInvoice
type LineItem
type LineItemType
type Status

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Query ¶

func Query(db *datastore.Datastore) datastore.Query

Types ¶

type BillingInvoice ¶

type BillingInvoice struct {
	mixin.Model[BillingInvoice]

	// Customer
	UserId        string `json:"userId"`
	CustomerEmail string `json:"customerEmail,omitempty"`

	// Subscription link (empty for one-off invoices)
	SubscriptionId string `json:"subscriptionId,omitempty"`

	// Billing period
	PeriodStart time.Time `json:"periodStart"`
	PeriodEnd   time.Time `json:"periodEnd"`

	// Financial summary (all in cents)
	Subtotal      int64   `json:"subtotal"`
	Tax           int64   `json:"tax"`
	TaxPercent    float64 `json:"taxPercent"`
	Discount      int64   `json:"discount"`
	DiscountName  string  `json:"discountName,omitempty"`
	CreditApplied int64   `json:"creditApplied"`
	AmountDue     int64   `json:"amountDue"`
	AmountPaid    int64   `json:"amountPaid"`

	Currency currency.Type `json:"currency" orm:"default:usd"`

	// Status lifecycle: draft -> open -> paid | void | uncollectible
	Status   Status    `json:"status" orm:"default:draft"`
	DueDate  time.Time `json:"dueDate,omitempty"`
	PaidAt   time.Time `json:"paidAt,omitempty"`
	VoidedAt time.Time `json:"voidedAt,omitempty"`

	// Payment reference
	PaymentMethod string `json:"paymentMethod,omitempty"` // "balance", "stripe", "credit"
	PaymentRef    string `json:"paymentRef,omitempty"`    // e.g. Stripe PaymentIntent ID

	// Invoice number (auto-increment per org)
	Number    int    `json:"number"`
	NumberStr string `json:"numberStr"` // "INV-0042"

	// Dunning retry tracking
	AttemptCount  int       `json:"attemptCount"`
	LastAttemptAt time.Time `json:"lastAttemptAt,omitempty"`
	NextAttemptAt time.Time `json:"nextAttemptAt,omitempty"`

	// Line items (JSON-serialized)
	LineItems  []LineItem `json:"lineItems,omitempty" datastore:"-"`
	LineItems_ string     `json:"-" datastore:",noindex"`

	Metadata  Map    `json:"metadata,omitempty" datastore:"-"`
	Metadata_ string `json:"-" datastore:",noindex"`
}

BillingInvoice is a proper billing invoice with line items, status lifecycle, and payment tracking. This is distinct from the legacy Invoice model (Kind="payment") which is actually a charge/payment record.

func New ¶

func New(db *datastore.Datastore) *BillingInvoice

func (*BillingInvoice) Finalize ¶

func (inv *BillingInvoice) Finalize() error

Finalize transitions an invoice from draft to open and computes AmountDue.

func (*BillingInvoice) Load ¶

func (inv *BillingInvoice) Load(ps []datastore.Property) (err error)

func (*BillingInvoice) MarkPaid ¶

func (inv *BillingInvoice) MarkPaid(method, ref string) error

MarkPaid marks the invoice as paid.

func (*BillingInvoice) MarkUncollectible ¶

func (inv *BillingInvoice) MarkUncollectible() error

MarkUncollectible marks an invoice as uncollectible after all retries.

func (*BillingInvoice) MarkVoid ¶

func (inv *BillingInvoice) MarkVoid() error

MarkVoid voids an open invoice.

func (*BillingInvoice) RecalculateSubtotal ¶

func (inv *BillingInvoice) RecalculateSubtotal()

RecalculateSubtotal sums all line item amounts.

func (*BillingInvoice) Save ¶

func (inv *BillingInvoice) Save() (ps []datastore.Property, err error)

func (*BillingInvoice) SetNumber ¶

func (inv *BillingInvoice) SetNumber(n int)

SetNumber assigns the invoice number and formatted string.

func (*BillingInvoice) Validator ¶

func (inv *BillingInvoice) Validator() *val.Validator

type LineItem ¶

type LineItem struct {
	Id          string       `json:"id"`
	Type        LineItemType `json:"type"`
	Description string       `json:"description"`

	// Usage items
	MeterId   string `json:"meterId,omitempty"`
	Quantity  int64  `json:"quantity,omitempty"`
	UnitPrice int64  `json:"unitPrice,omitempty"` // cents

	// Subscription items
	PlanId   string `json:"planId,omitempty"`
	PlanName string `json:"planName,omitempty"`

	Amount   int64         `json:"amount"` // cents
	Currency currency.Type `json:"currency"`

	PeriodStart time.Time `json:"periodStart,omitempty"`
	PeriodEnd   time.Time `json:"periodEnd,omitempty"`
}

LineItem represents a single charge on an invoice.

type LineItemType ¶

type LineItemType string

LineItemType categorizes what a line item charges for.

const (
	LineSubscription LineItemType = "subscription"
	LineUsage        LineItemType = "usage"
	LineOneOff       LineItemType = "one_off"
	LineProration    LineItemType = "proration"
)

type Status ¶

type Status string

Status represents the billing invoice lifecycle state.

const (
	Draft         Status = "draft"
	Open          Status = "open"
	Paid          Status = "paid"
	Void          Status = "void"
	Uncollectible Status = "uncollectible"
)

Source Files ¶

View all Source files

billinginvoice.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL