Update a Pay Item
Changed onUpdates 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". 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. 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 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 through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
- Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page. See Authorization for customers.
Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage payroll runs (payroll) | - | Manage pay items (pay_item:write) |
Request
- Base URL: https://gateway.remote.com
- URL: https://gateway.remote.com/v1/pay-items/{id}
- Auth: HTTP bearer and OAuth 2 (authorization code, authorization URL /auth/oauth2/authorize, token URL /auth/oauth2/token, scopes: https://gateway.remote.com/company.manage, pay_item:write, payroll, all:write)
Path parameters
A unique identifier in UUID v4 format.
Pay item ID
Request body
Example request
{
"amount": 7800
}Response
Success
Example response
{
"data": {
"pay_item": {
"amount": 7200,
"code": "overtime",
"effective_date": "2026-03-11",
"employment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"end_date": null,
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"provider_data": {
"correction_effective_date": "2026-03-15",
"hourly_rate": 2550,
"hourly_rate_currency_code": "SGD",
"pay_rate": 1.5,
"shift_code": "DAY",
"work_day_duration": 28800
},
"replaced_ids": []
}
}
}Changes
- info
added the new optional request property
- info
added the optional property
//to the response with the status
- info
- info
added the new optional request property
- info
added the required property
//to the response with the status
- info