invoice

Documentation

Index

• Constants
• Variables
• type CreditService
• type CustomerService
• type Filter
• type Invoice
• type Item
• type ItemType
  • func (t ItemType) String() string
• type Locker
• type ProductService
• type Repository
• type Service
  • func NewService(stripeClient *client.API, invoiceRepository Repository, ...) *Service
  • func (s *Service) Close() error
  • func (s *Service) CreateInProvider(ctx context.Context, custmr customer.Customer, description string, ...) (*stripe.Invoice, error)
  • func (s *Service) DeleteByCustomer(ctx context.Context, c customer.Customer) error
  • func (s *Service) GenerateForCredits(ctx context.Context) error
  • func (s *Service) GetUpcoming(ctx context.Context, customerID string) (Invoice, error)
  • func (s *Service) Init(ctx context.Context) error
  • func (s *Service) List(ctx context.Context, filter Filter) ([]Invoice, error)
  • func (s *Service) ListAll(ctx context.Context, filter Filter) ([]Invoice, error)
  • func (s *Service) Reconcile(ctx context.Context) error
  • func (s *Service) SyncWithProvider(ctx context.Context, customr customer.Customer) error
  • func (s *Service) TriggerCreditOverdraftInvoices(ctx context.Context) error
• type State
  • func (s State) String() string

Constants

const (
	// ItemIDMetadataKey is used to uniquely identify the item in the invoice
	// this is useful when reconciling the invoice items for payments and
	// avoid creating duplicate credits
	ItemIDMetadataKey = "item_id"
	// ItemTypeMetadataKey is used to identify the item type in the invoice
	// this is useful when reconciling the invoice items for payments and
	// avoid creating duplicate invoices
	ItemTypeMetadataKey = "item_type"

	// ReconciledMetadataKey marks the invoice as reconciled and avoid processing it again
	// as an optimization
	ReconciledMetadataKey = "reconciled"

	// GenerateForCreditLockKey is used to lock the invoice generation within current application
	GenerateForCreditLockKey = "generate_for_credit"
)

const (
	// MonthCreditRangeForInvoice only month is supported for now, could be week or year
	MonthCreditRangeForInvoice = "month"
	CreditOverdraftDescription = "Invoice for the underpayment of credit utilization"
)

Variables

var (
	ErrNotFound      = fmt.Errorf("invoice not found")
	ErrInvalidDetail = fmt.Errorf("invalid invoice detail")
)

Types

type CreditService

type CreditService interface {
	Add(ctx context.Context, cred credit.Credit) error
	GetBalanceForRange(ctx context.Context, accountID string, start time.Time, end time.Time) (int64, error)
}

type CustomerService

type CustomerService interface {
	GetByID(ctx context.Context, id string) (customer.Customer, error)
	List(ctx context.Context, filter customer.Filter) ([]customer.Customer, error)
}

type Filter

type Filter struct {
	CustomerID  string
	NonZeroOnly bool
	State       State

	Pagination *pagination.Pagination
}

type Invoice

type Invoice struct {
	ID         string
	CustomerID string
	ProviderID string
	// State could be one of draft, open, paid, uncollectible, void
	State         State
	Currency      string
	Amount        int64
	HostedURL     string
	DueAt         time.Time
	EffectiveAt   time.Time
	CreatedAt     time.Time
	PeriodStartAt time.Time
	PeriodEndAt   time.Time

	Items    []Item
	Metadata metadata.Metadata
}

type Item

type Item struct {
	ID         string `json:"id"`
	ProviderID string `json:"provider_id"`
	// Name is the item name
	Name string `json:"name"`
	// Type is the item type
	Type ItemType `json:"type"`
	// UnitAmount is per unit cost
	UnitAmount int64 `json:"unit_amount"`
	// Quantity is the number of units
	Quantity int64 `json:"quantity"`

	// TimeRangeStart is the start time of the item since it's effective
	TimeRangeStart *time.Time `json:"range_start"`
	// TimeRangeEnd is the end time of the item since it's effective
	TimeRangeEnd *time.Time `json:"range_end"`
}

type ItemType

type ItemType string

const (
	// CreditItemType is used to charge for the credits used in the system
	// as overdraft
	CreditItemType ItemType = "credit"
)

func (ItemType) String

func (t ItemType) String() string

type Locker

type Locker interface {
	TryLock(ctx context.Context, id string) (*db.Lock, error)
}

type ProductService

type ProductService interface {
	GetByID(ctx context.Context, id string) (product.Product, error)
}

type Repository

type Repository interface {
	Create(ctx context.Context, invoice Invoice) (Invoice, error)
	GetByID(ctx context.Context, id string) (Invoice, error)
	List(ctx context.Context, filter Filter) ([]Invoice, error)
	UpdateByID(ctx context.Context, invoice Invoice) (Invoice, error)
	Delete(ctx context.Context, id string) error
}

type Service

type Service struct {
	// contains filtered or unexported fields
}

func NewService

func NewService(stripeClient *client.API, invoiceRepository Repository,
	customerService CustomerService, creditService CreditService, productService ProductService,
	locker Locker, cfg billing.Config) *Service

func (*Service) Close

func (s *Service) Close() error

func (*Service) CreateInProvider

func (s *Service) CreateInProvider(ctx context.Context, custmr customer.Customer,
	description string, items []Item, currency string) (*stripe.Invoice, error)

CreateInProvider creates a custom invoice with items in the provider. Once created the invoice object will be synced back within system using regular syncer/webhook loop.

func (*Service) DeleteByCustomer

func (s *Service) DeleteByCustomer(ctx context.Context, c customer.Customer) error

func (*Service) GenerateForCredits

func (s *Service) GenerateForCredits(ctx context.Context) error

GenerateForCredits finds all customers which has credit min limit lower than 0, that is, allows for negative balance and generates an invoice for them. Invoices will be paid asynchronously by the customer but system need to reconcile the token balance once it's paid.

func (*Service) GetUpcoming

func (s *Service) GetUpcoming(ctx context.Context, customerID string) (Invoice, error)

GetUpcoming returns the upcoming invoice for the customer based on the active subscription plan. If no upcoming invoice is found, it returns empty.

func (*Service) Init

func (s *Service) Init(ctx context.Context) error

func (*Service) List

func (s *Service) List(ctx context.Context, filter Filter) ([]Invoice, error)

List currently queries stripe for invoices, but it should be refactored to query our own database

func (*Service) ListAll

func (s *Service) ListAll(ctx context.Context, filter Filter) ([]Invoice, error)

ListAll should only be called by admin users

func (*Service) Reconcile

func (s *Service) Reconcile(ctx context.Context) error

Reconcile checks all paid invoices and reconciles them with the system. If the invoice was created for credit overdraft, it will credit the customer account with the amount of the invoice.

func (*Service) SyncWithProvider

func (s *Service) SyncWithProvider(ctx context.Context, customr customer.Customer) error

func (*Service) TriggerCreditOverdraftInvoices

func (s *Service) TriggerCreditOverdraftInvoices(ctx context.Context) error

TriggerCreditOverdraftInvoices is on-demand trigger for generating credit overdraft invoices if applicable.

type State

type State string

const (
	DraftState State = "draft"
	OpenState  State = "open"
	PaidState  State = "paid"
)

func (State) String

func (s State) String() string