ynab

package module
v1.7.0 Latest Latest
Warning

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

Go to latest
Published: May 22, 2026 License: MIT Imports: 10 Imported by: 0

README

ynab-go

A Go client for the YNAB (You Need a Budget) API. All API endpoints and response fields are supported.

YNAB now refers to budgets as plans in the API. New code should use Client.Plans, Client.GetPlans, and the Plan types. The old Budget names remain as compatibility aliases where practical.

Age of Money

This command will print out more information about how old your money is.

Set YNAB_TOKEN to your API token in your environment. You can find your token on the Settings page: https://app.youneedabudget.com/settings

Finally, run the binary:

go run ./cmd/ynab-age-of-money --budget='Personal Budget'

The output will look something like this:

 70 earned: 2019-02-07 spent: 2019-04-18     $25.00 Cash Exxon Mobil
 71 earned: 2019-02-07 spent: 2019-04-19      $3.00 Cash Shaska Cafe
 71 earned: 2019-02-07 spent: 2019-04-19      $2.00 Cash Shaska Cafe
 72 earned: 2019-02-07 spent: 2019-04-20      $4.00 Cash Aces
 75 earned: 2019-02-07 spent: 2019-04-23      $6.00 Cash Corner Store
 75 earned: 2019-02-07 spent: 2019-04-23      $3.00 Cash Lava Java
 76 earned: 2019-02-07 spent: 2019-04-24    $123.45 Shared Checking Transfer : Credit Card 1
 76 earned: 2019-02-07 spent: 2019-04-24    $456.78 Shared Checking Transfer : Credit Card 2
 77 earned: 2019-02-07 spent: 2019-04-25      $3.00 Cash Lava Java
 77 earned: 2019-02-07 spent: 2019-04-25      $2.00 Cash Corner Store

upcoming spending thresholds (and age if you spent today):
 78 2019-02-07   $1000.00 Personal Checking Employer 1
 74 2019-02-11   $2000.00 Shared Checking Employer 2
 73 2019-02-12   $2020.00 Personal Checking Venmo
 71 2019-02-14   $3020.00 Shared Checking Employer 2
 66 2019-02-19   $3060.00 Cash Laura Cash
 60 2019-02-25   $3065.00 Shared Checking Bank Interest
 60 2019-02-25   $3070.00 Personal Checking Bank Interest

The number in the far left hand column is the age of money, in days, for each transaction. The thresholds show the upcoming age of money when you spend it.

The flags are:

  -budget-name string
    	Name of the budget to compute AOM for
  -debug
    	Enable debug
  -file string
    	Filename to read txns from

You will need to specify --budget-name if you have more than one budget. --debug provides more information about all of the buckets you have as well as all of the accounts you have. --file is useful if you are making a lot of requests - save the JSON transaction data to a file and load it from there.

Errata

YNAB uses a weighted average to calculate age of money for a single transaction if it spans multiple buckets. I choose the date of the bucket the last penny was taken out of, so the numbers may be slightly lower here than in your dashboard.

YNAB averages the last ten transactions to get the Age of Money. I print accurate results for each transaction in your account.

Largest Inputs and Outputs

The ynab-largest-inputs-outputs command finds the largest inputs and outputs to your Net Worth, optionally filtered by a month argument. Any income or outflows that come into either your budget accounts or your tracking accounts will appear here. One exception is that credit card spending is accounted at the time of payment, not at the time the money is spent.

Pass the --month flag to filter by a given month. The flag accepts arguments in the form of 'Jan 2006', e.g. --month='Aug 2019'.

OpenAPI Spec

The YNAB OpenAPI spec is available at https://api.ynab.com/papi/open_api_spec.yaml. A local copy is kept at open_api_spec.yaml. Run make update-spec to refresh it.

Disclaimer

I spot checked the results against my account, and they appeared to be accurate. They may not be correct for your account. This software is provided "as is" and I am not liable for any claim or damages arising from how you use this library.

License

MIT

Support

You can hire me: https://burke.services

I maintain this software in my free time. Donations free up time to make improvements to the library, and respond to bug reports. You can send donations via Paypal's "Send Money" feature to kev@inburke.com. Donations are not tax deductible in the USA.

Documentation

Index

Examples

Constants

View Source
const Version = "1.7.0"

Variables

This section is empty.

Functions

This section is empty.

Types

type Account

type Account struct {
	ID                        string
	Name                      string
	Type                      string
	OnBudget                  bool `json:"on_budget"` // Whether this account is on budget or not
	Closed                    bool // Whether this account is closed or not
	Note                      string
	Balance                   int64   // The current balance of the account in milliunits format
	ClearedBalance            int64   `json:"cleared_balance"`   // The current cleared balance of the account in milliunits format
	UnclearedBalance          int64   `json:"uncleared_balance"` // The current uncleared balance of the account in milliunits format
	BalanceFormatted          string  `json:"balance_formatted"`
	BalanceCurrency           float64 `json:"balance_currency"`
	ClearedBalanceFormatted   string  `json:"cleared_balance_formatted"`
	ClearedBalanceCurrency    float64 `json:"cleared_balance_currency"`
	UnclearedBalanceFormatted string  `json:"uncleared_balance_formatted"`
	UnclearedBalanceCurrency  float64 `json:"uncleared_balance_currency"`
	StartingBalance           int64   `json:"starting_balance"`
	Deleted                   bool
	TransferPayeeID           types.NullString `json:"transfer_payee_id"`      // The payee id which should be used when transferring to this account
	DirectImportLinked        bool             `json:"direct_import_linked"`   // Whether or not the account is linked to a financial institution for automatic transaction import
	DirectImportInError       bool             `json:"direct_import_in_error"` // If an account linked to a financial institution and the linked connection is not in a healthy state, this will be true
	LastReconciledAt          types.NullString `json:"last_reconciled_at"`     // A date/time specifying when the account was last reconciled
	DebtInterestRates         map[string]int64 `json:"debt_interest_rates"`    // Loan account periodic interest rate values
	DebtMinimumPayments       map[string]int64 `json:"debt_minimum_payments"`  // Loan account periodic minimum payment values
	DebtEscrowAmounts         map[string]int64 `json:"debt_escrow_amounts"`    // Loan account periodic escrow amount values
}

func (Account) CashBacked

func (a Account) CashBacked() bool

type AccountListResponse

type AccountListResponse struct {
	Data AccountListWrapper `json:"data"`
}

type AccountListWrapper

type AccountListWrapper struct {
	Accounts        []*Account `json:"accounts"`
	ServerKnowledge int64      `json:"server_knowledge"`
}

type AccountResponse added in v1.5.0

type AccountResponse struct {
	Data struct {
		Account *Account `json:"account"`
	} `json:"data"`
}

AccountResponse wraps a single account response.

type Budget

type Budget = Plan

Budget is deprecated. Use Plan.

type BudgetDetail added in v1.5.0

type BudgetDetail = PlanDetail

BudgetDetail is deprecated. Use PlanDetail.

type BudgetDetailResponse added in v1.5.0

type BudgetDetailResponse struct {
	Data struct {
		Budget          *BudgetDetail `json:"plan"`
		ServerKnowledge int64         `json:"server_knowledge"`
	} `json:"data"`
}

BudgetDetailResponse wraps the plan detail response with the old field name.

type BudgetListResponse

type BudgetListResponse struct {
	Data BudgetListWrapper `json:"data"`
}

type BudgetListWrapper

type BudgetListWrapper struct {
	Budgets       []*Budget `json:"plans"`
	DefaultBudget *Budget   `json:"default_plan"`
}

type BudgetService

type BudgetService = PlanService

BudgetService is deprecated. Use PlanService.

type BudgetSettings added in v1.5.0

type BudgetSettings = PlanSettings

BudgetSettings is deprecated. Use PlanSettings.

type BudgetSettingsResponse added in v1.5.0

type BudgetSettingsResponse = PlanSettingsResponse

BudgetSettingsResponse is deprecated. Use PlanSettingsResponse.

type Category

type Category struct {
	ID                      string
	Name                    string
	CategoryGroupID         string           `json:"category_group_id"`
	CategoryGroupName       string           `json:"category_group_name"` // The name of the category group
	OriginalCategoryGroupID types.NullString `json:"original_category_group_id"`
	Note                    string           `json:"note"`
	Hidden                  bool
	Internal                bool
	Deleted                 bool
	Budgeted                int64 // Assigned (budgeted) amount in milliunits format
	Activity                int64 // Activity amount in milliunits format
	Balance                 int64 // Available balance in milliunits format

	BudgetedFormatted string  `json:"budgeted_formatted"`
	BudgetedCurrency  float64 `json:"budgeted_currency"`
	ActivityFormatted string  `json:"activity_formatted"`
	ActivityCurrency  float64 `json:"activity_currency"`
	BalanceFormatted  string  `json:"balance_formatted"`
	BalanceCurrency   float64 `json:"balance_currency"`

	GoalType                   types.NullString `json:"goal_type"`                     // The type of goal, or null. TB=Target Category Balance, TBD=Target Category Balance by Date, MF=Monthly Funding, NEED=Plan Your Spending, DEBT=Debt Payoff
	GoalTarget                 *int64           `json:"goal_target"`                   // The goal target amount in milliunits
	GoalTargetFormatted        types.NullString `json:"goal_target_formatted"`         // The goal target amount formatted in the plan's currency format
	GoalTargetCurrency         *float64         `json:"goal_target_currency"`          // The goal target amount as a decimal currency amount
	GoalPercentageComplete     *int32           `json:"goal_percentage_complete"`      // The percentage completed of the goal
	GoalMonthsToBudget         *int32           `json:"goal_months_to_budget"`         // The number of months remaining until the goal is completed
	GoalUnderFunded            *int64           `json:"goal_under_funded"`             // The amount of funding still needed in milliunits
	GoalUnderFundedFormatted   types.NullString `json:"goal_under_funded_formatted"`   // The goal underfunded amount formatted in the plan's currency format
	GoalUnderFundedCurrency    *float64         `json:"goal_under_funded_currency"`    // The goal underfunded amount as a decimal currency amount
	GoalOverallFunded          *int64           `json:"goal_overall_funded"`           // The total amount funded towards the goal in milliunits
	GoalOverallFundedFormatted types.NullString `json:"goal_overall_funded_formatted"` // The total amount funded towards the goal formatted in the plan's currency format
	GoalOverallFundedCurrency  *float64         `json:"goal_overall_funded_currency"`  // The total amount funded towards the goal as a decimal currency amount
	GoalOverallLeft            *int64           `json:"goal_overall_left"`             // The amount still left to fund the goal in milliunits
	GoalOverallLeftFormatted   types.NullString `json:"goal_overall_left_formatted"`   // The amount still left to fund the goal formatted in the plan's currency format
	GoalOverallLeftCurrency    *float64         `json:"goal_overall_left_currency"`    // The amount still left to fund the goal as a decimal currency amount
	GoalNeedsWholeAmount       *bool            `json:"goal_needs_whole_amount"`       // For NEED goals: true=Set Aside, false=Refill. Null for other goal types
	GoalDay                    *int32           `json:"goal_day"`                      // Day offset for the goal's due date
	GoalCadence                *int32           `json:"goal_cadence"`                  // The goal cadence (0-14)
	GoalCadenceFrequency       *int32           `json:"goal_cadence_frequency"`        // The goal cadence frequency
	GoalCreationMonth          types.NullString `json:"goal_creation_month"`           // The month a goal was created
	GoalTargetMonth            types.NullString `json:"goal_target_month"`             // The original target month for the goal to be completed
	GoalTargetDate             types.NullString `json:"goal_target_date"`              // The target date for the goal to be completed
	GoalSnoozedAt              types.NullString `json:"goal_snoozed_at"`               // The date/time the goal was snoozed
}

type CategoryData added in v1.5.0

type CategoryData struct {
	Category *Category `json:"category"`
}

CategoryData contains the category.

type CategoryGroup

type CategoryGroup struct {
	ID         string
	Name       string
	Hidden     bool
	Internal   bool
	Deleted    bool
	Categories []*Category
}

type CategoryListResponse

type CategoryListResponse struct {
	Data CategoryListWrapper `json:"data"`
}

type CategoryListWrapper

type CategoryListWrapper struct {
	CategoryGroups  []*CategoryGroup `json:"category_groups"`
	ServerKnowledge int64            `json:"server_knowledge"`
}

type CategoryResponse added in v1.5.0

type CategoryResponse struct {
	Data CategoryData `json:"data"`
}

CategoryResponse is the response from getting a single category.

type ClearedStatus added in v1.1.0

type ClearedStatus string

ClearedStatus represents the cleared status of a transaction

const (
	ClearedStatusCleared    ClearedStatus = "cleared"
	ClearedStatusUncleared  ClearedStatus = "uncleared"
	ClearedStatusReconciled ClearedStatus = "reconciled"
)

type Client

type Client struct {
	*restclient.Client

	Plans func(planID string) *PlanService
	// Budgets is deprecated. Use Plans.
	Budgets func(budgetID string) *PlanService
	// contains filtered or unexported fields
}

func NewClient

func NewClient(token string) *Client

func (*Client) GetBudgets added in v1.0.0

func (c *Client) GetBudgets(ctx context.Context, data url.Values) (*BudgetListResponse, error)

GetBudgets is deprecated. Use GetPlans.

func (*Client) GetPlans added in v1.7.0

func (c *Client) GetPlans(ctx context.Context, data url.Values) (*PlanListResponse, error)

func (*Client) GetUser added in v1.5.0

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

GetUser returns the authenticated user.

func (*Client) GetUserAgent added in v1.3.0

func (c *Client) GetUserAgent() string

GetUserAgent returns the current User-Agent string that will be sent with requests

func (*Client) MakeRequest added in v0.6.0

func (c *Client) MakeRequest(ctx context.Context, method string, pathPart string, data url.Values, reqBody any, v any) error

func (*Client) NewRequestWithContext

func (c *Client) NewRequestWithContext(ctx context.Context, method, path string, body io.Reader) (*http.Request, error)

func (*Client) PutResource added in v0.6.0

func (c *Client) PutResource(ctx context.Context, pathPart string, sid string, req any, resp any) error

func (*Client) SetUserAgent added in v1.3.0

func (c *Client) SetUserAgent(userAgent string)

SetUserAgent sets a custom User-Agent string for requests

type CreateAccountRequest added in v1.5.0

type CreateAccountRequest struct {
	Account *SaveAccount `json:"account"`
}

CreateAccountRequest is the request body for creating an account.

type CreateCategoryGroupRequest added in v1.7.0

type CreateCategoryGroupRequest struct {
	CategoryGroup *SaveCategoryGroup `json:"category_group"`
}

CreateCategoryGroupRequest is the request body for creating a category group.

type CreateCategoryRequest added in v1.7.0

type CreateCategoryRequest struct {
	Category *SaveCategory `json:"category"`
}

CreateCategoryRequest is the request body for creating a category.

type CreateScheduledTransactionRequest added in v1.5.0

type CreateScheduledTransactionRequest struct {
	ScheduledTransaction *SaveScheduledTransaction `json:"scheduled_transaction"`
}

CreateScheduledTransactionRequest is the request body for creating a scheduled transaction.

type CreateTransactionData added in v1.1.0

type CreateTransactionData struct {
	TransactionIDs  []string     `json:"transaction_ids"`
	Transaction     *Transaction `json:"transaction,omitempty"`
	ServerKnowledge int64        `json:"server_knowledge"`
}

type CreateTransactionRequest added in v1.1.0

type CreateTransactionRequest struct {
	Transaction *NewTransaction `json:"transaction"`
}

type CreateTransactionResponse added in v1.1.0

type CreateTransactionResponse struct {
	Data CreateTransactionData `json:"data"`
}

type CurrencyFormat added in v1.5.0

type CurrencyFormat struct {
	ISOCode          string `json:"iso_code"`
	ExampleFormat    string `json:"example_format"`
	DecimalDigits    int    `json:"decimal_digits"`
	DecimalSeparator string `json:"decimal_separator"`
	SymbolFirst      bool   `json:"symbol_first"`
	GroupSeparator   string `json:"group_separator"`
	CurrencySymbol   string `json:"currency_symbol"`
	DisplaySymbol    bool   `json:"display_symbol"`
}

CurrencyFormat represents the currency format setting for a plan.

type Date

type Date time.Time

func (Date) GoString

func (t Date) GoString() string

func (Date) MarshalJSON added in v0.5.0

func (t Date) MarshalJSON() ([]byte, error)

func (Date) String

func (t Date) String() string

func (*Date) UnmarshalJSON

func (t *Date) UnmarshalJSON(b []byte) error

type DateFormat added in v1.5.0

type DateFormat struct {
	Format string `json:"format"`
}

DateFormat represents the date format setting for a plan.

type Error added in v1.4.0

type Error struct {
	Message string
}

Error represents an error from the YNAB API or this client library.

func (*Error) Error added in v1.4.0

func (e *Error) Error() string

type FlagColor added in v0.7.0

type FlagColor string

FlagColor represents the available flag colors for transactions

const (
	FlagColorRed    FlagColor = "red"
	FlagColorOrange FlagColor = "orange"
	FlagColorYellow FlagColor = "yellow"
	FlagColorGreen  FlagColor = "green"
	FlagColorBlue   FlagColor = "blue"
	FlagColorPurple FlagColor = "purple"
	FlagColorEmpty  FlagColor = ""
)

func (FlagColor) MarshalJSON added in v0.7.0

func (fc FlagColor) MarshalJSON() ([]byte, error)

func (*FlagColor) UnmarshalJSON added in v0.7.0

func (fc *FlagColor) UnmarshalJSON(b []byte) error

type HybridTransaction added in v1.5.0

type HybridTransaction struct {
	ID                      string           `json:"id"`
	Date                    Date             `json:"date"`   // The transaction date in ISO format (e.g. 2016-12-01)
	Amount                  int64            `json:"amount"` // The transaction amount in milliunits format
	AmountFormatted         string           `json:"amount_formatted"`
	AmountCurrency          float64          `json:"amount_currency"`
	Memo                    string           `json:"memo"`
	Cleared                 ClearedStatus    `json:"cleared"`
	Approved                bool             `json:"approved"` // Whether or not the transaction is approved
	FlagColor               FlagColor        `json:"flag_color"`
	FlagName                types.NullString `json:"flag_name"` // The customized name of a transaction flag
	AccountID               string           `json:"account_id"`
	AccountName             string           `json:"account_name"`
	PayeeID                 types.NullString `json:"payee_id"`
	PayeeName               string           `json:"payee_name"`
	CategoryID              types.NullString `json:"category_id"`
	CategoryName            types.NullString `json:"category_name"`              // If a split transaction, this will be 'Split'.
	TransferAccountID       types.NullString `json:"transfer_account_id"`        // If a transfer transaction, the account to which it transfers
	TransferTransactionID   types.NullString `json:"transfer_transaction_id"`    // If a transfer transaction, the id of transaction on the other side of the transfer
	MatchedTransactionID    types.NullString `json:"matched_transaction_id"`     // If transaction is matched, the id of the matched transaction
	ImportID                types.NullString `json:"import_id"`                  // If the transaction was imported, a unique (by account) import identifier
	ImportPayeeName         types.NullString `json:"import_payee_name"`          // If the transaction was imported, the payee name that was used when importing and before applying any payee rename rules
	ImportPayeeNameOriginal types.NullString `json:"import_payee_name_original"` // If the transaction was imported, the original payee name as it appeared on the statement
	DebtTransactionType     types.NullString `json:"debt_transaction_type"`      // If a debt/loan account transaction, the type of transaction
	Deleted                 bool             `json:"deleted"`
	Type                    string           `json:"type"`                  // Whether the hybrid transaction represents a regular transaction or a subtransaction
	ParentTransactionID     types.NullString `json:"parent_transaction_id"` // For subtransaction types, this is the id of the parent transaction. For transaction types, this will be null.
	Subtransactions         []Transaction    `json:"subtransactions"`
}

HybridTransaction represents a transaction that may be either a regular transaction or a subtransaction, returned by payee/category/month transaction endpoints.

type HybridTransactionListResponse added in v1.5.0

type HybridTransactionListResponse struct {
	Data struct {
		Transactions    []*HybridTransaction `json:"transactions"`
		ServerKnowledge int64                `json:"server_knowledge"`
	} `json:"data"`
}

HybridTransactionListResponse wraps the hybrid transaction list response.

type MoneyMovement added in v1.7.0

type MoneyMovement struct {
	ID                   string           `json:"id"`
	Month                NullDate         `json:"month"`
	MovedAt              types.NullString `json:"moved_at"`
	Note                 types.NullString `json:"note"`
	MoneyMovementGroupID types.NullString `json:"money_movement_group_id"`
	PerformedByUserID    types.NullString `json:"performed_by_user_id"`
	FromCategoryID       types.NullString `json:"from_category_id"`
	ToCategoryID         types.NullString `json:"to_category_id"`
	Amount               int64            `json:"amount"`
	AmountFormatted      string           `json:"amount_formatted"`
	AmountCurrency       float64          `json:"amount_currency"`
}

MoneyMovement represents a category money movement in a plan.

type MoneyMovementGroup added in v1.7.0

type MoneyMovementGroup struct {
	ID                string           `json:"id"`
	GroupCreatedAt    string           `json:"group_created_at"`
	Month             Date             `json:"month"`
	Note              types.NullString `json:"note"`
	PerformedByUserID types.NullString `json:"performed_by_user_id"`
}

MoneyMovementGroup represents a group of money movements in a plan.

type MoneyMovementGroupsResponse added in v1.7.0

type MoneyMovementGroupsResponse struct {
	Data struct {
		MoneyMovementGroups []*MoneyMovementGroup `json:"money_movement_groups"`
		ServerKnowledge     int64                 `json:"server_knowledge"`
	} `json:"data"`
}

MoneyMovementGroupsResponse wraps the money movement groups list response.

type MoneyMovementsResponse added in v1.7.0

type MoneyMovementsResponse struct {
	Data struct {
		MoneyMovements  []*MoneyMovement `json:"money_movements"`
		ServerKnowledge int64            `json:"server_knowledge"`
	} `json:"data"`
}

MoneyMovementsResponse wraps the money movements list response.

type MonthDetail added in v1.5.0

type MonthDetail struct {
	Month                 string      `json:"month"`
	Note                  string      `json:"note"`
	Income                int64       `json:"income"` // The total amount of transactions categorized to 'Inflow: Ready to Assign' in the month
	IncomeFormatted       string      `json:"income_formatted"`
	IncomeCurrency        float64     `json:"income_currency"`
	Budgeted              int64       `json:"budgeted"` // The total amount assigned in the month
	BudgetedFormatted     string      `json:"budgeted_formatted"`
	BudgetedCurrency      float64     `json:"budgeted_currency"`
	Activity              int64       `json:"activity"` // The total amount of transactions in the month, excluding those categorized to 'Inflow: Ready to Assign'
	ActivityFormatted     string      `json:"activity_formatted"`
	ActivityCurrency      float64     `json:"activity_currency"`
	ToBeBudget            int64       `json:"to_be_budgeted"` // The available amount for 'Ready to Assign'
	ToBeBudgetedFormatted string      `json:"to_be_budgeted_formatted"`
	ToBeBudgetedCurrency  float64     `json:"to_be_budgeted_currency"`
	AgeOfMoney            int         `json:"age_of_money"` // The Age of Money as of the month
	Deleted               bool        `json:"deleted"`
	Categories            []*Category `json:"categories"` // Amounts (budgeted, activity, balance, etc.) are specific to this month.
}

MonthDetail represents a plan month with all its categories.

type MonthDetailResponse added in v1.5.0

type MonthDetailResponse struct {
	Data struct {
		Month *MonthDetail `json:"month"`
	} `json:"data"`
}

MonthDetailResponse wraps a single month detail response.

type MonthSummary added in v1.5.0

type MonthSummary struct {
	Month                 string  `json:"month"`
	Note                  string  `json:"note"`
	Income                int64   `json:"income"` // The total amount of transactions categorized to 'Inflow: Ready to Assign' in the month
	IncomeFormatted       string  `json:"income_formatted"`
	IncomeCurrency        float64 `json:"income_currency"`
	Budgeted              int64   `json:"budgeted"` // The total amount assigned in the month
	BudgetedFormatted     string  `json:"budgeted_formatted"`
	BudgetedCurrency      float64 `json:"budgeted_currency"`
	Activity              int64   `json:"activity"` // The total amount of transactions in the month, excluding those categorized to 'Inflow: Ready to Assign'
	ActivityFormatted     string  `json:"activity_formatted"`
	ActivityCurrency      float64 `json:"activity_currency"`
	ToBeBudgeted          int64   `json:"to_be_budgeted"` // The available amount for 'Ready to Assign'
	ToBeBudgetedFormatted string  `json:"to_be_budgeted_formatted"`
	ToBeBudgetedCurrency  float64 `json:"to_be_budgeted_currency"`
	AgeOfMoney            *int    `json:"age_of_money"` // The Age of Money as of the month
	Deleted               bool    `json:"deleted"`
}

MonthSummary represents a plan month summary without category details.

type MonthSummaryListResponse added in v1.5.0

type MonthSummaryListResponse struct {
	Data struct {
		Months          []*MonthSummary `json:"months"`
		ServerKnowledge int64           `json:"server_knowledge"`
	} `json:"data"`
}

MonthSummaryListResponse wraps the month summary list response.

type NewSubTransaction added in v1.1.0

type NewSubTransaction struct {
	Amount     int64            `json:"amount"` // The subtransaction amount in milliunits format
	PayeeID    types.NullString `json:"payee_id"`
	PayeeName  types.NullString `json:"payee_name"`  // If provided and payee_id is null, used to resolve the payee by matching rename rule, same name, or creation of a new payee.
	CategoryID types.NullString `json:"category_id"` // Credit Card Payment categories are not permitted.
	Memo       types.NullString `json:"memo"`
}

type NewTransaction added in v1.1.0

type NewTransaction struct {
	AccountID  string           `json:"account_id"`
	Date       Date             `json:"date"`   // The transaction date in ISO format (e.g. 2016-12-01). Future dates (scheduled transactions) are not permitted.
	Amount     int64            `json:"amount"` // The transaction amount in milliunits format
	PayeeID    types.NullString `json:"payee_id"`
	PayeeName  types.NullString `json:"payee_name"`  // If provided and payee_id is null, used to resolve the payee by matching rename rule, same name, or creation of a new payee.
	CategoryID types.NullString `json:"category_id"` // To configure a split, specify null and provide a subtransactions array. Credit Card Payment categories are not permitted.
	Memo       types.NullString `json:"memo"`
	Cleared    ClearedStatus    `json:"cleared,omitempty"`
	Approved   bool             `json:"approved"` // Whether or not the transaction is approved. If not supplied, transaction will be unapproved by default.
	FlagColor  FlagColor        `json:"flag_color,omitempty"`
	// An array of subtransactions to configure a transaction as a split. Updating subtransactions on an existing split transaction is not supported.
	Subtransactions   []*NewSubTransaction `json:"subtransactions,omitempty"`
	ImportID          types.NullString     `json:"import_id"`
	TransferAccountID types.NullString     `json:"transfer_account_id"`
}

func NewTransferTransaction added in v1.4.0

func NewTransferTransaction(sourceAccountID string, targetAccount *Account, amount int64, date Date) (*NewTransaction, error)

NewTransferTransaction creates a NewTransaction configured as a transfer between accounts. The sourceAccountID is where the transaction will appear (the "from" account). The targetAccount must have a valid TransferPayeeID (the "to" account). A positive amount transfers money into the source account; a negative amount transfers out.

Example
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kevinburke/ynab-go"
)

func main() {
	client := ynab.NewClient("your-api-token")

	// First, get the accounts to find the transfer_payee_id
	accounts, err := client.Plans("plan-id").Accounts(context.Background(), nil)
	if err != nil {
		log.Fatal(err)
	}

	// Find the source and target accounts
	var checkingAccount, savingsAccount *ynab.Account
	for _, acct := range accounts.Data.Accounts {
		switch acct.Name {
		case "Checking":
			checkingAccount = acct
		case "Savings":
			savingsAccount = acct
		}
	}

	if checkingAccount == nil || savingsAccount == nil {
		log.Fatal("could not find accounts")
	}

	// Create a transfer from Checking to Savings
	// Negative amount means money leaves the source account (Checking)
	txn, err := ynab.NewTransferTransaction(
		checkingAccount.ID, // source account
		savingsAccount,     // target account (has TransferPayeeID)
		-100000,            // -$100.00 transfer out of Checking
		ynab.Date(time.Date(2023, 6, 15, 0, 0, 0, 0, time.Local)),
	)
	if err != nil {
		log.Fatal(err)
	}

	resp, err := client.Plans("plan-id").CreateTransaction(
		context.Background(),
		&ynab.CreateTransactionRequest{Transaction: txn},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Created transfer: %s\n", resp.Data.Transaction.ID)
	fmt.Printf("Transfer to account: %s\n", resp.Data.Transaction.TransferAccountID.String)
}

type NullDate added in v0.7.0

type NullDate struct {
	Valid bool
	Date  Date
}

A NullDate is a Date that may be null.

func (NullDate) MarshalJSON added in v0.7.0

func (nt NullDate) MarshalJSON() ([]byte, error)

func (*NullDate) UnmarshalJSON added in v0.7.0

func (nt *NullDate) UnmarshalJSON(b []byte) error

type Payee added in v1.5.0

type Payee struct {
	ID                string           `json:"id"`
	Name              string           `json:"name"`
	TransferAccountID types.NullString `json:"transfer_account_id"` // If a transfer payee, the account_id to which this payee transfers to
	Deleted           bool             `json:"deleted"`
}

Payee represents a YNAB payee.

type PayeeListResponse added in v1.5.0

type PayeeListResponse struct {
	Data struct {
		Payees          []*Payee `json:"payees"`
		ServerKnowledge int64    `json:"server_knowledge"`
	} `json:"data"`
}

PayeeListResponse wraps the payee list response.

type PayeeLocation added in v1.5.0

type PayeeLocation struct {
	ID        string `json:"id"`
	PayeeID   string `json:"payee_id"`
	Latitude  string `json:"latitude"`
	Longitude string `json:"longitude"`
	Deleted   bool   `json:"deleted"`
}

PayeeLocation represents a payee's geographic location.

type PayeeLocationListResponse added in v1.5.0

type PayeeLocationListResponse struct {
	Data struct {
		PayeeLocations []*PayeeLocation `json:"payee_locations"`
	} `json:"data"`
}

PayeeLocationListResponse wraps the payee location list response.

type PayeeLocationResponse added in v1.5.0

type PayeeLocationResponse struct {
	Data struct {
		PayeeLocation *PayeeLocation `json:"payee_location"`
	} `json:"data"`
}

PayeeLocationResponse wraps a single payee location response.

type PayeeResponse added in v1.5.0

type PayeeResponse struct {
	Data struct {
		Payee *Payee `json:"payee"`
	} `json:"data"`
}

PayeeResponse wraps a single payee response.

type Plan added in v1.7.0

type Plan struct {
	ID             string     `json:"id"`
	Name           string     `json:"name"`
	LastModifiedOn string     `json:"last_modified_on"` // The last time any changes were made to the plan from either a web or mobile client
	FirstMonth     string     `json:"first_month"`      // The earliest plan month
	LastMonth      string     `json:"last_month"`       // The latest plan month
	DateFormat     any        `json:"date_format"`
	CurrencyFormat any        `json:"currency_format"`
	Accounts       []*Account `json:"accounts,omitempty"`
}

type PlanDetail added in v1.7.0

type PlanDetail struct {
	ID                       string                  `json:"id"`
	Name                     string                  `json:"name"`
	LastModifiedOn           string                  `json:"last_modified_on"` // The last time any changes were made to the plan from either a web or mobile client
	FirstMonth               string                  `json:"first_month"`      // The earliest plan month
	LastMonth                string                  `json:"last_month"`       // The latest plan month
	DateFormat               any                     `json:"date_format"`
	CurrencyFormat           any                     `json:"currency_format"`
	Accounts                 []*Account              `json:"accounts"`
	Payees                   []*Payee                `json:"payees"`
	PayeeLocations           []*PayeeLocation        `json:"payee_locations"`
	CategoryGroups           []*CategoryGroup        `json:"category_groups"`
	Categories               []*Category             `json:"categories"`
	Months                   []*MonthDetail          `json:"months"`
	Transactions             []*Transaction          `json:"transactions"`
	Subtransactions          []*Transaction          `json:"subtransactions"`
	ScheduledTransactions    []*ScheduledTransaction `json:"scheduled_transactions"`
	ScheduledSubtransactions []*ScheduledTransaction `json:"scheduled_subtransactions"`
}

PlanDetail represents a full plan export with all related entities.

type PlanDetailResponse added in v1.7.0

type PlanDetailResponse struct {
	Data struct {
		Plan            *PlanDetail `json:"plan"`
		ServerKnowledge int64       `json:"server_knowledge"`
	} `json:"data"`
}

PlanDetailResponse wraps the plan detail response.

type PlanListResponse added in v1.7.0

type PlanListResponse struct {
	Data PlanListWrapper `json:"data"`
}

type PlanListWrapper added in v1.7.0

type PlanListWrapper struct {
	Plans       []*Plan `json:"plans"`
	DefaultPlan *Plan   `json:"default_plan"`
}

type PlanService added in v1.7.0

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

func (*PlanService) AccountTransactions added in v1.7.0

func (b *PlanService) AccountTransactions(ctx context.Context, accountID string, data url.Values) (*TransactionListResponse, error)

AccountTransactions returns the transactions for a specific account.

func (*PlanService) Accounts added in v1.7.0

func (b *PlanService) Accounts(ctx context.Context, data url.Values) (*AccountListResponse, error)

func (*PlanService) Categories added in v1.7.0

func (b *PlanService) Categories(ctx context.Context, data url.Values) (*CategoryListResponse, error)

func (*PlanService) CategoryTransactions added in v1.7.0

func (b *PlanService) CategoryTransactions(ctx context.Context, categoryID string, data url.Values) (*HybridTransactionListResponse, error)

CategoryTransactions returns the transactions for a specific category.

func (*PlanService) CreateAccount added in v1.7.0

func (b *PlanService) CreateAccount(ctx context.Context, req *CreateAccountRequest) (*AccountResponse, error)

CreateAccount creates a new account in this plan.

func (*PlanService) CreateCategory added in v1.7.0

CreateCategory creates a category in this plan.

func (*PlanService) CreateCategoryGroup added in v1.7.0

CreateCategoryGroup creates a category group in this plan.

func (*PlanService) CreateScheduledTransaction added in v1.7.0

CreateScheduledTransaction creates a new scheduled transaction.

func (*PlanService) CreateTransaction added in v1.7.0

Example
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kevinburke/go-types"
	"github.com/kevinburke/ynab-go"
)

func main() {
	client := ynab.NewClient("your-api-token")

	// Create a normal expense transaction
	txn := &ynab.NewTransaction{
		AccountID:  "checking-account-id",
		Date:       ynab.Date(time.Date(2023, 6, 15, 0, 0, 0, 0, time.Local)),
		Amount:     -25000, // -$25.00 in milliunits
		PayeeName:  types.NullString{String: "Coffee Shop", Valid: true},
		CategoryID: types.NullString{String: "food-category-id", Valid: true},
		Memo:       types.NullString{String: "Morning coffee", Valid: true},
		Cleared:    ynab.ClearedStatusCleared,
		Approved:   true,
	}

	resp, err := client.Plans("plan-id").CreateTransaction(
		context.Background(),
		&ynab.CreateTransactionRequest{Transaction: txn},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Created transaction: %s\n", resp.Data.Transaction.ID)
}

func (*PlanService) DeleteScheduledTransaction added in v1.7.0

func (b *PlanService) DeleteScheduledTransaction(ctx context.Context, scheduledTransactionID string) (*ScheduledTransactionResponse, error)

DeleteScheduledTransaction deletes a scheduled transaction.

func (*PlanService) DeleteTransaction added in v1.7.0

func (b *PlanService) DeleteTransaction(ctx context.Context, transactionID string) (*TransactionResponse, error)

func (*PlanService) GetAccount added in v1.7.0

func (b *PlanService) GetAccount(ctx context.Context, accountID string) (*AccountResponse, error)

GetAccount returns a single account by ID.

func (*PlanService) GetBudget added in v1.7.0

func (b *PlanService) GetBudget(ctx context.Context) (*BudgetDetailResponse, error)

GetBudget is deprecated. Use GetPlan.

func (*PlanService) GetCategory added in v1.7.0

func (b *PlanService) GetCategory(ctx context.Context, categoryID string) (*CategoryResponse, error)

GetCategory returns a single category by ID.

func (*PlanService) GetMonth added in v1.7.0

func (b *PlanService) GetMonth(ctx context.Context, month string) (*MonthDetailResponse, error)

GetMonth returns a single plan month. The month should be in ISO format (e.g., "2024-01-01") or "current".

func (*PlanService) GetMonthCategory added in v1.7.0

func (b *PlanService) GetMonthCategory(ctx context.Context, month string, categoryID string) (*CategoryResponse, error)

GetMonthCategory retrieves a category for a specific plan month. The month should be in ISO format (e.g., "2024-01-01") or "current" for the current month. Amounts (budgeted, activity, balance) are specific to the requested month.

func (*PlanService) GetPayee added in v1.7.0

func (b *PlanService) GetPayee(ctx context.Context, payeeID string) (*PayeeResponse, error)

GetPayee returns a single payee by ID.

func (*PlanService) GetPayeeLocation added in v1.7.0

func (b *PlanService) GetPayeeLocation(ctx context.Context, locationID string) (*PayeeLocationResponse, error)

GetPayeeLocation returns a single payee location by ID.

func (*PlanService) GetPlan added in v1.7.0

func (b *PlanService) GetPlan(ctx context.Context) (*PlanDetailResponse, error)

GetPlan returns a full plan export with all months and categories. This is more efficient than making per-month API calls.

func (*PlanService) GetScheduledTransaction added in v1.7.0

func (b *PlanService) GetScheduledTransaction(ctx context.Context, scheduledTransactionID string) (*ScheduledTransactionResponse, error)

GetScheduledTransaction returns a single scheduled transaction by ID.

func (*PlanService) GetSettings added in v1.7.0

func (b *PlanService) GetSettings(ctx context.Context) (*BudgetSettingsResponse, error)

GetSettings returns the settings for this plan.

func (*PlanService) GetTransaction added in v1.7.0

func (b *PlanService) GetTransaction(ctx context.Context, transactionID string) (*TransactionResponse, error)

GetTransaction returns a single transaction by ID.

func (*PlanService) ImportTransactions added in v1.7.0

func (b *PlanService) ImportTransactions(ctx context.Context) (*TransactionsImportResponse, error)

ImportTransactions imports transactions from linked accounts.

func (*PlanService) MoneyMovementGroups added in v1.7.0

func (b *PlanService) MoneyMovementGroups(ctx context.Context, data url.Values) (*MoneyMovementGroupsResponse, error)

MoneyMovementGroups returns all money movement groups for this plan.

func (*PlanService) MoneyMovements added in v1.7.0

func (b *PlanService) MoneyMovements(ctx context.Context, data url.Values) (*MoneyMovementsResponse, error)

MoneyMovements returns all money movements for this plan.

func (*PlanService) MonthMoneyMovementGroups added in v1.7.0

func (b *PlanService) MonthMoneyMovementGroups(ctx context.Context, month string, data url.Values) (*MoneyMovementGroupsResponse, error)

MonthMoneyMovementGroups returns money movement groups for a specific month.

func (*PlanService) MonthMoneyMovements added in v1.7.0

func (b *PlanService) MonthMoneyMovements(ctx context.Context, month string, data url.Values) (*MoneyMovementsResponse, error)

MonthMoneyMovements returns money movements for a specific month.

func (*PlanService) MonthTransactions added in v1.7.0

func (b *PlanService) MonthTransactions(ctx context.Context, month string, data url.Values) (*HybridTransactionListResponse, error)

MonthTransactions returns the transactions for a specific month.

func (*PlanService) Months added in v1.7.0

Months returns the list of plan months for this plan.

func (*PlanService) PayeeLocations added in v1.7.0

func (b *PlanService) PayeeLocations(ctx context.Context) (*PayeeLocationListResponse, error)

PayeeLocations returns all payee locations for this plan.

func (*PlanService) PayeeLocationsByPayee added in v1.7.0

func (b *PlanService) PayeeLocationsByPayee(ctx context.Context, payeeID string) (*PayeeLocationListResponse, error)

PayeeLocationsByPayee returns all payee locations for a specific payee.

func (*PlanService) PayeeTransactions added in v1.7.0

func (b *PlanService) PayeeTransactions(ctx context.Context, payeeID string, data url.Values) (*HybridTransactionListResponse, error)

PayeeTransactions returns the transactions for a specific payee.

func (*PlanService) Payees added in v1.7.0

func (b *PlanService) Payees(ctx context.Context, data url.Values) (*PayeeListResponse, error)

Payees returns the list of payees for this plan.

func (*PlanService) ScheduledTransactions added in v1.7.0

func (b *PlanService) ScheduledTransactions(ctx context.Context, data url.Values) (*ScheduledTransactionListResponse, error)

func (*PlanService) Transactions added in v1.7.0

func (b *PlanService) Transactions(ctx context.Context, data url.Values) (*TransactionListResponse, error)

func (*PlanService) UpdateCategory added in v1.7.0

func (b *PlanService) UpdateCategory(ctx context.Context, categoryID string, req *UpdateCategoryRequest) (*SaveCategoryResponse, error)

UpdateCategory updates a category.

func (*PlanService) UpdateCategoryGroup added in v1.7.0

func (b *PlanService) UpdateCategoryGroup(ctx context.Context, categoryGroupID string, req *UpdateCategoryGroupRequest) (*SaveCategoryGroupResponse, error)

UpdateCategoryGroup updates a category group.

func (*PlanService) UpdateMonthCategory added in v1.7.0

func (b *PlanService) UpdateMonthCategory(ctx context.Context, month string, categoryID string, budgeted int64) (*SaveCategoryResponse, error)

UpdateMonthCategory updates the budgeted amount for a category in a specific month. The month should be in ISO format (e.g., "2024-01-01") or "current" for the current month. The budgeted amount is in milliunits (e.g., $50.00 = 50000).

func (*PlanService) UpdatePayee added in v1.7.0

func (b *PlanService) UpdatePayee(ctx context.Context, payeeID string, req *UpdatePayeeRequest) (*SavePayeeResponse, error)

UpdatePayee updates a payee.

func (*PlanService) UpdateScheduledTransaction added in v1.7.0

func (b *PlanService) UpdateScheduledTransaction(ctx context.Context, scheduledTransactionID string, req *UpdateScheduledTransactionRequest) (*ScheduledTransactionResponse, error)

UpdateScheduledTransaction updates an existing scheduled transaction.

func (*PlanService) UpdateTransaction added in v1.7.0

func (b *PlanService) UpdateTransaction(ctx context.Context, transactionID string, req *UpdateTransactionRequest) (*TransactionResponse, error)
Example
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kevinburke/go-types"
	"github.com/kevinburke/ynab-go"
)

func main() {
	client := ynab.NewClient("your-api-token")

	// Update an existing transaction's memo and category
	update := &ynab.UpdateTransaction{
		Date:       ynab.Date(time.Date(2023, 6, 15, 0, 0, 0, 0, time.Local)),
		Memo:       types.NullString{String: "Updated memo", Valid: true},
		CategoryID: types.NullString{String: "new-category-id", Valid: true},
	}

	resp, err := client.Plans("plan-id").UpdateTransaction(
		context.Background(),
		"transaction-id",
		&ynab.UpdateTransactionRequest{Transaction: update},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Updated transaction: %s\n", resp.Data.Transaction.ID)
}

func (*PlanService) UpdateTransactions added in v1.7.0

UpdateTransactions bulk-updates multiple transactions.

type PlanSettings added in v1.7.0

type PlanSettings struct {
	DateFormat     DateFormat     `json:"date_format"`
	CurrencyFormat CurrencyFormat `json:"currency_format"`
}

PlanSettings represents the settings for a plan.

type PlanSettingsResponse added in v1.7.0

type PlanSettingsResponse struct {
	Data struct {
		Settings PlanSettings `json:"settings"`
	} `json:"data"`
}

PlanSettingsResponse wraps the plan settings response.

type SaveAccount added in v1.5.0

type SaveAccount struct {
	Name    string `json:"name"`
	Type    string `json:"type"`
	Balance int64  `json:"balance"` // The current balance of the account in milliunits format
}

SaveAccount represents the data for creating a new account.

type SaveCategory added in v1.5.0

type SaveCategory struct {
	Name                 string `json:"name,omitempty"`
	Note                 string `json:"note,omitempty"`
	CategoryGroupID      string `json:"category_group_id,omitempty"`
	GoalTarget           *int64 `json:"goal_target,omitempty"` // The goal target amount in milliunits.
	GoalTargetDate       string `json:"goal_target_date,omitempty"`
	GoalNeedsWholeAmount *bool  `json:"goal_needs_whole_amount,omitempty"`
}

SaveCategory represents the data for updating a category.

type SaveCategoryData added in v1.5.0

type SaveCategoryData struct {
	Category        *Category `json:"category"`
	ServerKnowledge int64     `json:"server_knowledge"`
}

SaveCategoryData contains the updated category and server knowledge.

type SaveCategoryGroup added in v1.7.0

type SaveCategoryGroup struct {
	Name string `json:"name"` // Maximum 50 characters.
}

SaveCategoryGroup represents the data for creating or updating a category group.

type SaveCategoryGroupResponse added in v1.7.0

type SaveCategoryGroupResponse struct {
	Data struct {
		CategoryGroup   *CategoryGroup `json:"category_group"`
		ServerKnowledge int64          `json:"server_knowledge"`
	} `json:"data"`
}

SaveCategoryGroupResponse wraps the response from creating or updating a category group.

type SaveCategoryResponse added in v1.5.0

type SaveCategoryResponse struct {
	Data SaveCategoryData `json:"data"`
}

SaveCategoryResponse is the response from creating or updating a category.

type SaveMonthCategory added in v1.5.0

type SaveMonthCategory struct {
	Budgeted int64 `json:"budgeted"` // Budgeted amount in milliunits format
}

SaveMonthCategory contains the assigned amount to set for a category in a month.

type SavePayee added in v1.5.0

type SavePayee struct {
	Name string `json:"name"` // Maximum 500 characters.
}

SavePayee represents the data for updating a payee.

type SavePayeeResponse added in v1.5.0

type SavePayeeResponse struct {
	Data struct {
		Payee           *Payee `json:"payee"`
		ServerKnowledge int64  `json:"server_knowledge"`
	} `json:"data"`
}

SavePayeeResponse wraps the response from updating a payee.

type SaveScheduledTransaction added in v1.5.0

type SaveScheduledTransaction struct {
	AccountID  string           `json:"account_id"`
	Date       Date             `json:"date"`             // The scheduled transaction date in ISO format (e.g. 2016-12-01). Must be a future date no more than 5 years out.
	Amount     *int64           `json:"amount,omitempty"` // The scheduled transaction amount in milliunits format
	PayeeID    types.NullString `json:"payee_id"`         // To create a transfer, use the account transfer payee pointing to the target account.
	PayeeName  types.NullString `json:"payee_name"`       // If provided and payee_id is null, used to resolve the payee by same name or creation of a new payee.
	CategoryID types.NullString `json:"category_id"`      // Credit Card Payment categories are not permitted. Split scheduled transactions are not supported.
	Memo       types.NullString `json:"memo"`
	FlagColor  FlagColor        `json:"flag_color,omitempty"`
	Frequency  string           `json:"frequency,omitempty"`
}

SaveScheduledTransaction represents the data for creating or updating a scheduled transaction.

type ScheduledTransaction

type ScheduledTransaction struct {
	AccountID         string           `json:"account_id"`
	AccountName       string           `json:"account_name"`
	Amount            int64            // The scheduled transaction amount in milliunits format
	AmountFormatted   string           `json:"amount_formatted"`
	AmountCurrency    float64          `json:"amount_currency"`
	CategoryID        types.NullString `json:"category_id"`
	CategoryName      types.NullString `json:"category_name"`
	DateFirst         Date             `json:"date_first"` // The first date for which the Scheduled Transaction was scheduled.
	DateNext          Date             `json:"date_next"`  // The next date for which the Scheduled Transaction is scheduled.
	Deleted           bool
	FlagColor         FlagColor        `json:"flag_color"`
	FlagName          types.NullString `json:"flag_name"` // The customized name of a transaction flag
	Frequency         string
	ID                string `json:"id"`
	Memo              string
	PayeeID           types.NullString `json:"payee_id"`
	PayeeName         string           `json:"payee_name"`
	TransferAccountID types.NullString `json:"transfer_account_id"` // If a transfer, the account_id which the scheduled transaction transfers to
	Subtransactions   []Transaction    `json:"subtransactions"`
}

type ScheduledTransactionListResponse

type ScheduledTransactionListResponse struct {
	Data ScheduledTransactionListWrapper `json:"data"`
}

type ScheduledTransactionListWrapper

type ScheduledTransactionListWrapper struct {
	ScheduledTransactions []*ScheduledTransaction `json:"scheduled_transactions"`
	ServerKnowledge       int64                   `json:"server_knowledge"`
}

type ScheduledTransactionResponse added in v1.5.0

type ScheduledTransactionResponse struct {
	Data struct {
		ScheduledTransaction *ScheduledTransaction `json:"scheduled_transaction"`
	} `json:"data"`
}

ScheduledTransactionResponse wraps a single scheduled transaction response.

type SubTransaction added in v0.6.0

type SubTransaction struct {
	Amount     int64            `json:"amount"` // The subtransaction amount in milliunits format
	PayeeID    types.NullString `json:"payee_id"`
	PayeeName  types.NullString `json:"payee_name"`
	CategoryID types.NullString `json:"category_id"` // Credit Card Payment categories are not permitted.
	Memo       types.NullString `json:"memo"`
}

type Transaction

type Transaction struct {
	AccountID               string           `json:"account_id"`
	AccountName             string           `json:"account_name"`
	Amount                  int64            // The transaction amount in milliunits format
	AmountFormatted         string           `json:"amount_formatted"`
	AmountCurrency          float64          `json:"amount_currency"`
	Approved                bool             // Whether or not the transaction is approved
	CategoryID              types.NullString `json:"category_id"`
	CategoryName            types.NullString `json:"category_name"` // The name of the category. If a split transaction, this will be 'Split'.
	Cleared                 ClearedStatus    // The cleared status of the transaction
	Date                    Date             // The transaction date in ISO format (e.g. 2016-12-01)
	DebtTransactionType     types.NullString `json:"debt_transaction_type"` // If a debt/loan account transaction, the type of transaction
	Deleted                 bool             // Whether or not the transaction has been deleted. Deleted transactions will only be included in delta requests.
	FlagColor               FlagColor        `json:"flag_color"` // The transaction flag
	FlagName                types.NullString `json:"flag_name"`  // The customized name of a transaction flag
	ID                      string           `json:"id"`
	ImportID                types.NullString `json:"import_id"`                  // If the transaction was imported, a unique (by account) import identifier
	ImportPayeeName         types.NullString `json:"import_payee_name"`          // If the transaction was imported, the payee name that was used when importing and before applying any payee rename rules
	ImportPayeeNameOriginal types.NullString `json:"import_payee_name_original"` // If the transaction was imported, the original payee name as it appeared on the statement
	Memo                    string
	PayeeID                 types.NullString `json:"payee_id"`
	PayeeName               string           `json:"payee_name"`
	TransferAccountID       types.NullString `json:"transfer_account_id"`     // If a transfer transaction, the account to which it transfers
	TransferTransactionID   types.NullString `json:"transfer_transaction_id"` // If a transfer transaction, the id of transaction on the other side of the transfer
	MatchedTransactionID    types.NullString `json:"matched_transaction_id"`  // If transaction is matched, the id of the matched transaction
	Subtransactions         []Transaction    `json:"subtransactions"`         // If a split transaction, the subtransactions.
}

type TransactionListResponse

type TransactionListResponse struct {
	Data TransactionListWrapper `json:"data"`
}

type TransactionListWrapper

type TransactionListWrapper struct {
	Transactions    []*Transaction `json:"transactions"`
	ServerKnowledge int64          `json:"server_knowledge"`
}

type TransactionResponse added in v0.6.0

type TransactionResponse struct {
	Data TransactionWrapper `json:"data"`
}

type TransactionWrapper added in v0.6.0

type TransactionWrapper struct {
	Transaction *Transaction `json:"transaction"`
}

type TransactionsImportResponse added in v1.5.0

type TransactionsImportResponse struct {
	Data struct {
		TransactionIDs []string `json:"transaction_ids"`
	} `json:"data"`
}

TransactionsImportResponse wraps the response from importing transactions.

type UpdateCategoryGroupRequest added in v1.7.0

type UpdateCategoryGroupRequest struct {
	CategoryGroup *SaveCategoryGroup `json:"category_group"`
}

UpdateCategoryGroupRequest is the request body for updating a category group.

type UpdateCategoryRequest added in v1.5.0

type UpdateCategoryRequest struct {
	Category *SaveCategory `json:"category"`
}

UpdateCategoryRequest is the request body for updating a category.

type UpdateMonthCategoryRequest added in v1.5.0

type UpdateMonthCategoryRequest struct {
	Category SaveMonthCategory `json:"category"`
}

UpdateMonthCategoryRequest is the request body for updating a category's assigned amount for a month.

type UpdatePayeeRequest added in v1.5.0

type UpdatePayeeRequest struct {
	Payee *SavePayee `json:"payee"`
}

UpdatePayeeRequest is the request body for updating a payee.

type UpdateScheduledTransactionRequest added in v1.5.0

type UpdateScheduledTransactionRequest struct {
	ScheduledTransaction *SaveScheduledTransaction `json:"scheduled_transaction"`
}

UpdateScheduledTransactionRequest is the request body for updating a scheduled transaction.

type UpdateTransaction added in v0.6.0

type UpdateTransaction struct {
	AccountID  *string          `json:"account_id,omitempty"`
	Date       Date             `json:"date"`             // The transaction date in ISO format (e.g. 2016-12-01). Split transaction dates cannot be changed.
	Amount     *int64           `json:"amount,omitempty"` // The transaction amount in milliunits format. Split transaction amounts cannot be changed.
	PayeeID    types.NullString `json:"payee_id"`         // To create a transfer, use the account transfer payee pointing to the target account.
	PayeeName  types.NullString `json:"payee_name"`       // If provided and payee_id is null, used to resolve the payee by matching rename rule, same name, or creation of a new payee.
	CategoryID types.NullString `json:"category_id"`      // Credit Card Payment categories are not permitted.
	Memo       types.NullString `json:"memo"`
	Cleared    types.NullString `json:"cleared"`
	Approved   *bool            `json:"approved,omitempty"` // Whether or not the transaction is approved.
	FlagColor  types.NullString `json:"flag_color"`
	// An array of subtransactions to configure a transaction as a split. Updating subtransactions on an existing split transaction is not supported.
	Subtransactions []*SubTransaction `json:"subtransactions,omitempty"`
}

func UpdateTransactionToTransfer added in v1.4.0

func UpdateTransactionToTransfer(existingTxn *Transaction, targetAccount *Account) (*UpdateTransaction, error)

UpdateTransactionToTransfer creates an UpdateTransaction that converts an existing transaction into a transfer to the target account. The existing transaction's date, amount, memo, cleared status, and approval are preserved. The targetAccount must have a valid TransferPayeeID.

Example
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/kevinburke/ynab-go"
)

func main() {
	client := ynab.NewClient("your-api-token")
	ctx := context.Background()

	// Get transactions to find the one we want to convert to a transfer
	// (e.g., an ATM withdrawal that should actually be a transfer to cash account)
	txnResp, err := client.Plans("plan-id").Transactions(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}

	// Find the transaction to convert (in practice, you'd have the ID already)
	var existingTxn *ynab.Transaction
	for _, txn := range txnResp.Data.Transactions {
		if txn.PayeeName == "ATM Withdrawal" {
			existingTxn = txn
			break
		}
	}
	if existingTxn == nil {
		log.Fatal("transaction not found")
	}

	// Get the target account for the transfer
	accounts, err := client.Plans("plan-id").Accounts(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}

	var cashAccount *ynab.Account
	for _, acct := range accounts.Data.Accounts {
		if acct.Name == "Cash" {
			cashAccount = acct
			break
		}
	}

	if cashAccount == nil {
		log.Fatal("could not find Cash account")
	}

	// Convert the transaction to a transfer
	// This preserves the date, amount, memo, cleared status, and approval
	update, err := ynab.UpdateTransactionToTransfer(existingTxn, cashAccount)
	if err != nil {
		log.Fatal(err)
	}

	resp, err := client.Plans("plan-id").UpdateTransaction(
		ctx,
		existingTxn.ID,
		&ynab.UpdateTransactionRequest{Transaction: update},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Converted to transfer: %s\n", resp.Data.Transaction.ID)
	fmt.Printf("Now transfers to: %s\n", resp.Data.Transaction.TransferAccountID.String)
}

type UpdateTransactionRequest added in v0.6.0

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

type UpdateTransactionsRequest added in v1.5.0

type UpdateTransactionsRequest struct {
	Transactions []*UpdateTransaction `json:"transactions"`
}

UpdateTransactionsRequest is the request body for bulk-updating transactions.

type User added in v1.5.0

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

User represents a YNAB user.

type UserResponse added in v1.5.0

type UserResponse struct {
	Data struct {
		User *User `json:"user"`
	} `json:"data"`
}

UserResponse wraps the user response.

Directories

Path Synopsis
The ynab-export-transactions command retrieves transactions and prints them to stdout in CSV format.
The ynab-export-transactions command retrieves transactions and prints them to stdout in CSV format.
The ynab-largest-inputs-outputs function finds the largest inputs and outputs to your Net Worth, optionally filtered by a month argument.
The ynab-largest-inputs-outputs function finds the largest inputs and outputs to your Net Worth, optionally filtered by a month argument.

Jump to

Keyboard shortcuts

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