Batch tax calculation
To get properties for multiple taxes in one network call, you can use the following endpoint:
Note: This endpoint requires a POST request with a <TaxBatch>
JSON body:
TaxBatch:
{ paydate?: string, payperiods?: integer, earnings: number, supplemental?: boolean, ytdearnings?: number, exemptions?: number, stateexemptions?: number, filingstatus?: integer, unemploymentrate?: number, // required for FUTA, SUTA round?: boolean, companyzip: integer, // required for FUTA taxlist: [ { taxname: string, // required ytdtax?: number, miscellaneous?: number, auxiliary?: number, earnings?: number, // overrides outer value paydate?: string, // overrides outer value payperiods?: integer, // overrides outer value supplemental?: boolean, // overrides outer value ytdearnings?: number, // overrides outer value exemptions?: integer, // overrides outer value stateexemptions?: integer, // overrides outer value filingstatus?: integer, // overrides outer value unemploymentrate?: number, // overrides outer value round?: boolean, // overrides outer value companyzip?: integer // overrides outer value }, ... ]}
All keys are optional unless specifically noted as required.
Parameter | Description | Default |
---|---|---|
paydate | Check date in the form YYYY-mm-dd. | current date. |
payperiods | Number of pay periods per year. | 12 (monthly) |
earnings | Gross taxable earnings for the pay period. | 0 |
supplemental | A true value indicates a non-regular or bonus payment. | false |
ytdearnings | YTD earnings paid PRIOR TO the current pay period. | 0 |
exemptions | Employee’s federal exemptions. | 0 |
stateexemptions | Employee’s state exemptions. | 0 |
filingstatus | Employee’s federal filing status. | 0 |
unemploymentrate | Employer’s unemployment rate, expressed as a floating point (e.g., 2.4% => 0.024). | 0 |
round | A true value requests rounding of tax amounts which may be optionally rounded. | false |
companyzip | Set to employer ZIP code for unemployment tax purposes. Required only for FUTA calculation. | no default |
taxlist entries:
Parameter | Description | Default |
---|---|---|
taxname | The name of the tax to be computed for this entry of the batch. | n/a |
ytdtax | YTD taxes (for this taxname) paid PRIOR TO the current pay period. | 0 |
miscellaneous | Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty miscellaneous_instructions property. | 0 |
auxiliary | Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty auxiliary_instructions property. | 0 |
… | The remaining parameters are for overriding the corresponding parameter in the enclosing TaxBatch for this tax. |
Results:
{ status: "error" value: string // error message}
or
{ status: "ok", value: { earnings: number, net: number, taxes: [ { taxname: string, // tax name amount: number, // computed amount taxtype: string, // tax type withheld: boolean // true if tax is withheld }, ... ] }}
Examples
- Minimal request, which takes the default values for most properties:
{ "earnings": 4000, "taxlist": [ { "taxname": "federal income tax" }, { "taxname": "fica ss" }, { "taxname": "fica med" } ]}
- Request with an override for federal exemptions:
{ "earnings": 4000, "taxlist": [ { "taxname": "federal income tax", "exemptions": 2500 }, { "taxname": "fica ss" }, { "taxname": "fica med" } ]}
- A more typical example:
{ "earnings": 1680, "payperiods": 52, "ytdearnings": 1680, "filingstatus": 3, "unemploymentrate": 0.024, "round": true, "companyzip": 47838, "taxlist":[ { "taxname": "federal income tax", "exemptions": 2500, "stateexemptions": 0, "miscellaneous": 0, // W-4 line 4a - 4b "auxiliary": 0 // W-4 step2c }, { "taxname": "fica ss", "exemptions": 0, "stateexemptions": 0, "miscellaneous": 0, "auxiliary": 0 }, { "taxname": "fica med", "exemptions": 0, "stateexemptions": 0, "miscellaneous": 0, "auxiliary": 0 }, { "taxname": "futa with credit reduction", "exemptions": 0, "stateexemptions": 0, "miscellaneous": 40.32, // SUTA per period "auxiliary": 2}, // normal+additional credits { "taxname": "IN", "exemptions": 0, // first-time exempts "stateexemptions": 2, // personal exempts "miscellaneous": 0, // dependent exempts "auxiliary": 0 }, // adoption exempts { "taxname": "IN unemployment", "exemptions": 0, "stateexemptions": 0, "miscellaneous": 0, "auxiliary": 0 }, { "taxname": "IN Sullivan Co.", "exemptions": 0, "stateexemptions": 0, "miscellaneous": 0, "auxiliary": 0 } ] }