Skip to content
YNAB API JavaScript Library
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Add vscode config for debugging examples Aug 9, 2018
examples Some minor example improvements Feb 4, 2019
scripts Fix path references with generate.js moved to scripts/ Sep 25, 2018
src Ran generate and fixed updateMonthCategory parameters so it work with… Feb 2, 2019
.gitignore Build structure tweaks for consistency w/ Ruby client and ease of use Jul 10, 2018
config.json Ran generate and fixed updateMonthCategory parameters so it work with… Feb 2, 2019
tsconfig.json Use TypeScript 3.0 project references for test project Aug 21, 2018

YNAB API JavaScript Library

Build Status npm version

Please read the YNAB API documentation for an overview of using the API and a complete list of available resources.

This client is generated using the Swagger Code Generator.


First, install the module with npm (or yarn):

npm install ynab

Then, depending upon your usage context, add a reference to it:

CommonJS / Node

const ynab = require("ynab");

ESM / TypeScript

import * as ynab from "ynab";


The API supports Cross Origin Resource Sharing (CORS) for asynchronous browser requests from any origin.

The dist/browser/ynab.js file (located in node_modules/ynab after installation) is specifically built to run in a browser / window context and exports ynab variable to global namespace. No other dependencies are needed.

<script src="ynab.js" async></script>
  // This assignment is not necessary but demonstrates that
  // once the library is loaded, the global 'ynab' object will be available.
  var ynab = window.ynab;


A simple way to load the library in a browser is by using the unpkg CDN, which is a "fast, global content delivery network for everything on npm". To use it, include a script tag like this in your file:

<script src="" async></script>

Using the "latest" tag will result in a 302 redirect to the latest version tag so it is highly recommended to use a specific version tag such as to avoid this redirect.


To use this client, you must obtain an access token from the My Account area of the YNAB web application.

const accessToken = "b43439eaafe2_this_is_fake_b43439eaafe2";
const ynabAPI = new ynab.API(accessToken);

(async function() {
  const budgetsResponse = await ynabAPI.budgets.getBudgets();
  const budgets =;
  for (let budget of budgets) {
    console.log(`Budget Name: ${}`);

Error Handling

If a response is returned with a code >= 300, instead of returning the response, the response will be thrown as an error to be caught.

const ynab = require("ynab");
const accessToken = "invalid_token";
const ynabAPI = new ynab.API(accessToken);

const budgetsResponse = ynabAPI.budgets
  .then(budgetsResponse => {
    // Won't get here because an error will be thrown
  .catch(e => {
    // {
    //   error: {
    //    id: "401",
    //    name: "unauthorized",
    //    detail: "Unauthorized"
    //   }
    // }


See the examples folder for example usage scenarios.


The following methods are available in this library. For more details on parameters and usage, the TypeScript declaration file can be referenced.

Method Description
User user.getUser() Returns authenticated user information
Budgets budgets.getBudgets() Returns budgets list with summary information
budgets.getBudgetById(budget_id) Returns a single budget with all related entities
budgets.getBudgetSettingsById(budget_id) Returns settings for a budget
Accounts accounts.getAccounts(budget_id) Returns all accounts
accounts.getAccountById(budget_id, account_id) Returns a single account
Categories categories.getCategories(budget_id) Returns all categories grouped by category group.
categories.getCategoryById(budget_id, category_id) Returns a single category
Payees payees.getPayees(budget_id) Returns all payees
payees.getPayeeById(budget_id, payee_id) Returns single payee
Payee Locations payee_locations.getPayeeLocations(budget_id) Returns all payee locations
payee_locations.getPayeeLocationById(budget_id, payee_location_id) Returns a single payee location
payee_locations.getPayeeLocationsByPayee(budget_id, payee_id) Returns all payee locations for the specified payee
Months months.getBudgetMonths(budget_id) Returns all budget months
months.getBudgetMonth(budget_id, month) Returns a single budget month
months.getMonthCategory_by_id(budget_id, month, category_id) Returns a single category for a specific budget month
months.updateMonthCategory(budget_id, month, category_id, month_category) Update an existing month category
Transactions transactions.getTransactions(budget_id) Returns budget transactions
transactions.getTransactionsByAccount(budget_id, account_id) Returns all transactions for a specified account
transactions.getTransactionsByCategory(budget_id, category_id) Returns all transactions for a specified category
transactions.getTransactionById(budget_id, transaction_id) Returns a single transaction
transactions.createTransaction(budget_id, data) Creates a single transaction
transactions.createTransactions(budget_id, data) Creates multiple transactions
transactions.updateTransaction(budget_id, transaction_id, data) Updates a single transaction
transactions.updateTransactions(budget_id, data) Updates multiple transactions
Scheduled Transactions scheduled_transactions.getScheduledTransactions(budget_id) Returns all scheduled transactions
scheduled_transactions.getScheduledTransactionById(budget_id, scheduled_transaction_id) Returns a single scheduled transaction


There are several utilities available on the utils export to make working with ISO dates and milliunits a bit easier.

// Returns the current month (system timezone) in ISO 8601 format (i.e. '2015-12-01')
getCurrentMonthInISOFormat(): string;
// Returns the current date (system timezone) in ISO 8601 format (i.e. '2015-12-15')
getCurrentDateInISOFormat(): string;
// Converts an ISO 8601 formatted string to a JS date object
convertFromISODateString(isoDateString: string): Date;
// Converts a milliunits amount to a currency amount
convertMilliUnitsToCurrencyAmount(milliunits: number, currencyDecimalDigits: number): number;


  • Install dependencies: npm install
  • Generate latest client based on swagger spec: npm run generate
  • Run tests: npm test


  • Commit all changes
  • Run npm run release to publish to npm


Copyright (c) 2018 You Need A Budget, LLC

Licensed under the Apache-2.0 license

You can’t perform that action at this time.