--- title: "Insert or update payroll period data" method: PATCH path: "/v2/providers/employers/employees/employments/{employmentId}/payrollperioddata" tags: ["Payroll period data"] --- # Insert or update payroll period data `PATCH /v2/providers/employers/employees/employments/{employmentId}/payrollperioddata` ## Request - Base URL: `https://api.loket.nl` - URL: `https://api.loket.nl/v2/providers/employers/employees/employments/{employmentId}/payrollperioddata` - Auth: none required **This endpoint is the REST alternative to the ImporteerGegevens (Variabele Gegevens) SOAP webservice functionality**

__Activity name :__ PatchPayrollPeriodDataByEmploymentId

This endpoint is typically used by applications that are considered to be leading in regard to the values for the payroll components they manage. For most (external) applications this will the most viable endpoint to achieve that functionality. Loket considers these parties as not interested in the current state of the payroll period data in the Loket database. This endpoint is provided to make these scenarios easier to implement since no GET call is required to determine whether a POST or PUT call is to be performed to either insert or update payroll period data. Based on the current state of the database Loket will either insert a new record or update the existing record with the supplied data. * A new record is created when the combination of `payrollPeriod`, `shift`, `payslipType`, `distributionUnit`, `costCenter` and `costUnit` is valid and _does not_ exist for the employment. Next to that, the objects consisting of `payrollComponent`, `value` and `attribute` are inserted into the database.
* An update is performed when the combination of `payrollPeriod`, `shift`, `payslipType`, `distributionUnit`, `costCenter` and `costUnit` _does_ exist for the employment. In that case the specified objects consisting of `payrollComponent`, `value` and `attribute` are inserted into the database, overwriting existing values. Existing records with a `payrollComponent.key` that is not supplied in the request are not modified.

__Metadata :__
Possible values for fields of the type 'metadata' can be acquired (GET) by adding `/metadata` to the PATCH URL
Possible values for fields of the type 'metadata' that are PERIOD-specific can be acquired (GET) by adding `/metadata/year/{year}/period/{periodNumber}` to the PATCH URL

__Default values :__
Default values may be acquired by adding `/defaults` (GET) to the PATCH url . It is very much (!!!) recommended to acquire the defaults-objects first and use that information when inserting data for this employment. I.e. use the default values for costCenter, shift etcetera and the complement the object with the payroll components you want to provide.

__Extra background reading :__
It may be useful to read more about payroll period data (variabele gegevens, mutaties) on the Loket [helpdesk portal](https://helpdesk.loket.nl/hc/nl/articles/115003667669-Variabele-mutaties-Individuele-vastlegging). Please note that this information is in Dutch and access is required.
## Path parameters - `employmentId` string, uuid, required ## Query parameters - `filter` string - `orderBy` string - `pageNumber` integer - `pageSize` integer ## Headers - `Authorization` string, required - `Accept` string, required ## Request body - PayrollDataPatch20180101 - `id` string, uuid: The unique identifier of an object (GUID/UUID) - `payrollPeriod` object - `year` integer: The year of the payroll period in which the payroll data is to be processed - `periodNumber` integer: The period (month [1 to 12] , 4 weeks [1 to 13] or week [1 to 53]) of the payroll period in which the payroll data is to be processed. - `periodStartDate` string, date: The first day of the period to which the payroll period data applies - `periodEndDate` string, date: The last day of the period to which the payroll period data applies - `shift` object: The shift determines the full-time hours and bonus percentage. - `shiftNumber` integer: The number for the shift. Loket supports a maximum of 15 shifts per payroll administration. - `fullTimeHoursPerWeek` number: The full time hours for an employment that is linked to this shift. - `bonusPercentage` number: The bonus percentage used in wage calculations for the hours made in this shift. - `payslipType` object: The type of payslip (as defined by the Dutch tax authorities) - `key` integer - `value` string - `payslipText` string, nullable: A custom text to be displayed on the payslip. - `distributionUnit` object: Distribution unit (verdelingseenheid), used in several reports and the "basic wage journal" functionality. Commonly used as a cost center. - `key` string, uuid: The unique identifier of an object (GUID/UUID) - `code` integer - `description` string - `costCenter` object, nullable: The cost center on which the payroll period data for this record will be booked for the ledger. - `key` integer - `code` string - `description` string - `costUnit` object, nullable: The cost unit on which the data for this record will be booked for the ledger - `key` integer - `code` string - `description` string - `processingMethod` 'overwrite' | 'doNotOverwrite' | 'addUp', nullable: The processing method determines how components that already have a value are handled. - `payrollComponents` object[] - `payrollComponent` object: A payroll component is the link to the salary calculation. By setting the value of a component the salary calculation will take this value into account when calculating the wage of the employment for the given payroll period.
Please note: Business rules may differ per component! Understanding these business rules and corresponding validations requires functional knowledge of Loket. - `key` integer: The number for the payroll component. This number has meaning to payroll professionals using Loket who often know it by heart. - `description` string: The description of the payroll component - `category` object: The category of the payroll component. Example categories are, hours/extra hours/net payment/net deduction etc. - `key` integer - `value` string - `deductionOrPayment` object, nullable: Indicates if the value of the payroll component will be deducted from or added to the salary. In case the component is neither a deduction or a payment, NULL is returned. - `key` integer - `value` string - `canBeSupplemented` boolean: Indicates whether the atribute for this payroll component can have the value `supplement`. Refer to the description of the attribute field for an explanation. - `value` number, nullable: Depending on the selected payroll component the possible value(s) for this field change (dynamic business rules). Please note: a `null` value will be seen as empty, any period-specific record for the corresponding component will be deleted for the payroll period it applies to. This is something different than setting it to the value of 0 (!). Please also note the following (!!!) if you do not have a value for the component in this period please do not include this payrollComponent at all in your request. If you do so, this might result in unexpected results. - `isSupplement` boolean: This boolean determines what the salary calculation will do with the value of the payroll component if the payroll component has values in both the payroll period specific data (this endpoint) and in the non-payroll period specific configuration of the employment (it is possible to configure values for payroll components that span multiple payroll periods and even parts thereof). * When set to `false`, the value of the payroll component will overwrite the value specified in the non-payroll period specific data with the given value in the payroll period specific date. * When set to `true`, the value of the payroll period specific data will be added to the value of the non-payroll period specific data. Note that a value can be a negative number. For instance, a payroll period specific value of 20 and a non-payroll period specific value of -8 will effectively result in 12 for salary calculation. This boolean can only be set to `true` in components for which `payrollComponent.canBesupplemented = true`. ## Response `200` OK ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `500`: Internal Server Error --- [API](https://skmtc.dev/loket/apis/loket-api.md) - [All operations](https://skmtc.dev/loket/apis/loket-api/llms.txt) - [OpenAPI document](https://skmtc.dev/loket/apis/loket-api/revisions/32170564148f?raw)