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" }
    ]
}

Submit

• Request with an override for federal exemptions:

{
  "earnings": 4000,
  "taxlist":
    [
      { "taxname": "federal income tax", "exemptions": 2500 },
      { "taxname": "fica ss" },
      { "taxname": "fica med" }
    ]
}

Submit

• 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 }
        ]
    }

Submit