Pay Components

Verbs supported: POST

POST: Add a single pay component to the worker. This pay component will be used for apply recurring pay components on a workers check based on the frequency specified. Currently this only supports the ability to POST reduction type pay components.

EndpointDescription
https://api.paychex.com/workers/{workerId}/paycomponentsAdd a pay component to a worker that will be a recurring deduction.


Request (Body):

Element NameTypeDescription
componentIDstringThe unique identifier of the pay component.
calculationTypestringThe type of calculation that will be applied for the pay component .
  • FLAT_DOLLAR_AMOUNT: This is used for a specific dollar amount.
  • PERCENTAGE: This is used for when a Percentage will be used to calculate the amount and will need a calculationBaseId to specify what to apply against.
  • RATE_X_UNITS: This is used for apply the rate against units and will need a calculationBaseId to specify what to apply against.
  • RATE_X_HOURS: This is used for apply the rate against hours and will need a calculationBaseId to specify what to apply against.
calculationBaseIdstringThis is required if you are not using a FLAT_DOLLAR_AMOUNT Calculation Type.
valuenumberThis is used to specify the value that is used against the calculationType.
startDatedateDate which this pay component will start to be applied during the payruns. This is an optional field that default to current datetime if not provided. This cannot be backdated but can be added to start in the future.
endDatedateDate which this pay component will stop being applied. This is an optional field that default to null if not provided. This cannot be backdated but can be added to end in the future.
frequencyobjectYou will define how often the pay component will be applied during the payruns.


Frequency

You can cross reference the workers payFrequency against the occurrences to determine what values are applicable.

Element NameTypeDescription
appliedstringCurrently we only support a BY_PAY_PERIOD value for the API.
occurrencestringThis is how often the pay component will be applied on the pay run. The available values for this will depend on the payFrequency that a worker is paid which can be found on the worker compensations pay standards.
occuranceIntervalsobjectThese are sub intervals that are used for occurrences that are larger in duration that allow you to define when to apply the pay component. You can reference the payFrequency and occurance to determine what intervals and values applicable.
effectedChecksstringWhich check(s) within the payrun that the paycomponent will be applied to.
  • FIRST_CHECK: The Pay Component will be applied to the first check for the worker within the pay run. This is used for a pay component that only should be applied once like a health insurance deduction.
  • EVERY_CHECK: The Pay Component will be applied to all of the checks for the worker within the pay run. This is used for a pay component that is applied on all check like a retirement deduction.
{
        "componentId": "00H2A1IUJE7MXV6TQ37U",
        "calculationType": "PERCENTAGE",
        "calculationBaseId": "1174507",
        "value": 15,
        "startDate": "2018-01-22T00:00:00Z",
        "endDate": "2018-12-22T00:00:00Z",
        "frequency": "EVERY_PAY_PERIOD",
        "applied": "BY_PAY_PERIOD",
        "occurrence": "QUARTERLY",
        "occurrenceIntervals": {
            "interval1": "2",
            "interval2": "1"
                },
        "effectedChecks": "FIRST_CHECK"
        }

Endpoint: https://api.paychex.com/workers/{workerId}/paycomponents

Verbs supported: GET

GET: Get all the the Pay Components for a specific worker.

Request:

Element NameTypeDescription
workerIdstringThe id assigned to the worker that the requested for.

Response:

VerbDescription
GETWorker pay components profile.

Endpoint: https://api.paychex.com/workers/{workerId}/paycomponents/{workerComponentId}

Verbs supported: GET, PATCH, & DELETE

GET: Retrieve a specific pay component that a worker has.

PATCH: Update a specific pay component that a worker has.

DELETE: Remove a specific pay component that a worker has.

Request:

Element NameTypeDescription
workerIdstringThe id assigned to the worker that workers are being requested for.
workerComponentIdstringThe id of a single pay component that a workers has.

 

Response

Profile: Worker Pay Components

The representational state of a workers pay component.
Element NameTypeDescription
workerComponentIdstringThe id of a single pay component that a workers has.
componentIDstringThe unique identifier of the pay component.
namestringName of the pay component.
calculationTypestringThe type of calculation that will be applied for the pay component .
  • FLAT_DOLLAR_AMOUNT: This is used for a specific dollar amount.
  • PERCENTAGE: This is used for when a Percentage will be used to calculate the amount and will need a calculationBaseId to specify what to apply against.
  • RATE_X_UNITS: This is used for apply the rate against units and will need a calculationBaseId to specify what to apply against.
  • RATE_X_HOURS: This is used for apply the rate against hours and will need a calculationBaseId to specify what to apply against.
calculationBaseIdstringThis is required if you are not using a FLAT_DOLLAR_AMOUNT Calculation Type.
valuenumberThis is used to specify the value that is used against the calculationType.
startDatedateDate which this pay component will start to be applied during the payruns. This is an optional field that default to current datetime if not provided. This cannot be backdated but can be added to start in the future.
effectOnPaystringWhat the effect on pay will be (REDUCTION OR ADDITION), currently only reductions are available.
frequencyobjectYou will define how often the pay component will be applied during the payruns.

{
    "content": [
        {
            "workerComponentId": "970000223656831",
            "componentId": "970000180599325",
            "name": "Deduction - 1",
            "calculationType": "FLAT_DOLLAR_AMOUNT",
            "value": 250.75,
            "startDate": "2018-03-15T00:00:00Z",
            "effectOnPay": "REDUCTION",
            "frequency": {
                "applied": "BY_PAY_PERIOD",
                "occurrence": "QUARTERLY",
                "occurrenceIntervals": {
                    "interval1": "2",
                    "interval2": "Last"
                },
                "effectedChecks": "EVERY_CHECK"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents/970000223656831"
                }
            ]
        },
        {
            "workerComponentId": "970000224745559",
            "componentId": "970000079956947",
            "name": "Deduction - 2",
            "calculationType": "PERCENTAGE",
            "calculationBaseId": "00H2A1IUJE7MXV6TQ37U",
            "value": 5,
            "startDate": "2018-03-01T00:00:00Z",
            "effectOnPay": "REDUCTION",
            "frequency": {
                "applied": "BY_PAY_PERIOD",
                "occurrence": "QUARTERLY",
                "occurrenceIntervals": {
                    "interval1": "1",
                    "interval2": "Last"
                },
                "effectedChecks": "FIRST_CHECK"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents/970000224745559"
                }
            ]
        },
        {
            "workerComponentId": "970000223656812",
            "componentId": "970000180598323",
            "name": "Deduction - 3",
            "calculationType": "RATE_X_UNITS",
            "calculationBaseId": "00H2A1IUJE7MXV6TQ37U",
            "value": 3,
            "startDate": "2018-03-15T00:00:00Z",
            "effectOnPay": "REDUCTION",
            "frequency": {
                "applied": "BY_PAY_PERIOD",
                "occurrence": "EVERY",
                "effectedChecks": "FIRST_CHECK"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents/970000223656812"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents"
        }
    ]
}