Worker Paycomponent API lets you retrieve a specific pay component (e.g., salary, bonus) for an active worker as it was on a certain date. Pay components change over time, and effectivity identifies which version was valid on the date you request.

How Effectivity Works

What is Effectivity?
•    Effectivity defines the period during which a pay component is valid for a worker.
•    Each pay component has:
         Start Date – when the value became effective
         End Date – when the value was replaced or ended (may be open-ended)

The asof Query Parameter
•    The asof query parameter lets you specify a date (example: 2020-01-04T00:00:00Z).
•    The endpoint returns the version of the pay component active on that date.
•    If no version was effective on the provided date, the endpoint may return no data.

 Use the cURL sample below to GET Paycomponent for a worker.

curl --location 'https://api.paychex.com/workers/{worker_id}/paycomponents?effectonpay=REDUCTION&asof=YYYY-MM-DDT00:00:00Z' \
--header 'Authorization: Bearer <your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.payroll.paycomponents.v1+json' \

 Sample Response

{
  "content": [
    {
      "workerComponentId": "970000223656831",
      "componentId": "970000180599325",
      "name": "Deduction - 1",
      "calculationType": "FLAT_DOLLAR_AMOUNT",
      "value": 250.75,
      "startDate": "2018-03-15T00:00:00Z",
      "effectOnPay": "REDUCTION",
      "checkLimit": {
        "type": "BASED_ON_YTD_CASH_WAGES",
        "startsAt": "500"
      },
      "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"
        }
      ]
    }

 Use the cURL sample below to POST Paycomponent for a worker.

curl --location 'https://api.paychex.com/workers/{worker_id}/paycomponents' \
--header 'Authorization: Bearer <your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.payroll.paycomponents.v1+json' \
--data '{
  "componentId": "850001659458001",
  "calculationType": "PERCENTAGE",
  "calculationBaseId": "00DCE1NVJEOMDPV36GDY",
  "value": 5,
  "startDate": "2021-09-23T00:00:00Z",
  "effectiveDate": "2021-08-24T00:00:00Z",
  "endDate": "2021-09-24T00:00:00Z",
  "frequency": {
    "applied": "BY_PAY_PERIOD",
    "occurrence": "QUARTERLY",
    "occurrenceIntervals": {
      "interval1": "1",
      "interval2": "1"
    },
    "effectedChecks": "EVERY_CHECK"
  },
  "checkLimit": {
    "type": "",
    "startsAt": 500
  }
}'

    Sample Response 

{
  "content": [
    {
      "workerComponentId": "850002975988185",
      "componentId": "850001659458001",
      "name": "Union dues",
      "calculationType": "PERCENTAGE",
      "calculationBaseId": "00DCE1NVJEOMDPV36GDY",
      "value": 5,
      "startDate": "2021-09-23T00:00:00Z",
      "effectiveDate": "2021-08-24T00:00:00Z",
      "endDate": "2021-09-24T00:00:00Z",
      "effectOnPay": "REDUCTION",
      "classificationType": "UNION_DUES",
      "checkLimit": {
        "type": "BASED_ON_YTD_CASH_WAGES",
        "startsAt": "500"
      },
      "frequency": {
        "applied": "BY_PAY_PERIOD",
        "occurrence": "QUARTERLY",
        "occurrenceIntervals": {
          "interval1": "1",
          "interval2": "1"
        },
        "effectedChecks": "EVERY_CHECK"
      },
      "links": [
        {
          "rel": "self",
          "href": "https://api.paychex.com/workers/00DCE1NVK4DV16J4ENQJ/paycomponents/850002975988185"
        }
      ]
    }
  ]
}