Updates a pay item. Only the fields provided are changed. Editing amount or effective_date archives the existing pay item and creates a new one with a new id. Any id this API returned for a pay item edited through PATCH, including every entry of replaced_ids, keeps working and resolves to its current version, so storing the new id is strongly advised but not necessary; replaced_ids in the response lists the earlier ids for integrations that track changes. A deleted pay item (no live version left) returns 404 with the message "Pay item not found because it was deleted".
Send partner_external_id to set or change the calling integration's own reference code, or null or an empty string to clear it. An edit that creates a new id keeps the value on the new version.
See Your own IDs on Remote records.
Cannot update pay items linked to a payroll adjustment, salary pay items, pay items automatically created from an external source, pay items whose payroll run is no longer in preparation, or pay items with more than one live version.
The one change allowed on a pay item linked to a payroll adjustment, a salary pay item, one created from an external source or one whose payroll run is no longer in preparation is clearing partner_external_id: a request whose only field is partner_external_id, sent as null or an empty string, clears it and leaves the pay item itself unchanged. Setting a value on such a pay item is refused, so the clear can't be undone, and a bulk item sent again with the cleared value creates a new pay item. A clear still gets the not found, recurring, more than one live version and "is not available" refusals; any pay item they allow accepts it, including one dated after the employment's termination date.
Recurring pay items cannot be updated or deleted through this API and return 422. A monthly payment generated from a recurring pay item can be regenerated with a new id when the recurring item changes; its old id then returns 404.
When more than one refusal applies, the first in this order is returned: an employment that isn't on Global Payroll (404 "Pay item not found"), a recurring pay item (422), then a pay item with more than one live version (422).
When custom_configuration doesn't match the pay code's custom configuration, the 422 response is a parameter error with the same code bulk create returns: custom_configuration_not_used, custom_configuration_required or invalid_custom_configuration, and the param at fault.
Authentication
This endpoint accepts any one of the following token types:
- Company-scoped access token (
OAuth2AuthorizationCode) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See Authentication for partners. - Company-scoped access token (assertion) (
OAuth2CompanyManagerAssertion) — obtained through theurn:ietf:params:oauth:grant-type:jwt-bearergrant for a company manager. See OAuth Assertion. - Customer API token (
CustomerAPIToken) — generated by the customer on their Integration Settings page, with the scopes they choose there. See Authorization for customers.
Scopes
Any one of the scopes in a token type's row is enough. all:write works too.
| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage payroll runs (payroll) | - | Manage pay items (pay_item:write) |
| Company-scoped access token (assertion) | Manage payroll runs (payroll) | - | Manage pay items (pay_item:write) |
| Customer API token | Manage payroll runs (payroll) | - | Manage pay items (pay_item:write) |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||