The QuickBooks Payroll API provides resources for managing benefits. The examples below demonstrate how to use the resources to view the benefits associated with both an employer and an employee.
For details on each resource, see the the GraphQL Reference.
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 | query EmployerBenefitsQuery($first: Int
$after: String
){
payrollEmployerInfo {
benefits(first: $first, after: $after) {
pageInfo {
endCursor
hasNextPage
hasPreviousPage
startCursor
}
edges {
node {
id
name
category {
description
key
value
}
statutoryType {
description
key
value
}
subCategory {
description
key
value
}
}
}
}
deductions {
edges {
node {
id
name
category {
description
key
value
}
statutoryType {
description
key
value
}
subCategory {
description
key
value
}
}
}
}
}
}
|
Input variable
Note: If you have four elements and specify “after 0”, you will get records 2-4.
1 2 3 4 | { "first": 10, "after": "-1" } |
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 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 | { "data":{ "payrollEmployerInfo":{ "benefits":[ { "id":"01020000-0378-0000-8600-002FDD66E3BF", "name":"YourBenefitName PPO", "category":{ "description":"HEALTH_INSURANCE", "key":"HEALTH_INSURANCE", "value":"HEALTH_INSURANCE" }, "statutoryType":{ "description":"TDED_CUS_EHIMEDPT", "key":"TDED_CUS_EHIMEDPT", "value":"TDED_CUS_EHIMEDPT" }, "subCategory":{ "description":"Medical Insurance", "key":"Medical Insurance", "value":"Medical Insurance" } } ] }, "deductions":{ "edges":[ { "node":{ "id":"01020000-0378-0000-FD00-0030F16F5555", "name":"FSA", "category":{ "description":"FLEXIBLE_SPENDING_PLANS", "key":"FLEXIBLE_SPENDING_PLANS", "value":"FLEXIBLE_SPENDING_PLANS" }, "statutoryType":{ "description":"TDED_CUS_EFSMEDEXPPT", "key":"TDED_CUS_EFSMEDEXPPT", "value":"TDED_CUS_EFSMEDEXPPT" }, "subCategory":{ "description":"Medical Expense FSA", "key":"Medical Expense FSA", "value":"Medical Expense FSA" } } }, { "node":{ "id":"01020000-0378-0000-8600-003025C05554", "name":"Test hsa", "category":{ "description":"HSA_PLANS", "key":"HSA_PLANS", "value":"HSA_PLANS" }, "statutoryType":{ "description":"TDED_CUS_EHSPREPT", "key":"TDED_CUS_EHSPREPT", "value":"TDED_CUS_EHSPREPT" }, "subCategory":{ "description":"Pretax HSA", "key":"Pretax HSA", "value":"Pretax HSA" } } } ] } } } |
Create Employer benefits, such as medical, dental, or insurance.
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 | mutation createEmployerBenefit($input: Payroll_CreateBenefitPolicyInput!) {
payrollCreateBenefitPolicy(input: $input) {
... on Payroll_CreateBenefitPolicyPayloadSuccess {
policy {
id
name
statutoryType {
description
}
category {
description
}
}
}
... on Payroll_CreateBenefitPolicyPayloadError {
code
message
type
}
}
}
|
Input variables
Medical
1 2 3 4 5 6 | { "input": { "name": "YourBenefitName Medical", "statutoryType": "TDED_CUS_EHIMEDPT" } } |
Vision
1 2 3 4 5 6 | { "input": { "name": "YourBenefitName Vision", "statutoryType": "TDED_CUS_EHIVISPT" } } |
Dental
1 2 3 4 5 6 | { "input": { "name": "YourBenefitName Dental", "statutoryType": "TDED_CUS_EHIDENPT" } } |
HSA
1 2 3 4 5 6 | { "input": { "name": "YourBenefitName HSA", "statutoryType": "TDED_CUS_EHSPREPT" } } |
FSA
1 2 3 4 5 6 | { "input": { "name": "YourBenefitName FSA", "statutoryType": "TDED_CUS_EFSMEDEXPPT" } } |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | Success:
{
"data": {
"payrollCreateBenefitPolicy": {
"policy": {
"id": "40820000-0370-0000-3F00-002E3160F692",
"name": "YourBenefitName Medical",
"statutoryType": {
"description": "TDED_CUS_EHIMEDTA"
},
"category": {
"description": "HEALTH_INSURANCE"
}
}
}
}
}
|
1 2 3 4 5 6 7 8 9 10 11 | Error:
{
"data": {
"payrollCreateBenefitPolicy": {
"code": "0",
"message": "Some error message",
"type": "INVALID_REQUEST"
}
}
}
|
Update Employer benefits, such as medical, dental, or insurance.
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 | mutation updateBenefitPolicy($input: Payroll_UpdateBenefitPolicyInput!) {
payrollUpdateBenefitPolicy(input: $input) {
... on Payroll_UpdateBenefitPolicyPayloadSuccess {
policy {
id
name
category {
description
}
subCategory {
description
}
statutoryType {
description
}
}
}
... on Payroll_UpdateBenefitPolicyPayloadError {
code
message
type
}
|
Input variables
1 2 3 4 5 6 | { "input": { "name": "YourBenefitName Medical 10", "id": "40820000-0370-0000-4D00-002E154EF62A", } } |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | Success:
{
"data": {
"payrollUpdateBenefitPolicy": {
"policy": {
"id": "40820000-0370-0000-3F00-002E3160F692",
"name": "YourBenefitName Medical 10",
"category": {
"description": "HEALTH_INSURANCE"
},
"subCategory": {
"description": "Medical Insurance"
},
"statutoryType": {
"description": "TDED_CUS_EHIMEDTA"
}
}
}
}
}
|
1 2 3 4 5 6 7 8 9 10 11 | Error:
{
"data": {
"payrollUpdateBenefitPolicy": {
"code": "0",
"message": "Some error message",
"type": "INVALID_REQUEST"
}
}
}
|
Allows reading Employee benefits info.
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 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | query EmployeeBenefitQuery(
$first: Int
$after: String
$filter: WorkerManagement_EmployeeConnectionFilter
) {
workerManagementEmployees(first: $first, after: $after, filter: $filter) {
edges {
node {
id
alternateIds {
id
nameSpace
}
payrollEmployeeDetails {
benefits {
id
active
deductionPolicy {
id
name
category {
description
key
value
}
subCategory {
description
key
value
}
statutoryType {
description
key
value
}
}
employeeContribution {
amount {
type
value
}
capping {
amount {
value
type
}
frequency
}
frequency
}
employerContribution {
amount {
type
value
}
capping {
amount {
value
type
}
frequency
}
frequency
}
}
deductions{
id
active
deductionPolicy {
id
name
category {
description
key
value
}
subCategory {
description
key
value
}
statutoryType {
description
key
value
}
}
employeeContribution {
amount {
type
value
}
capping {
amount {
value
type
}
frequency
}
frequency
}
employerContribution {
amount {
type
value
}
capping {
amount {
value
type
}
frequency
}
frequency
}
}
}
}
}
}
}
|
Input variable
Note: If you have four elements and specify “after 0”, you will get records 2-4.
1 2 3 4 5 6 7 8 9 10 11 | { "first": 10, "after": "-1", "filter": { "employmentStatus": { "active": { "eq": true } } } } |
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 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 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 | { "data": { "workerManagementEmployees": { "edges": [ { "node": { "id": "1", "alternateIds": [ { "id": "1", "nameSpace": "Intuit.sbe.salsa.default" }, { "id": "01020000-0340-0000-E500-019508B8F4D6", "nameSpace": "Intuit.ems.iop" } ], "payrollEmployeeDetails": { "benefits": [ { "id": "010203B1-0370-30DD-8300-4B705E7B7C24", "active": true, "deductionPolicy": { "id": "01020000-0378-0000-1100-002F9C57E424", "name": "updatedName3 ", "category": { "description": "HEALTH_INSURANCE", "key": "HEALTH_INSURANCE", "value": "HEALTH_INSURANCE" }, "subCategory": { "description": "Medical Insurance", "key": "Medical Insurance", "value": "Medical Insurance" }, "statutoryType": { "description": "TDED_CUS_EHIMEDPT", "key": "TDED_CUS_EHIMEDPT", "value": "TDED_CUS_EHIMEDPT" } }, "employeeContribution": { "amount": { "type": "FIXED", "value": "10" }, "capping": { "amount": { "value": "10", "type": "FIXED" }, "frequency": "BY_CALENDAR_YEAR" }, "frequency": "PER_PAYSLIP" }, "employerContribution": { "amount": { "type": "FIXED", "value": "20" }, "capping": null, "frequency": "PER_PAYSLIP" } } ], "deductions": [ { "id": "01020000-0370-0002-5500-543CF9353954", "active": true, "deductionPolicy": { "id": "01020000-0378-0000-8600-003025C05554", "name": "Test hsa", "category": { "description": "HSA_PLANS", "key": "HSA_PLANS", "value": "HSA_PLANS" }, "subCategory": { "description": "Pretax HSA", "key": "Pretax HSA", "value": "Pretax HSA" }, "statutoryType": { "description": "TDED_CUS_EHSPREPT", "key": "TDED_CUS_EHSPREPT", "value": "TDED_CUS_EHSPREPT" } }, "employeeContribution": { "amount": { "type": "FIXED", "value": "200" }, "capping": { "amount": { "value": "2000", "type": "FIXED" }, "frequency": "BY_CALENDAR_YEAR" }, "frequency": "PER_PAYSLIP" }, "employerContribution": null }, { "id": "01020000-0370-0002-AA00-543C30853955", "active": true, "deductionPolicy": { "id": "01020000-0378-0000-FD00-0030F16F5555", "name": "FSA", "category": { "description": "FLEXIBLE_SPENDING_PLANS", "key": "FLEXIBLE_SPENDING_PLANS", "value": "FLEXIBLE_SPENDING_PLANS" }, "subCategory": { "description": "Medical Expense FSA", "key": "Medical Expense FSA", "value": "Medical Expense FSA" }, "statutoryType": { "description": "TDED_CUS_EFSMEDEXPPT", "key": "TDED_CUS_EFSMEDEXPPT", "value": "TDED_CUS_EFSMEDEXPPT" } }, "employeeContribution": { "amount": { "type": "FIXED", "value": "200" }, "capping": { "amount": { "value": "2000", "type": "FIXED" }, "frequency": "BY_CALENDAR_YEAR" }, "frequency": "PER_PAYSLIP" }, "employerContribution": null } ] } } } ] } } } |
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 | mutation createEmployeeBenefit($input: Payroll_CreateEmployeeBenefitInput!) {
payrollCreateEmployeeBenefit(input: $input) {
... on Payroll_CreateEmployeeBenefitPayloadSuccess {
deduction {
id
active
deductionPolicy {
id
name
category {
description
}
subCategory {
description
}
statutoryType {
description
}
}
employeeContribution {
amount {
type
value
}
frequency
capping {
amount {
type
value
}
frequency
}
}
employerContribution {
amount {
type
value
}
frequency
capping {
amount {
type
value
}
frequency
}
}
}
}
... on Payroll_CreateEmployeeBenefitPayloadError {
code
type
message
}
}
}
|
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":"01020000-0340-0000-2B00-018B95AC7BB4", "employeeDeductionDetails": { "existingDeductionPolicyId": "123", "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 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | Success:
{
"data": {
"payrollCreateEmployeeBenefit": {
"deduction": {
"id": "010203B8-0370-9924-0C00-87B4CB401460",
"active": true,
"deductionPolicy": {
"id": "01020000-0378-0000-6E00-002F0E99F460",
"name": "YourBenefitName Medical",
"category": {
"description": "HEALTH_INSURANCE"
},
"subCategory": {
"description": "Medical Insurance"
},
"statutoryType": {
"description": "TDED_CUS_EHIMEDTA"
}
},
"employeeContribution": {
"amount": {
"type": "FIXED",
"value": "20"
},
"frequency": "PER_PAYSLIP",
"capping": {
"amount": {
"type": "FIXED",
"value": "200"
},
"frequency": "BY_CALENDAR_YEAR"
}
},
"employerContribution": {
"amount": {
"type": "FIXED",
"value": "10"
},
"frequency": "PER_PAYSLIP",
"capping": {
"amount": {
"type": "FIXED",
"value": "100"
},
"frequency": "BY_CALENDAR_YEAR"
}
}
}
}
}
}
|
1 2 3 4 5 6 7 8 9 10 11 | Error:
{
"data": {
"payrollCreateEmployeeBenefit": {
"code": "0",
"message": "Some error message",
"type": "INVALID_REQUEST"
}
}
}
|
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 | mutation PayrollUpdateEmployeeBenefit($input: Payroll_UpdateEmployeeBenefitInput!) {
payrollUpdateEmployeeBenefit(input: $input) {
... on Payroll_UpdateEmployeeBenefitPayloadSuccess {
deduction {
active
deductionPolicy {
category {
description
}
id
name
statutoryType {
description
}
subCategory {
description
}
}
employeeContribution {
amount {
type
value
}
capping {
amount {
type
value
}
frequency
}
frequency
}
employerContribution {
amount {
value
type
}
capping {
amount {
value
type
}
frequency
}
frequency
}
id
}
}
... on Payroll_UpdateEmployeeBenefitPayloadError {
code
employeeDeductionId
employeeId
employerDeductionId
message
type
}
}
}
|
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": { "value": "123", "type": "FIXED" }, "capping": { "amount": { "value": "123", "type": "FIXED" } }, "frequency": "PER_HOUR" }, "employeeDeductionId": "01821446-0369-BA20-FA00-FF6CAA1A9", "employerContributionInput": { "amount": { "value": "123", "type": "FIXED" }, "capping": { "amount": { "value": "123", "type": "FIXED" } }, "frequency": "PER_PAYSLIP" } }, "employeeId": "21" } } |
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 40 41 42 43 44 45 46 47 48 49 50 51 | { "data": { "payrollUpdateEmployeeBenefit": { "deduction": { "active": true, "deductionPolicy": { "category": { "description": "HEALTH_INSURANCE" }, "id": "01820000-0371-0000-4A00-00EB42ECF9A9", "name": "MyName Medical", "statutoryType": { "description": "TDED_CUS_EHIMEDPT" }, "subCategory": { "description": "Medical Insurance" } }, "employeeContribution": { "amount": { "type": "FIXED", "value": "123" }, "capping": { "amount": { "type": "FIXED", "value": "123" }, "frequency": "BY_CALENDAR_YEAR" }, "frequency": "PER_HOUR" }, "employerContribution": { "amount": { "value": "123", "type": "FIXED" }, "capping": { "amount": { "value": "123", "type": "FIXED" }, "frequency": "BY_CALENDAR_YEAR" }, "frequency": "PER_PAYSLIP" }, "id": "01821446-0369-BA20-FA00-FF6CAA1A9" } } } } |
Scope: qb.payroll.benefits
Request
1 2 3 4 5 6 7 8 9 10 11 12 | mutation DisableEmployeeBenefit($input: Payroll_DisableEmployeeBenefitInput!) {
payrollDisableEmployeeBenefit(input: $input) {
... on Payroll_DisableEmployeeBenefitPayloadSuccess {
id
}
... on Payroll_DisableEmployeeBenefitPayloadError {
type
message
code
}
}
}
|
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": { "payrollDisableEmployeeBenefit": { "id": "01821446-0369-BA20-FA00-FF6EB3CAA1A9" } } } |