Manage payroll deductions

The QuickBooks Payroll API provides resources for managing payroll deductions. The information below describes how to use the resources to view the deduction associated with both an employer and an employee.

For details on each resource, see the the GraphQL Reference.

Read Employer Deductions

Scope: qb.payroll.benefits

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  query EmployerDeductionsQuery {
    payrollEmployerInfo {
      deductions {
        edges {
          node {
            id
            name
            category {
              description
            }
            statutoryType {
              description
              key
              value
            }
            subCategory {
              description
              key
              value
            }
            alternateIds {
              id
              nameSpace
            }
          }
        }
      }
    }
  }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
  {
    "data": {
      "payrollEmployerInfo": {
        "deductions": {
          "edges": [
            {
              "node": {
                "id": "01020000-0378-0000-9E00-002D5E34C987",
                "name": "YourDeductionName 401(k) Loan",
                "category": {
                  "description": "OTHER_TAXABLE_DEDUCTIONS_3P"
                },
                "statutoryType": {
                  "description": "TDED_CUS_EODLOEANREP3PTA",
                  "key": "TDED_CUS_EODLOEANREP3PTA",
                  "value": "TDED_CUS_EODLOEANREP3PTA"
                },
                "subCategory": {
                  "description": "Loan Repayment",
                  "key": "Loan Repayment",
                  "value": "Loan Repayment"
                },
                "alternateIds": [
                  {
                    "id": "djQuMTo5MTMwMzU5NDA4NTE3ODk2OjZlYWFkMDNkMWU:3000711",
                    "nameSpace": "Intuit.ems.v4"
                  }
                ]
              }
            }
          ]
        }
      }
    }
  }
Create Employer Deduction

Scope: qb.payroll.benefits

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
  mutation createEmployerDeduction($input: Payroll_CreateMiscDeductionPolicyInput!) {
    payrollCreateMiscDeductionPolicy(input: $input) {
      ... on Payroll_CreateMiscDeductionPolicySuccess {
        policy {
          id
          alternateIds {
            nameSpace
            id
          }
          name
          category {
            key
            description
            value
          }
          subCategory {
            key
            description
            value
          }
          statutoryType {
            key
            description
            value
          }
        }
      }
     ... on Payroll_DeductionError {
        employeeId
        message
        type
      }
    }
  }

Input variable

1
2
3
4
5
6
  {
   "input":{
      "name":"YourDeductionName Traditional 401(k)",
      "statutoryType":"TDED_CUS_EODLOEANREPTA"
    }
  }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
  {
    "data":{
      "payrollCreateMiscDeductionPolicy":{
         "policy":{
            "id":"01020000-0378-0000-3100-0030037AA127",
            "alternateIds": [
                  {
                  "nameSpace": "Intuit.sbseg.v4",
                          "id": "djQuMTo5MTMwMzYyNDY4ODIwODk2OjZlYWFkMDNkMWU:3186983"
                 }
            ],
          "name":"YourDeductionName Traditional 401(k)",
          "category":{
             "key":"OTHER_TAXABLE_DEDUCTIONS",
             "description":"OTHER_TAXABLE_DEDUCTIONS",
             "value":"OTHER_TAXABLE_DEDUCTIONS"
          },
          "subCategory":{
             "key":"DeductionItem.LoanRepayment.Desc",
             "description":"DeductionItem.LoanRepayment.Desc",
             "value":"DeductionItem.LoanRepayment.Desc"
          },
          "statutoryType":{
             "key":"TDED_CUS_EODLOEANREPTA",
             "description":"TDED_CUS_EODLOEANREPTA",
             "value":"TDED_CUS_EODLOEANREPTA"
          }
        }
      }
    }
  }
Update Employer Deductions

Scope: qb.payroll.benefits

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
  mutation updateMiscEmployerDeduction($input: Payroll_UpdateMiscDeductionPolicyInput!) {
    payrollUpdateMiscDeductionPolicy(input: $input) {
      ... on Payroll_UpdateMiscDeductionPolicySuccess {
        policy {
          id
          alternateIds {
            nameSpace
            id
          }
          name
          category {
            key
            description
            value
          }
          subCategory {
            key
            description
            value
          }
          statutoryType {
            key
            description
            value
          }
        }
      }
     ... on Payroll_DeductionError {
        employeeId
        message
        type
      }
    }
  }

Input variable

1
2
3
4
5
6
  {
   "input":{
      "name":"YourDeductionName Traditional 401(k) updated new",
      "id":"01020000-0378-0000-3100-0030037AA127"
    }
  }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
  {
    "data":{
      "payrollUpdateMiscDeductionPolicy":{
         "policy":{
            "id":"3186983",
            "alternateIds": [
                  {
                  "nameSpace": "Intuit.sbseg.v4",
                            "id": "djQuMTo5MTMwMzYyNDY4ODIwODk2OjZlYWFkMDNkMWU:3186983"
                 }
            ],
          "name":"YourDeductionName Traditional 401(k) updated new",
          "category":{
             "key":"OTHER_TAXABLE_DEDUCTIONS",
             "description":"OTHER_TAXABLE_DEDUCTIONS",
             "value":"OTHER_TAXABLE_DEDUCTIONS"
          },
          "subCategory":{
             "key":"Loan Repayment",
             "description":"Loan Repayment",
             "value":"Loan Repayment"
          },
          "statutoryType":{
             "key":"TDED_CUS_EODLOEANREPTA",
             "description":"TDED_CUS_EODLOEANREPTA",
             "value":"TDED_CUS_EODLOEANREPTA"
          }
        }
      }
    }
  }
Read Employee Deductions

Scope: qb.payroll.benefits

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
  query EmployeeDeductionQuery( $filter: WorkerManagement_EmployeeConnectionFilter) {
    workerManagementEmployees(filter: $filter) {
      edges {
        node {
          id
          firstName
          lastName
          alternateIds {
            id
            nameSpace
          }
          employmentStatus {
            active
            detailedStatus
          }
          payrollEmployeeDetails {
            workLocation {
              id
              alternateIds {
                id
                nameSpace
              }
              addressComponents {
                streetAddressLine1
                city
                state
                country
              }
            }

            deductions {
              id
              active
              alternateIds {
                id
                nameSpace
              }
              employeeContribution {
                amount {
                  value
                  type
                }
                capping {
                  amount {
                    value
                    type
                  }
                  frequency
                }
                frequency
              }
              employerContribution {
                amount {
                  type
                  value
                }
                capping {
                  amount {
                    type
                    value
                  }
                  frequency
                }
                frequency
              }
              deductionPolicy {
                id
                name
                statutoryType {
                  key
                  description
                  value
                }

                subCategory {
                  key
                  value
                  description
                }
              }
            }
          }
        }
      }
    }
  }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
  {
    "data": {
      "workerManagementEmployees": {
        "edges": [
          {
            "node": {
              "id": "6",
              "firstName": "test1",
              "lastName": "jam1",
              "alternateIds": [
                {
                  "id": "djQuMTo5MTMwMzU5NDA4NTE3ODk2OjlkNjk5ZTk2MDg:002071e4737d650c7246f89ba1cc5851e7f3c7",
                  "nameSpace": "Intuit.sbseg.v4"
                }
              ],
              "employmentStatus": {
                "active": true,
                "detailedStatus": "PAID_LEAVE"
              },
              "payrollEmployeeDetails": {
                "workLocation": {
                  "id": "01020000-0338-0000-0400-035E633F8497",
                  "alternateIds": null,
                  "addressComponents": {
                    "streetAddressLine1": "2700 Coast Ave",
                    "city": "Mountain View",
                    "state": "CA",
                    "country": null
                  }
                },
                "deductions": []
              }
            }
          }
        ]
      }
    }
  }
Create Employee Deductions

Scope: qb.payroll.benefits

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
  mutation CreateEmployeeDeduction( $input: Payroll_CreateEmployeeMiscDeductionInput!) {
    payrollCreateEmployeeMiscDeduction(input: $input) {
      ... on Payroll_CreateEmployeeMiscDeductionSuccess {
        deduction {
          alternateIds {
            nameSpace
            id
          }
          employerContribution {
            frequency
            capping {
              amount {
                value
                type
              }
              frequency
            }
            amount {
              type
              value
            }
          }
          employeeContribution {
            frequency
            capping {
              frequency
              amount {
                value
                type
              }
            }
            amount {
              value
              type
            }
          }
          id
          active
        }
      }
    }
  }

Input variable

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
  {
    "input": {
      "employeeId": "5",
      "employeeDeductionDetails": {
        "existingDeductionPolicyId": "01020000-0378-0000-6D00-002EDC0843FB2",
        "contribution": {
          "employerContributionInput": {
            "amount": {
              "type": "FIXED",
              "value": "10"
            },
            "frequency": "PER_PAYSLIP",
            "capping": {
              "amount": {
                "type": "FIXED",
                "value": "100"
              }
            }
          },
          "employeeContributionInput": {
            "amount": {
              "type": "FIXED",
              "value": "20"
            },
            "frequency": "PER_PAYSLIP",
            "capping": {
              "amount": {
                "type": "FIXED",
                "value": "200"
              }
            }
          }
        }
      }
    }
  }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
  {
   "data": {
     "payrollCreateEmployeeMiscDeduction": {
       "deduction": {
         "alternateIds": [],
         "employerContribution": {
             "frequency": "PER_PAYSLIP",
             "capping": {
                 "amount": {
                     "value": "100",
                     "type": "FIXED"
                 },
                 "frequency": "BY_CALENDAR_YEAR"
             },
             "amount": {
                 "type": "FIXED",
                 "value": "10"
             }
         },
         "employeeContribution": {
             "frequency": "PER_PAYSLIP",
             "capping": {
                 "frequency": "BY_CALENDAR_YEAR",
                 "amount": {
                     "value": "200",
                     "type": "FIXED"
                 }
             },
             "amount": {
                 "value": "20",
                 "type": "FIXED"
             }
         },
         "id": "01821446-0369-BA20-C000-FF6F1A15FC63",
         "active": true
        }
      }
    }
  }
Update Employee Deductions

Scope: qb.payroll.benefits

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
  mutation updateEmployeeDeduction($input: Payroll_UpdateEmployeeMiscDeductionInput!) {
   payrollUpdateEmployeeMiscDeduction(input: $input) {
      ... on Payroll_UpdateEmployeeMiscDeductionSuccess {
        deduction {
          id
          active
          employeeContribution {
            amount {
              value
              type
            }
            capping {
              frequency
              amount {
                type
                value
              }
            }
            frequency
          }
          employerContribution {
            frequency
            capping {
              amount {
                value
                type
              }
              frequency
            }
            amount {
              type
              value
            }
          }
          alternateIds {
            id
            nameSpace
          }
        }
      }
    }
  }

Input variable

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
  {
   "input": {
     "employeeDeductionDetails": {
       "employeeContributionInput": {
         "amount": {
             "type": "FIXED",
             "value": "200"
         },
         "capping": {
             "amount": {
                 "type": "FIXED",
                 "value": "200"
             }
         },
         "frequency": "PER_PAYSLIP"
     },
     "employeeDeductionId": "01821447-0369-0C64-6200-878DBAED55AB",
     "employerContributionInput": {
         "amount": {
             "type": "FIXED",
             "value": "10"
         },
         "capping": {
             "amount": {
                 "type": "FIXED",
                 "value": "100"
             }
         },
         "frequency": "PER_PAYSLIP"
       }
     },
     "employeeId": "20"
   }
  }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
  {
   "data": {
     "payrollUpdateEmployeeMiscDeduction": {
       "deduction": {
         "id": "01821447-0369-0C64-6200-878DBAED55AB",
         "active": true,
         "employeeContribution": {
             "amount": {
                 "value": "200",
                 "type": "FIXED"
             },
             "capping": {
                 "frequency": "BY_CALENDAR_YEAR",
                 "amount": {
                     "type": "FIXED",
                     "value": "200"
                 }
             },
             "frequency": "PER_PAYSLIP"
         },
         "employerContribution": {
             "frequency": "PER_PAYSLIP",
             "capping": {
                 "amount": {
                     "value": "100",
                     "type": "FIXED"
                 },
                 "frequency": "BY_CALENDAR_YEAR"
             },
             "amount": {
                 "type": "FIXED",
                 "value": "10"
             }
         },
         "alternateIds": []
       }
     }
   }
  }
Delete Employee Deduction

Scope: qb.payroll.benefits

Request

1
2
3
4
5
6
7
  mutation DeleteEmployeePension($input: Payroll_DeleteEmployeeMiscDeductionInput!) {
    payrollDeleteEmployeeMiscDeduction(input: $input){
      ... on Payroll_DeleteEmployeeMiscDeductionSuccess {
        Id
      }
    }
  }

Input variable

1
2
3
4
5
6
  {
    "input": {
      "employeeId": "01020000-0340-0000-A200-0155368C4534",
      "employeeDeductionId": "0102031A-0370-94F6-2E00-FB0EC78B305D"
    }
  }

Response

1
2
3
4
5
6
7
  {
    "data": {
       "payrollDeleteEmployeePension": {
         "id": "01821447-0369-0C64-8100-878E49D1B05D"
       }
     }
  }