lunchmoney

package module
v0.6.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 12, 2026 License: MIT Imports: 12 Imported by: 6

README

lunchmoney

GoDoc Go Report Card

Golang API wrapper for Lunch Money API

To use this API, you need to create an API token by following the directions at developers.lunchmoney.app.

Notes

  • We currently only support read only requests. We'd love a PR to add support for write though!
  • We currently only support Go 1.23 and greater.

Documentation

Index

Constants

View Source 
const (
	// BaseAPIURL is the base url we use for all API requests.
	BaseAPIURL = "https://dev.lunchmoney.app/"
)

Variables

This section is empty.

Functions

func ParseCurrency 

func ParseCurrency(amount, currency string) (*money.Money, error)

ParseCurrency converts a string amount and currency code into a money.Money struct. It parses the amount as a float, multiplies by 100 to convert to cents, and returns a Money object in the specified currency. Returns an error if the amount can't be parsed.

Types

type Asset 

type Asset struct {
	ID              int64     `json:"id"`
	TypeName        string    `json:"type_name"`
	SubtypeName     string    `json:"subtype_name"`
	Name            string    `json:"name"`
	DisplayName     string    `json:"display_name"`
	Balance         string    `json:"balance"`
	BalanceAsOf     time.Time `json:"balance_as_of"`
	ToBase          float64   `json:"to_base"` // the balance converted to the user's primary currency
	Currency        string    `json:"currency"`
	Status          string    `json:"status"`
	InstitutionName string    `json:"institution_name"`
	CreatedAt       time.Time `json:"created_at"`
}

Asset is a single LM asset.

func (*Asset) ParsedAmount 

func (a *Asset) ParsedAmount() (*money.Money, error)

ParsedAmount converts the asset's balance and currency into a money.Money object. This provides a convenient way to work with the asset's value using the go-money library's currency handling capabilities. Returns an error if the balance cannot be parsed.

type AssetsResponse 

type AssetsResponse struct {
	Assets []*Asset `json:"assets"`
}

AssetsResponse is a response to an asset lookup.

type Budget 

type Budget struct {
	CategoryGroupName string                 `json:"category_group_name,omitempty"`
	CategoryID        int                    `json:"category_id"`
	CategoryName      string                 `json:"category_name"`
	Data              map[string]*BudgetData `json:"data,omitempty" validate:"dive"`
	ExcludeFromBudget bool                   `json:"exclude_from_budget"`
	ExcludeFromTotals bool                   `json:"exclude_from_totals"`
	GroupID           int                    `json:"group_id"`
	HasChildren       bool                   `json:"has_children,omitempty"`
	IsGroup           bool                   `json:"is_group,omitempty"`
	IsIncome          bool                   `json:"is_income"`
	Order             int                    `json:"order"`
	Recurring         struct {
		Sum  float64 `json:"sum"`
		List []struct {
			Payee    string  `json:"payee"`
			Amount   string  `json:"amount"`
			Currency string  `json:"currency"`
			ToBase   float64 `json:"to_base"`
		} `json:"list"`
	} `json:"recurring,omitempty"`
}

Budget defines a categories budget over time.

type BudgetData 

type BudgetData struct {
	BudgetMonth     string      `json:"budget_month,omitempty" validate:"datetime=2006-01-02"`
	BudgetToBase    float64     `json:"budget_to_base,omitempty"`
	BudgetAmount    json.Number `json:"budget_amount,omitempty"`
	BudgetCurrency  string      `json:"budget_currency,omitempty"`
	SpendingToBase  float64     `json:"spending_to_base,omitempty"`
	NumTransactions int         `json:"num_transactions,omitempty"`
}

BudgetData is a single month's budget for a category.

func (*BudgetData) ParsedAmount 

func (b *BudgetData) ParsedAmount() (*money.Money, error)

ParsedAmount converts the budget amount and currency into a money.Money object. This provides a convenient way to work with budget figures using the go-money library's currency handling capabilities. Returns an error if the amount cannot be parsed.

type BudgetFilters 

type BudgetFilters struct {
	StartDate string `json:"start_date" validate:"datetime=2006-01-02,required"`
	EndDate   string `json:"end_date" validate:"datetime=2006-01-02,required"`
}

BudgetFilters are options to pass into the request for budget history.

func (*BudgetFilters) ToMap 

func (r *BudgetFilters) ToMap() (map[string]string, error)

ToMap converts the budget filters to a string map to be sent with the request as GET parameters. This method formats the date filters correctly for the Lunch Money API. It marshals the filter struct to JSON and then unmarshals it to a string map.

type CategoriesResponse 

type CategoriesResponse struct {
	Categories []*Category `json:"categories"`
	Error      string      `json:"error"`
}

CategoriesResponse is the response we get from requesting categories. It contains a list of categories and an optional error message.

type Category 

type Category struct {
	ID                int64     `json:"id"`                  // Unique identifier for the category
	Name              string    `json:"name"`                // Display name of the category
	Description       string    `json:"description"`         // Optional description of the category
	IsIncome          bool      `json:"is_income"`           // Whether this category represents income
	ExcludeFromBudget bool      `json:"exclude_from_budget"` // Whether to exclude from budget calculations
	ExcludeFromTotals bool      `json:"exclude_from_totals"` // Whether to exclude from total calculations
	UpdatedAt         time.Time `json:"updated_at"`          // Last modification timestamp
	CreatedAt         time.Time `json:"created_at"`          // Creation timestamp
	IsGroup           bool      `json:"is_group"`            // Whether this category is a group
	GroupID           int64     `json:"group_id"`            // ID of the parent group, if any
}

Category represents a single Lunch Money category. Categories are used to organize transactions and budgets. They can be grouped hierarchically and marked as income or excluded from various calculations.

type Client 

type Client struct {
	HTTP *http.Client
	Base *url.URL
}

Client holds our base configuration for our LunchMoney client.

func NewClient 

func NewClient(apikey string) (*Client, error)

NewClient creates a new client with the specified API key.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, options map[string]string) (io.Reader, error)

Get makes a request using the client to the path specified with the key/value pairs specified in options. It returns the body of the response or an error.

func (*Client) GetAssets 

func (c *Client) GetAssets(ctx context.Context) ([]*Asset, error)

GetAssets retrieves all assets from the Lunch Money API. It returns a slice of Asset objects containing information about each asset, including balance, institution, and status details. Returns an error if the request fails.

func (*Client) GetBudgets 

func (c *Client) GetBudgets(ctx context.Context, filters *BudgetFilters) ([]*Budget, error)

GetBudgets returns budgets within a time period.

func (*Client) GetCategories added in v0.4.0 

func (c *Client) GetCategories(ctx context.Context) ([]*Category, error)

GetCategories returns a flattened list of all categories in alphabetical order associated with the user's account. This includes both regular categories and category groups. The returned categories include metadata such as creation time, group relationships, and budget exclusion settings.

The context can be used to control the request lifecycle. Returns an error if the API request fails or if the response cannot be validated.

func (*Client) GetCategory added in v0.4.0 

func (c *Client) GetCategory(ctx context.Context, id int64) (*Category, error)

GetCategory retrieves a single category by its ID. It returns detailed information about the category including its metadata, group relationships, and various settings.

Parameters:

  • ctx: Context for controlling the request lifecycle
  • id: The unique identifier of the category to retrieve

Returns the category details or an error if the request fails or the response cannot be validated.

func (*Client) GetPlaidAccounts 

func (c *Client) GetPlaidAccounts(ctx context.Context) ([]*PlaidAccount, error)

GetPlaidAccounts retrieves all Plaid-connected accounts from the Lunch Money API. It returns a slice of PlaidAccount objects containing information about each account, including balance, institution information, and status. Returns an error if the request fails.

func (*Client) GetRecurringExpenses 

func (c *Client) GetRecurringExpenses(ctx context.Context, filters *RecurringExpenseFilters) ([]*RecurringExpense, error)

GetRecurringExpenses retrieves all recurring expenses from the Lunch Money API based on the provided filters. It returns a slice of RecurringExpense objects or an error if the request fails. The filters parameter can be used to specify date ranges and other criteria.

func (*Client) GetTags 

func (c *Client) GetTags(ctx context.Context) ([]*Tag, error)

GetTags retrieves all tags from the Lunch Money API. It returns a slice of Tag objects containing tag details such as ID, name, and description. Returns an error if the request fails or if any tag fails validation.

func (*Client) GetTransaction 

func (c *Client) GetTransaction(ctx context.Context, id int64, filters *TransactionFilters) (*Transaction, error)

GetTransaction retrieves a single transaction from the Lunch Money API by its ID. It returns the transaction details or an error if the request fails. The filters parameter can be used to specify additional query parameters for the request.

func (*Client) GetTransactions 

func (c *Client) GetTransactions(ctx context.Context, filters *TransactionFilters) ([]*Transaction, error)

GetTransactions retrieves all transactions from the Lunch Money API based on the provided filters. It returns a slice of Transaction objects or an error if the request fails. The filters parameter can be used to narrow down results by date range, category, and other criteria.

func (*Client) GetUser added in v0.4.0 

func (c *Client) GetUser(ctx context.Context) (*User, error)

GetUser retrieves information about the currently authenticated user. It returns details such as user name, email, ID, and account preferences.

func (*Client) InsertTransactions added in v0.5.0 

func (c *Client) InsertTransactions(ctx context.Context, itReq InsertTransactionsRequest) (*InsertTransactionsResponse, error)

InsertTransactions creates new transactions in the Lunch Money API. It takes an InsertTransactionsRequest with transaction details and options. Returns the IDs of the created transactions or an error if the insertion fails.

func (*Client) Post added in v0.5.0 

func (c *Client) Post(ctx context.Context, path string, body any) (io.Reader, error)

Post performs an HTTP POST request to the specified API endpoint with the provided body. It returns the response body as an io.Reader or an error if the request fails.

func (*Client) Put added in v0.4.0 

func (c *Client) Put(ctx context.Context, path string, body any) (io.Reader, error)

Put performs an HTTP PUT request to the specified API endpoint with the provided body. It returns the response body as an io.Reader or an error if the request fails.

func (*Client) UpdateAsset added in v0.5.0 

func (c *Client) UpdateAsset(ctx context.Context, id int64, asset *UpdateAsset) (*Asset, error)

UpdateAsset modifies an existing asset with the specified ID using the provided fields. It returns the updated asset information or an error if the update fails. Only fields that are non-nil in the asset parameter will be updated.

func (*Client) UpdateTransaction added in v0.4.0 

func (c *Client) UpdateTransaction(ctx context.Context, id int64, ut *UpdateTransaction) (*UpdateTransactionResp, error)

UpdateTransaction modifies an existing transaction with the specified ID. It takes an UpdateTransaction object with the fields to be updated. Returns information about the update operation or an error if the update fails.

type ErrorResponse 

type ErrorResponse struct {
	ErrorString any   `json:"error,omitempty"`
	ErrorsArray []any `json:"errors,omitempty"`
}

ErrorResponse is json if we get an error from the LM API.

func (*ErrorResponse) Error 

func (e *ErrorResponse) Error() string

type InsertTransaction added in v0.5.0 

type InsertTransaction struct {
	Date           string `json:"date" validate:"datetime=2006-01-02"`
	Amount         string `json:"amount"`
	CategoryID     *int64 `json:"category_id,omitempty"`
	Payee          string `json:"payee,omitempty"`
	Currency       string `json:"currency,omitempty"`
	AssetID        *int64 `json:"asset_id,omitempty"`
	PlaidAccountID *int64 `json:"plaid_account_id,omitempty"`
	RecurringID    *int64 `json:"recurring_id,omitempty"`
	Notes          string `json:"notes,omitempty"`
	Status         string `json:"status,omitempty" validate:"omitnil,oneof=cleared uncleared"`
	ExternalID     string `json:"external_id,omitempty" validate:"max=75"`
	TagsIDs        []int  `json:"tags,omitempty"`
}

InsertTransaction represents a single transaction to be created in the Lunch Money system. It contains all the details needed to create a new transaction, with required fields being Date and Amount, while other fields are optional.

type InsertTransactionsRequest added in v0.5.0 

type InsertTransactionsRequest struct {
	ApplyRules        bool                `json:"apply_rules,omitempty"`
	SkipDuplicates    bool                `json:"skip_duplicates,omitempty"`
	CheckForRecurring bool                `json:"check_for_recurring,omitempty"`
	DebitAsNegative   bool                `json:"debit_as_negative,omitempty"`
	SkipBalanceUpdate bool                `json:"skip_balance_update,omitempty"`
	Transactions      []InsertTransaction `json:"transactions"`
}

InsertTransactionsRequest contains the data needed to create one or more transactions. It includes options for how the transactions should be processed by the Lunch Money system.

type InsertTransactionsResponse added in v0.5.0 

type InsertTransactionsResponse struct {
	IDs []int64 `json:"ids"`
}

InsertTransactionsResponse contains the IDs of transactions created through the InsertTransactions method. These IDs can be used to reference the newly created transactions in subsequent API calls.

type PlaidAccount 

type PlaidAccount struct {
	ID                int64     `json:"id"`
	DateLinked        string    `json:"date_linked"`
	Name              string    `json:"name"`
	DisplayName       string    `json:"display_name"`
	Type              string    `json:"type"`
	Subtype           string    `json:"subtype"`
	Mask              string    `json:"mask"`
	InstitutionName   string    `json:"institution_name"`
	Status            string    `json:"status"`
	LastImport        time.Time `json:"last_import"`
	Balance           string    `json:"balance"`
	ToBase            float64   `json:"to_base"` // the balance converted to the user's primary currency
	Currency          string    `json:"currency"`
	BalanceLastUpdate time.Time `json:"balance_last_update"`
	Limit             int64     `json:"limit"`
}

PlaidAccount is a single LM Plaid account.

func (*PlaidAccount) ParsedAmount 

func (p *PlaidAccount) ParsedAmount() (*money.Money, error)

ParsedAmount converts the Plaid account balance and currency into a money.Money object. This provides a convenient way to work with account balances using the go-money library's currency handling capabilities. Returns an error if the balance cannot be parsed.

type PlaidAccountsResponse 

type PlaidAccountsResponse struct {
	PlaidAccounts []*PlaidAccount `json:"plaid_accounts"`
}

PlaidAccountsResponse is a list plaid accounts response.

type RecurringExpense 

type RecurringExpense struct {
	ID             int64     `json:"id"`
	StartDate      string    `json:"start_date" validate:"datetime=2006-01-02"`
	EndDate        string    `json:"end_date" validate:"datetime=2006-01-02"`
	Cadence        string    `json:"cadence"`
	Payee          string    `json:"payee"`
	Amount         string    `json:"amount"`
	Currency       string    `json:"currency"`
	CreatedAt      time.Time `json:"created_at"`
	Description    string    `json:"description"`
	BillingDate    string    `json:"billing_date"`
	Type           string    `json:"type"`
	OriginalName   string    `json:"original_name"`
	Source         string    `json:"source"`
	PlaidAccountID int64     `json:"plaid_account_id"`
	AssetID        int64     `json:"asset_id"`
	TransactionID  int64     `json:"transaction_id"`
}

RecurringExpense is like a transaction, but one that's scheduled to happen.

func (*RecurringExpense) ParsedAmount 

func (r *RecurringExpense) ParsedAmount() (*money.Money, error)

ParsedAmount converts the recurring expense's amount and currency into a money.Money object. This provides a convenient way to work with the expense amount using the go-money library's currency handling capabilities. Returns an error if the amount cannot be parsed.

type RecurringExpenseFilters 

type RecurringExpenseFilters struct {
	StartDate       string `json:"start_date" validate:"omitempty,datetime=2006-01-02"`
	DebitAsNegative bool   `json:"debit_as_negative"`
}

RecurringExpenseFilters are options to pass to the request.

func (*RecurringExpenseFilters) ToMap 

func (r *RecurringExpenseFilters) ToMap() (map[string]string, error)

ToMap converts the recurring expense filters to a string map to be sent with the request as GET parameters. This method formats filter parameters correctly for the Lunch Money API. It marshals the filter struct to JSON and then unmarshals it to a string map.

type RecurringExpensesResponse 

type RecurringExpensesResponse struct {
	RecurringExpenses []*RecurringExpense `json:"recurring_expenses"`
}

RecurringExpensesResponse is the data struct we get back from a get request.

type Tag 

type Tag struct {
	ID          int    `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

Tag is a single LM tag.

type TagsResponse 

type TagsResponse []*Tag

TagsResponse is the response from getting all tags.

type Transaction 

type Transaction struct {
	ID             int64  `json:"id"`
	Date           string `json:"date" validate:"omitempty,datetime=2006-01-02"`
	Payee          string `json:"payee"`
	Amount         string `json:"amount"`
	Currency       string `json:"currency"`
	Notes          string `json:"notes"`
	CategoryID     int64  `json:"category_id"`
	RecurringID    int64  `json:"recurring_id"`
	AssetID        int64  `json:"asset_id"`
	PlaidAccountID int64  `json:"plaid_account_id"`
	Status         string `json:"status"`
	IsGroup        bool   `json:"is_group"`
	GroupID        int64  `json:"group_id"`
	ParentID       int64  `json:"parent_id"`
	ExternalID     string `json:"external_id"`
	// Additional fields from API response
	ToBase                  float64 `json:"to_base"`
	CategoryName            string  `json:"category_name"`
	CategoryGroupID         int64   `json:"category_group_id"`
	CategoryGroupName       string  `json:"category_group_name"`
	IsIncome                bool    `json:"is_income"`
	ExcludeFromBudget       bool    `json:"exclude_from_budget"`
	ExcludeFromTotals       bool    `json:"exclude_from_totals"`
	CreatedAt               string  `json:"created_at"`
	UpdatedAt               string  `json:"updated_at"`
	IsPending               bool    `json:"is_pending"`
	OriginalName            string  `json:"original_name"`
	RecurringPayee          string  `json:"recurring_payee"`
	RecurringDescription    string  `json:"recurring_description"`
	RecurringCadence        string  `json:"recurring_cadence"`
	RecurringType           string  `json:"recurring_type"`
	RecurringAmount         string  `json:"recurring_amount"`
	RecurringCurrency       string  `json:"recurring_currency"`
	HasChildren             bool    `json:"has_children"`
	AssetInstitutionName    string  `json:"asset_institution_name"`
	AssetName               string  `json:"asset_name"`
	AssetDisplayName        string  `json:"asset_display_name"`
	AssetStatus             string  `json:"asset_status"`
	PlaidAccountName        string  `json:"plaid_account_name"`
	PlaidAccountMask        string  `json:"plaid_account_mask"`
	InstitutionName         string  `json:"institution_name"`
	PlaidAccountDisplayName string  `json:"plaid_account_display_name"`
	PlaidMetadata           string  `json:"plaid_metadata"`
	PlaidCategory           string  `json:"plaid_category"`
	Source                  string  `json:"source"`
	DisplayName             string  `json:"display_name"`
	DisplayNotes            string  `json:"display_notes"`
	AccountDisplayName      string  `json:"account_display_name"`
	Tags                    []Tag   `json:"tags"`
}

Transaction is a single LM transaction.

func (*Transaction) ParsedAmount 

func (t *Transaction) ParsedAmount() (*money.Money, error)

ParsedAmount converts the transaction's amount and currency into a money.Money object. This provides a convenient way to work with the transaction amount using the go-money library's currency handling capabilities. Returns an error if the amount cannot be parsed.

type TransactionFilters 

type TransactionFilters struct {
	TagID           *int64  `json:"tag_id"`
	RecurringID     *int64  `json:"recurring_id"`
	PlaidAccountID  *int64  `json:"plaid_account_id"`
	CategoryID      *int64  `json:"category_id"`
	AssetID         *int64  `json:"asset_id"`
	Offset          *int64  `json:"offset"`
	Limit           *int64  `json:"limit"`
	StartDate       *string `json:"start_date" validate:"omitempty,datetime=2006-01-02"`
	EndDate         *string `json:"end_date" validate:"omitempty,datetime=2006-01-02"`
	DebitAsNegative *bool   `json:"debit_as_negative"`
}

TransactionFilters are options to pass into the request for transactions.

func (*TransactionFilters) ToMap 

func (r *TransactionFilters) ToMap() (map[string]string, error)

ToMap converts the filters to a string map to be sent with the request as GET parameters. If the field is nil, it will not be included in the map. This method provides query parameters for the Lunch Money API in the expected format. The function handles conversion of various data types to strings suitable for URL parameters.

type TransactionsResponse 

type TransactionsResponse struct {
	Transactions []*Transaction `json:"transactions"`
}

TransactionsResponse is the response we get from requesting transactions.

type UpdateAsset added in v0.5.0 

type UpdateAsset struct {
	TypeName             *string `json:"type_name,omitempty"`
	SubtypeName          *string `json:"subtype_name,omitempty"`
	Name                 *string `json:"name,omitempty"`
	DisplayName          *string `json:"display_name,omitempty"`
	Balance              *string `json:"balance,omitempty"`
	BalanceAsOf          *string `json:"balance_as_of,omitempty"`
	Currency             *string `json:"currency,omitempty"`
	InstitutionName      *string `json:"institution_name,omitempty"`
	ClosedOn             *string `json:"closed_on,omitempty"`
	ExcludedTransactions *bool   `json:"excluded_transactions,omitempty"`
}

UpdateAsset contains the fields that can be updated for an existing asset. Only non-nil fields will be sent in the update request.

type UpdateRequest added in v0.4.0 

type UpdateRequest struct {
	Transaction *UpdateTransaction `json:"transaction"`
}

UpdateRequest is the request body used to update a transaction in the Lunch Money API. It wraps an UpdateTransaction object in the format expected by the API.

type UpdateTransaction added in v0.4.0 

type UpdateTransaction struct {
	Date        *string `json:"date,omitempty" validate:"omitnil,datetime=2006-01-02"`
	CategoryID  *int    `json:"category_id,omitempty"`
	Payee       *string `json:"payee,omitempty"`
	Currency    *string `json:"currency,omitempty"`
	AssetID     *int    `json:"asset_id,omitempty"`
	RecurringID *int    `json:"recurring_id,omitempty"`
	Notes       *string `json:"notes,omitempty"`
	Status      *string `json:"status,omitempty" validate:"omitnil,oneof=cleared uncleared"`
	ExternalID  *string `json:"external_id,omitempty"`
}

UpdateTransaction contains fields that can be updated for an existing transaction. All fields are optional, and only non-nil fields will be sent in the update request. This provides a flexible way to update specific fields without needing to include unchanged values.

type UpdateTransactionResp added in v0.4.0 

type UpdateTransactionResp struct {
	Updated bool  `json:"updated"`
	Split   []int `json:"split"`
}

UpdateTransactionResp is the response received from the API when updating a transaction. It indicates whether the update was successful and includes any split transaction IDs if the transaction was split during the update process.

type User added in v0.4.0 

type User struct {
	UserName        string `json:"user_name"`
	UserEmail       string `json:"user_email"`
	UserID          int    `json:"user_id"`
	AccountID       int    `json:"account_id"`
	BudgetName      string `json:"budget_name"`
	PrimaryCurrency string `json:"primary_currency"`
	APIKeyLabel     string `json:"api_key_label"`
}

User represents the authenticated user's profile information from the Lunch Money API.

Source Files

View all Source files

Directories

Path Synopsis
examples
accounts command
assets command
budgets command
categories command
recurring command
tags command
transaction command
transactions command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.