A simple, unified view of your transaction history across all your payment methods
The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:
Some assembly required.
This application is a simple spending tracker/budgeting service that can be used to monitor your finances across any payment mechanism (credit card, debit card, cash sharing app), that has purchase notifications via email. Please see the associated blog post for the inspiration behind the application.
The basic flow for the application is as follows: purchase notifications via email are auto forwarded to a Zapier service. Zapier sends the email subject and body via a HTTP
POSTrequest to the Python Flask API endpoint. The API parses the transaction information (description/amount) from the email body, assigns it a category, and writes the transaction to a Google Sheets workbook. All expenses across any payment mechanism can be viewed on the Sheets workbook, along with monthly summaries.
These instructions will walk you through how to set up the application for yourself and host it on Heroku. Fork and clone this repo to get started.
The secret API for all your financial accounts is purchase notifications. For each associated payment product, you need to turn on purchase notifications via email for any transaction you make. For example, Chase gives instructions on their website, and Venmo has the option under your profile in the mobile app.
Copy the following workbook into your own Google drive.
Make a copy. Make sure the copy is named
Budget. There are instructions inside the workbook on how to use it.
Head to the Google API Console. You should see a box that says "To view this page, select a project." Click the
createbutton the right side. Give it a name and save. Click the
Credentialstab on the left side. Select
Service account key.
New service accountfrom the drop down. Give the service account a name, for the role enter
JSONselected and create it. The credentials file will be automatically downloaded. Rename this file
credentials.jsonand move it to the this application's directory.
Manage service accounts. Copy the email address of the service account you just created. Head back to the Sheets workbook you copied and share the document with the service account email. Make sure to give it access to edit.
Go to the Google Sheets API and enable it for your project.
Inside the application folder run
heroku create my-app-name-here-api-heroku
my-app-name-hereis the unique name of the application, change it to what ever you want. Heroku will assign a unique name for you if you don't put anything.
The output of the command should look like the following:
Creating ⬢ my-app-name-here-api-heroku... done https://my-app-name-here-api-heroku.herokuapp.com/ | https://git.heroku.com/my-app-name-here-api-heroku.git
Take note of the base URL for the application as well as the Heroku git repo it creates for you.
By default, Heroku deploys what ever is on the origin master branch in your fork to Heroku. However, we don't want to upload the
credentials.jsonfile to Github since that contains your Google account info. To fix this, we can create a local branch that contains
credentials.jsonwhile your master does not.
Create a new branch.
git checkout -b "secret-branch"
Now add and commit the
git add credentials.json git commit -m "Added credentials file"
Deploy by pulling any upstream changes from the master branch and then pushing to Heroku, Then check out the master branch again.
git pull origin master git push heroku secret-branch:master git checkout master
Check the Heroku logs to make sure your build succeeded.
Login or create an account on Zapier. Create a new zap. Set the "Trigger App" as email. Save and continue. Set anything you want for your email address prefix. Copy this email, click
Continue, and then head over to your email client, i.e. Gmail.
Send an email to your new email address with something in the subject and body. Head back to Zapier and once it receives your email, click
Pull in sampleand then
Now, we need to add an action to the Zap. Click the
Add a Stepbutton on the left side of the screen. Select
Action/Search, search for
Webhooks, and then select
Enter your Heroku URL +
/budget/api/emailat the end and change the Payload type to
Json. Use the following key-value pairs for the Data section.
body: Body Plain subject: Subject
Make sure you are click the
+button on the key entry and select
Subject. You should see the text you entered for the body and subject in the test email you sent.
Continue to the next step, send a test, and then finish. Turn the Zap on.
Auto forward all of your purchase notifications to your new Zapier email address. For Gmail, instructions for setting up auto-forwarding with filtering for your specific messages can be found here.
When auto forwarding with Gmail, you'll need to follow these instructions to verify your email address as you cant view the Zapier inbox.
By default, the application is set up to parse Chase credit card purchase notifications and Venmo charge & payment notifications. If you want more/different integrations, you'll have to set them up yourself. The parsing of the purchase notifications is done via regex.
The body of each request is set to print in the Heroku logs with
print(repr(body)). When an incoming purchase notification sent to the API, use the
Heroku logsto view the logs and copy the raw email body, and then create a regex to parse the description and amount. A helpful tool for building your regex expressions is here. I used a positive lookahead and a positive lookbehind to parse the result. Add a new
elifblock in the
parse_email()function to capture this transaction type.
Each transaction is assigned a category based on the description that is parses from the email. Add the common places you buy things from the in the
constants.py. Be sure to redeploy to Heroku once you make changes.
Once set up this, this application offers a simple, unified view of your transaction history across all your payment methods. The only maintenance needed is if your credit card company decides to change the format of their purchase notification emails. You'll have to update your regex, but this should be very infrequent.
Because the app uses a Google Sheets workbook as the frontend and backend, it is customizable and open for you to do your own spending analysis.