Splitwise for YNAB

Try it out for free 🔗

Background

My partner and I use separate YNAB plans but we use Splitwise as the source of truth for shared expenses

When I pay

If I pay $50 for gas with my debit card, here's the manual process to categorize this expense:

1. In YNAB, I categorize the $50 outflow in my Gas/Parking category.
2. In Splitwise, I add a $50 split evenly expense to our shared group.
3. In YNAB, I add a new $25 inflow transaction into a Splitwise cash account, and categorize it back into Gas/Parking

After this, YNAB shows I've only spent $25 on my half of gas, and my Splitwise account shows a positive balance of $25 (what I'm owed in the Splitwise app)

When she pays

If she pays $100 for our electricity bill, here's the manual process to categorize this expense:

2. In Splitwise, she adds a $100 split evenly expense to our shared group.
3. In YNAB, I add a new $50 outflow transaction into a Splitwise cash account, and categorize it into Utilities

After this, YNAB shows I've spent $50 on my half of the electricity bill, and my Splitwise account would show a negative balance of $50 (what I owe in the Splitwise app).

Settling up

When we settle up on Splitwise, the transaction is categorized as a transfer between my Splitwise account and my Checking account.

Warning

With this workflow, the dollars in your fake Splitwise cash account are not spendable. When the balance is positive (you are owed money), you can assign those dollars in your plan, but they are not in your Checking account yet. You must keep an eye on this and settle up as needed.

Concept

This project automates steps (2) and (3) above. Here's how:

First, I mark a transaction as shared in YNAB:

1. Flag the transaction with a color (I use blue, this is configurable)

When triggered, this app will search for flagged transactions. For each flagged transaction, it will:

1. Add a split equally expense into a Splitwise group
2. Add the corresponding transaction into the Splitwise account in YNAB for both partners

This lets me use Splitwise for shared expenses without ever leaving YNAB.

FAQs

What if my partner doesn't use YNAB?

This still works as long as your partner enters an expense into the configured shared group in their Splitwise app.

What if an expense isn't split evenly?

Enter it directly in the Splitwise app as such.

A common scenario is when you front a full purchase for your partner. In your Splitwise app, add an expense where you're owed the full amount. Both transactions will cancel out in YNAB, and would be a good candidate for a Reimbursements category.

Self-Hosted Setup

You can deploy your own instance of this app to run automatically without manual intervention.

Prerequisites

• A free Vercel account
• A free Upstash Redis account
• Your YNAB and Splitwise API credentials

1. Fork and Deploy

1. Fork this repository to your GitHub account
2. Connect your GitHub account to Vercel and deploy the fork
3. Note your deployment URL (e.g., https://your-app.vercel.app)

2. Set up Upstash Redis

1. Create a new Redis database at Upstash
2. Copy the UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN from your database details
3. Add these as environment variables in your Vercel deployment

3. Configure Environment Variables

In your Vercel project settings, add these environment variables:

API_SECRET_KEY=your-secret-key-here
UPSTASH_REDIS_REST_URL=your-upstash-url
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

4. Set up GitHub Actions Secrets

In your forked repository, go to Settings → Secrets and variables → Actions, and add these secrets:

API Configuration

• API_SECRET_KEY - Same value as your Vercel environment variable
• API_BASE_URL - Your Vercel url (e.g. https://your-app.vercel.app)

Secrets (for "mine" user)

• YNAB_API_KEY_MINE - Your YNAB personal access token
• YNAB_BUDGET_ID_MINE - Your YNAB budget ID
• YNAB_SPLITWISE_ACCOUNT_ID_MINE - Your Splitwise cash account ID in YNAB
• SPLITWISE_API_KEY_MINE - Your Splitwise API key
• SPLITWISE_USER_ID_MINE - Your Splitwise user ID (numeric)

Secrets (for "partner" user, if applicable)

• YNAB_API_KEY_PARTNER - Partner's YNAB personal access token
  • Can me same as "mine" if both budgets are on the same YNAB account
• YNAB_BUDGET_ID_PARTNER - Partner's YNAB budget ID
• YNAB_SPLITWISE_ACCOUNT_ID_PARTNER - Partner's Splitwise cash account ID in YNAB
• SPLITWISE_API_KEY_PARTNER - Partner's Splitwise API key (if applicable)
• SPLITWISE_USER_ID_PARTNER - Partner's Splitwise user ID (numeric, if applicable)

Shared Secrets (required)

• SPLITWISE_GROUP_ID_SHARED - Your shared Splitwise group ID

Step 5: Update GitHub Actions (optional)

If you want to change flag colors, emojis, or currenct, you can edit ./github/workflows/cron.yml

How It Works

The GitHub Actions workflow can be triggered manually and calls your deployed API endpoints with all the necessary configuration. This bypasses the need for manual OAuth flows and web interface interactions.

The sync uses Upstash Redis to store sync state, ensuring transactions aren't processed multiple times and maintaining consistency across runs.

Note

The automatic 6-hour schedule is currently disabled. You can manually trigger the workflow from the Actions tab in your GitHub repository, or re-enable the schedule by uncommenting the schedule section in .github/workflows/cron.yml.

Development

This is a Next.js project bootstrapped with create-next-app.

Prerequisites

• Node >= v22
• A Postgres database (Prisma, Neon, or local installation)

Setup

Set up your environment variables

cp .env.example .env
vim .env # fill these out

Install dependencies

npm install

Run the development server

npm run dev

Open http://localhost:3000 with your browser to see the main page.