Calculation for a batch of taxes
http://3.213.184.41:8000/batch_taxamount
You should also include a header for Content-Type: application/json.
TaxBatch:
{
"paydate": string,
"payperiods": integer,
"earnings": number,
"supplemental": boolean,
"ytdearnings": number,
"exemptions": integer,
"stateexemptions": integer,
"filingstatus": integer,
"unemploymentrate": number,
"round": boolean,
"companyzip": integer,
"taxlist": TaxInfo[] (required)
}
All keys are optional unless specifically designated as required.
| parameter | Description |
| paydate | Check date in the form YYYY-mm-dd. Defaults to current date. |
| payperiods | Number of pay periods per year. Defaults to 12 (monthly). |
| earnings | Gross taxable earnings for the pay period. Defaults to 0. |
| supplemental | A true value indicates a non-regular or bonus payment. Defaults to false. |
| ytdearnings | YTD earnings paid PRIOR TO the current pay period. Defaults to 0. |
| exemptions | Employee's federal exemptions. Defaults to 0. |
| stateexemptions | Employee's state exemptions. Defaults to 0. |
| filingstatus | 0 - Single (default)
1 - Head of Household
2 - Widow(er)
3 - Married Filing Jointly
4 - Married Filing Separately
5 - Married Both Employed
|
| unemploymentrate | Employer's unemployment rate, expressed as a floating point (e.g., 2.4% => 0.024). Defaults to 0. |
| round | A true value requests rounding of tax amounts which may be optionally rounded. Defaults to false. |
| companyzip | Set to employer ZIP code for unemployment tax purposes. Required only for FUTA calculation. |
| taxlist | A JSON array of TaxInfo objects (described below). |
TaxInfo:
{
"taxname": string (required),
"ytdtax": number,
"miscellaneous": number,
"auxiliary": number,
"paydate": string,
"payperiods": integer,
"supplemental": boolean,
"ytdearnings": number,
"exemptions": integer,
"stateexemptions": integer,
"filingstatus": integer,
"unemploymentrate": number,
"round": boolean,
"companyzip": integer
}
| parameter | Description |
| taxname | The name of the tax to be computed for this entry of the batch. |
| ytdtax | YTD taxes (for this taxname) paid PRIOR TO the current pay period. Defaults to 0. |
| miscellaneous | Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty miscellaneous_instructions property. Defaults to 0. |
| auxiliary | Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty auxiliary_instructions property. Defaults to 0. |
| ... | The remaining parameters are for overriding the corresponding parameter in the enclosing TaxBatch for this entry of the batch. |
Result:
{
"status": string ("ok" | "error")
"value": BatchResponse | error message
}
BatchResponse:
{
"earnings": number,
"net": number,
"taxes": TaxResponse[]
}
| Key | Description |
| earnings | Same as the earnings passed in the request. |
| net | The calculated net pay for this batch. |
| taxes | An array of TaxResponse objects, one for each entry in the TaxBatch request. |
TaxResponse:
{
"taxname": string,
"amount": number,
"taxtype": string,
"withheld": boolean
}
| Key | Description |
| taxname | The name of the tax for this entry of the batch. |
| amount | The resulting computed amount for this tax. |
| taxtype | The taxtype (F, S, L, O, or P) for this tax. |
| withheld | True if this tax should be withheld from employee pay, false if tax is paid by the employer. |
Example request JSON
Note that this request takes the default value for several keys, including "exemptions", "payperiods", and "supplemental". By including exemptions in the "fit" TaxInfo object, this calculation gets a value of 2 while the other tax entries get the default value of 0.
{
"earnings": 3000,
"ytdearnings": 2000,
"filingstatus": 1,
"stateexemptions": 1,
"paydate": "2022-01-01",
"companyzip": 10001,
"unemploymentrate": 0.052,
"round": true,
"taxlist":
[
{ "taxname": "fit", "exemptions": 2 },
{ "taxname": "fica med" },
{ "taxname": "futa", "ytdearnings": 6000, "auxiliary": 1 }
]
}
This request would result in the following response (based on 2021 tables):
{
"status":"ok",
"value": {
"earnings":3000.0,
"net":2814.5,
"taxes":
[
{"amount":142.0,"taxname":"fit","taxtype":"F","withheld":true},
{"amount":43.5,"taxname":"fica med","taxtype":"F","withheld":true},
{"amount":60.0,"taxname":"futa","taxtype":"O","withheld":false}
]
}
}