Retrieve User's YTD Taxes

At any time you can retrieve the user's year-to-date (YTD) tax information for a particular tax year. This information will always be the most up-to-date tax information for your user.

How to Retrieve YTD Taxes

If you haven't done so already, follow the Creating a User guide and make sure you have the resulting userId available for the next step.

Next, call the GET /users/{userId}/taxes/{year} API endpoint, replacing the {userId} and {year} with your desired UserUser - A single end-user of your application. Each user has a unique userId, which should be stored in your database and used to make API requests on behalf of this individual. and tax year, respectively.

📘

If you do not set a filingState when calculating taxes, it will default the filingState toca.

By default, Abound will use the sum of the incomes and expenses created using the POST /users/{userId}/incomes and POST /users/{userId}/expenses to generate the 1099Income and expenseDeduction values in the tax calculator.

curl \
  --request GET \
  --url https://sandbox-api.withabound.com/v2/users/<<testUserId>>/taxes/2020 \
  --header 'Authorization: Bearer <<apiKey>>'
const { default: Abound, Environment } = require("@withabound/node-sdk");

const abound = new Abound({
  appId: "<<sandbox_app_id>>",
  appSecret: "<<sandbox_app_secret>>",
  environment: Environment.SANDBOX,
  apiVersion: "v2",
});

(async () => {
  const response = await abound.taxes.retrieve(
    "<<testUserId>>",
    "2020"
  );
  
  console.log(response);
})();
import requests

url = "https://sandbox-api.withabound.com/v2/users/<<testUserId>>/taxes/2020"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <<apiKey>>"
}

response = requests.request("GET", url, headers=headers)

print(response.text)
// import com.squareup.okhttp.*;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://sandbox-api.withabound.com/v2/users/<<testUserId>>/taxes/2020")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <<apiKey>>")
  .build();

Response response = client.newCall(request).execute();
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://sandbox-api.withabound.com/v2/users/<<testUserId>>/taxes/2020"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <<apiKey>>")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}
// using RestSharp;

var client = new RestClient("https://sandbox-api.withabound.com/v2/users/<<testUserId>>/taxes/2020");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("Authorization", "Bearer <<apiKey>>");
IRestResponse response = client.Execute(request);
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox-api.withabound.com/v2/users/<<testUserId>>/taxes/2020")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'
request["Authorization"] = 'Bearer <<apiKey>>'

response = http.request(request)
puts response.read_body
{
  "data": {
    "1099Income": 85329.67,
    "effectiveTaxRate": 0.3203,
    "expenseDeduction": 15321.99,
    "federalIncomeTax": 11556.64,
    "federalTaxOutstanding": 21305.31,
    "federalTaxTotal": 21305.31,
    "filingState": "ca",
    "filingStatus": "single",
    "irsPayments": 0,
    "quarterlyPayments": 0,
    "marginalTaxRate": 0.4472,
    "medicareTax": 1847.79,
    "mileage": 1761.4,
    "mileageDeduction": 1012.8,
    "otherIrsPayments": 0,
    "otherStatePayments": 0,
    "otherTaxWithholdings": 0,
    "qbiDeduction": 12824.11,
    "selfEmploymentTax": 9748.67,
    "smartTaxRate": 0.3838,
    "socialSecurityTax": 7900.88,
    "stateIncomeTax": 6026.71,
    "stateTaxOutstanding": 6026.71,
    "stateTaxPayments": 0,
    "taxBalance": 27332.02,
    "taxWithholdings": 0,
    "taxWithholdingsPending": 0,
    "taxTotalOutstanding": 27332.02,
    "totalTax": 27332.02,
    "w2Income": 60000,
    "year": "2020"
  }
}

Field

Description

1099Income

The total annual 1099 income for the user. The tax totals returned are the taxes owed on this income.

expenseDeduction

The total business expense deduction for this user. Most business expenses are deducted at 100% of the expense value. However, it’s important to note that expenses related to categories, such as "Meals & Entertainment," are deducted at a different rate.

federalIncomeTax

The federal income tax owed on the user’s 1099 income. This is a graduated tax that is determined by the user’s filing status and income tax bracket.

filingState

The state in which the user earns their 1099 income (this is typically the state they live in). This value is used to calculate the user's stateIncomeTax.
The value should be the lowercase abbreviation of the state ("ca" for "California"). Default value is ca

filingStatus

The user's filing status, which determines the tax bracket to use for tax calculations. The possible values are single, married, marriedSeparately, and headOfHousehold.

quarterlyPayments

The total payments submitted to the IRS in the year.

smartTaxRate

The single rate at which Abound recommends your users withhold on outstanding (not yet withheld) 1099 income.

mileage

The total mileage driven for a current year. Used to calculate the mileageDeduction.

mileageDeduction

The total mileage deduction value for a current year.

selfEmploymentTax

The self-employment taxes owed on the user’s 1099 income. This is typically a flat rate of 15.3% that covers medicare (2.9%) and social security (12.4%).

stateIncomeTax

The state income tax owed on the user’s 1099 income. This is a graduated tax that is determined by the user’s filing status and income tax bracket. Seven states have no income tax (Alaska, Florida, Nevada, South Dakota, Texas, Washington and Wyoming).

taxWithholdings

The current tax withholding balance for your user. This value represents only settled funds and the max amount that can be withdrawn.
Only applicable if your user is using the Tax Withholding product.

taxWithholdingsPending

The amount of tax withholdings that have not settled yet. The value can be positive or negative based on the direction of the funds. For example, a non-settled withdrawal will show up as negative.
Only applicable if your user is using the Tax Withholding product.

totalTax

The sum of all the taxes owed across both federal and state.

w2Income

The user’s expected annual W2 income (if applicable). This number informs the tax bracket to be used when calculating the taxes owed on 1099 income. The taxes owed on this income are not included in the tax totals returned, as it is assumed to be already withheld by the employer.

year

The tax year in which the tax calculations are associated.


Did this page help you?