Skip to content

README.md

Latest commit

 

History

History
197 lines (134 loc) · 5.91 KB

README.md

File metadata and controls

197 lines (134 loc) · 5.91 KB
Raw

Grocery → Splitwise Sync

For lazy folks like me who order groceries every other day, forget to log expenses, and then get into awkward "bro you owe me ₹3,000" conversations with their roommates at the end of the month.

Automatically sync your Swiggy Instamart grocery orders from Gmail into a Splitwise group — so you can split expenses with roommates or flatmates without lifting a finger.

Blinkit and Zepto support coming soon! 🚧

Comes with an optional ML classifier that auto-includes shared household groceries (vegetables, dal, paneer, cleaning supplies) and auto-excludes personal items (fruits, cereals, personal care). Set it up once, run it whenever, and never do expense math again.

Features

  • Fetches Swiggy Instamart order emails directly from Gmail (read-only OAuth)
  • Parses order items from email bodies
  • Skips cancelled orders automatically
  • Deduplicates — never double-syncs an order
  • ML classifier (optional): auto-includes groceries/household, auto-excludes personal items, prompts on ambiguous orders
  • Learns from your y/n feedback to improve future classifications
  • Full Splitwise CLI: view groups, dues, expenses, friends, add custom expenses

Setup

1. Clone & create a virtual environment

git clone https://github.com/sirsha-chatterjee/swiggy-splitwise-sync.git
cd swiggy-splitwise-sync
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Gmail API credentials

  1. Go to Google Cloud Console
  2. Create a new project (or use an existing one)
  3. Enable the Gmail API
  4. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
  5. Choose Desktop app, download the JSON file
  6. Save it as credentials.json in the project root

On first run, a browser window will open for Gmail authorization. A gmail_token.json will be saved locally — keep it private.

3. Splitwise API credentials

  1. Go to https://secure.splitwise.com/apps
  2. Register a new app
  3. Note your Consumer Key, Consumer Secret
  4. Generate an OAuth Access Token (use this guide or a tool like Postman)

4. Configure environment variables

cp .env.example .env

Edit .env and fill in your credentials:

SPLITWISE_OAUTH_CONSUMER_KEY=your_consumer_key
SPLITWISE_OAUTH_CONSUMER_SECRET=your_consumer_secret
SPLITWISE_OAUTH_ACCESS_TOKEN=your_access_token

Usage

All commands are run via splitwise_cli.py. Make sure your venv is active:

source .venv/bin/activate

View your Splitwise groups

python splitwise_cli.py groups

View dues (who owes you / who you owe)

python splitwise_cli.py dues

View recent expenses

python splitwise_cli.py expenses
python splitwise_cli.py expenses --group "Flat Expenses" -n 10

View friends with balances

python splitwise_cli.py friends

Add a custom expense

python splitwise_cli.py add 450 "Electricity bill" --group "Flat Expenses" --date 2026-03-15

Sync Swiggy Instamart orders

Dry run (preview without posting to Splitwise):

python splitwise_cli.py sync --since 01-01-2026 --group "Flat Expenses" --dry-run

Sync with ML classifier (recommended — filters personal items):

python splitwise_cli.py sync --since 01-01-2026 --group "Flat Expenses" --classify

Sync last N days:

python splitwise_cli.py sync --days 30 --group "Flat Expenses" --classify

Sync without classifier (adds all orders):

python splitwise_cli.py sync --since 01-01-2026 --group "Flat Expenses"

Sync options

Flag Description
--since dd-mm-yyyy Fetch orders from this date onwards
--days N Fetch orders from the last N days (default: 30)
--group NAME Splitwise group name (default: Swiggy Instamart)
--classify Use ML classifier to filter orders
--dry-run Preview without posting to Splitwise

ML Classifier

When --classify is passed, each order is scored against two categories:

  • Include: vegetables, dairy (paneer, curd, ghee), eggs, poultry, meat, rice/dal/atta, spices, cooking oil, shared household cleaning (detergent, floor cleaner, dish wash, garbage bags)
  • Exclude: fruits, milk, breakfast cereals, personal care (shampoo, toothpaste, deodorant), stationery, medicines, electronics

Orders with a high-confidence score are auto-decided. Ambiguous orders prompt you interactively:

? unsure  (0.41)  2026-03-07  ₹489.00  ["Millet Muesli", "Amul Milk"]
    Include this order? [y/n]:

Your answers are saved to classifier_feedback.json and used as additional anchors in future runs, so the classifier improves over time.

File Overview

File Purpose
splitwise_cli.py Main CLI entry point
sync_orders.py Gmail fetching, email parsing, Splitwise expense creation
order_classifier.py ML classifier using paraphrase-MiniLM-L3-v2
requirements.txt Python dependencies
.env.example Template for environment variables

Files created at runtime (gitignored):

File Purpose
credentials.json Google OAuth client credentials
gmail_token.json Gmail access token (auto-refreshed)
processed_orders.json Tracks synced email IDs to prevent duplicates
classifier_feedback.json Learned include/exclude items from your feedback

Requirements

  • Python 3.9+
  • A Google Cloud project with Gmail API enabled
  • A Splitwise account with API credentials

Contributing

Currently supports Swiggy Instamart. Blinkit and Zepto support are on the roadmap — PRs are very much welcome! Found a bug or have a feature idea? Open an issue. The more grocery apps this supports, the less mental math we all have to do.