Working with tax parameter settings

Applied For

As mentioned in a previous section of this guide, marking a parameter as applied for enables us to skip the value submission of a particular tax parameter. This is particularly useful for when customers do not have state or federal account numbers while signing up. In this case they will be able to mark the parameter setting as applied for and will be able to update it when they receive it from the state agency. This field has three specific states:

• true: As long as the value is true, any attempt to collect a setting value will return a validation error. In order to start collecting setting values we must set this value as false in the same request body.
• false: As long as the value is false, all attempts to collect a setting value will require the actual value to be supplied in the request body.
• null: Only possible if the tax parameter can_be_applied_for=false, and will raise validation errors on every attempt to set the applied for flag to true.

Effective Dating

Most of the tax parameters exposed through this API will have an effective start date component attached to them, this is informed by the attribute effective_datable=true. Effective start dates define the lower boundary of a temporal range for which the value is applicable.

Consider the following examples.

Example 1: We create the first tax parameter setting; the value will be effective from 1900-01-01 until a time in the far future.

Example 2: We add a tax parameter setting effective from 2022-04-01 onwards. This forces the first param to have a date range of 1900-01-01 to 2022-02-01, not including the last date.

Example 3: Finally, we realized that we missed a tax parameter setting value effective from 2021-08-01 so we go ahead and add it. This will force the first range to end on 2021-08-01 and will create a new range from 2021-08-01 until 2022-04-01 not including that last date.

Dependencies

Some setup parameters contain a special attribute called depends_on. An example could look like the following:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "spa_X8r62qFbr9u2Mn9qBDwG",
      "label": "Massachusetts Family and Medical Leave EIN",
      "description": "Massachusetts Family and Medical Leave EIN",
      "name": "massachusetts_family_medical_leave_ein",
      "type": "string",
      "options": null,
      "depends_on": {
        "name": "private_plan_exemption",
        "id": "spa_TVOClgLUlBrug59xHdFr",
        "value_matches": [
          "false"
        ]
      },
      "editable": true,
      "effective_datable": true,
      "can_be_applied_for": true,
      "jurisdiction": "jur_CB5PYzMGoBVmSxpuhDX0",
      "tax": "tax_afRJqY785WwYH0PrtFde",
      "setting": null
    },
    ...,
  ]
}

This means that collecting these kinds of settings should only happen when the value collected from the dependency matches any of the values included in the value_matches array.

For example; the tax parameter setting included in the response shown above should not be collected if the tax parameter whose name is private_plan_exemption has a value of false.