---
title: "Update a Pay Item"
method: PATCH
path: "/v1/pay-items/{id}"
tags: ["Pay Items"]
---

# Update a Pay Item

`PATCH /v1/pay-items/{id}`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/pay-items/{id}`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `pay_item:write`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `pay_item:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

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 (except for payments generated from a recurring pay item, which return 422), 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". A deleted payment generated from a recurring pay item returns 422 instead, unless the request only clears `partner_external_id`.
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](https://developer.remote.com/docs/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, a payment generated from a recurring pay item 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, and neither can the payments generated from them, except to clear `partner_external_id`.
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 or a payment generated from one (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](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-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](https://developer.remote.com/docs/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`) |

## Path parameters

- `id` string, uuid, required: A unique identifier in UUID v4 format.

## Request body

- UpdatePayItemParams: Partial update — 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`; the old `id` keeps working, and the response's `replaced_ids` lists the earlier ids for integrations that track changes. Editing `end_date`, `provider_data` or `custom_configuration` alone updates the pay item in place and keeps the same `id`.
  - `amount` integer: Value of the pay item. See PayItemParams.amount for unit details. Must not be zero. Negative values are supported: send a negative `amount` to submit a deduction or to correct an earlier submission downwards — for any pay code, including hours-based ones such as `working_hours`.
  - `custom_configuration` PayItemCustomConfiguration, nullable: The pay item custom configuration values for pay codes that use one, such as the employee's company car. The pay code's `custom_configuration` (GET …/pay-codes) gives the `key` and the JSON Schema of the `values`. On PATCH, `values` are merged onto the stored ones: nested objects merge, and `null` removes a field at any level. Send `null` for the whole `custom_configuration` to remove the stored values.
    - `key` string, required: The pay code's `custom_configuration.key`
    - `values` object, required: Values matching the pay code's `custom_configuration.schema`
  - `effective_date` string, date: Date the pay item is applied on (YYYY-MM-DD) — the day worked, the day a correction was submitted, or the first day of a leave period.
  - `end_date` string, date, nullable: Last day of a leave period, inclusive (YYYY-MM-DD). Leave-of-absence pay codes only; send `null` to clear it.
  - `partner_external_id` string, nullable: A reference code for the pay item record in the calling integration's own system. Private to that integration — no other integration can read or overwrite it. Omit the field to leave the value unchanged; send `null` or an empty string to clear it. At most 64 characters, counting any surrounding whitespace sent; that whitespace is then trimmed off. A value can be held by one live pay item at a time, per integration and company; editing a pay item keeps its value on the new version. See [Your own IDs on Remote records](https://developer.remote.com/docs/your-own-ids-on-remote-records).
  - `provider_data` PayItemProviderDataParams
    - `adjustment_effective_date` string, date: **Deprecated — renamed to `correction_effective_date`**, which this value backfills. `correction_effective_date` wins when both are sent.
    - `correction_effective_date` string, date: Set this only on a correction: the original working day being corrected (YYYY-MM-DD). Its presence is what marks the pay item as a correction rather than an original submission.
    - `hourly_rate` integer: Hourly rate in cents
    - `hourly_rate_currency_code` string, nullable: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
    - `is_deduction` boolean: **Deprecated — accepted and ignored.** Express a deduction as a negative `amount`.
    - `pay_rate` number: Overtime rate multiplier (e.g. 1.5)
    - `payout_amount` integer: **Deprecated — accepted and ignored.** The payout value belongs in the pay item's own `amount`.
    - `payout_currency_code` string: **Deprecated — accepted and ignored.** The payout currency belongs in the pay item's own `currency`.
    - `shift_code` string: Shift identifier from partner system
    - `work_day_duration` integer: Expected work day duration in seconds

## Response `200`

Success

- PayItemResponse
  - `data` object, required
    - `pay_item` PayItem, required
      - `amount` integer, required: Value of the pay item. Its unit depends on the `type` of the pay code (see GET /v1/companies/:company_id/legal-entities/:legal_entity_id/pay-codes): `amount` in cents, `percentage` in basis points, `unit` as a raw count, `hours` as a whole number of hours, `duration` in seconds.
      - `code` string, required: Pay item type code
      - `custom_configuration` PayItemCustomConfiguration, nullable: The pay item custom configuration values for pay codes that use one, such as the employee's company car. The pay code's `custom_configuration` (GET …/pay-codes) gives the `key` and the JSON Schema of the `values`. On PATCH, `values` are merged onto the stored ones: nested objects merge, and `null` removes a field at any level. Send `null` for the whole `custom_configuration` to remove the stored values.
        - `key` string, required: The pay code's `custom_configuration.key`
        - `values` object, required: Values matching the pay code's `custom_configuration.schema`
      - `effective_date` string, date, required: Date the pay item is applied on (YYYY-MM-DD) — the day worked, the day a correction was submitted, or the first day of a leave period.
      - `employment_id` string, uuid, required: Employment UUID
      - `end_date` string, date, nullable, required: Last day of a leave period, inclusive (YYYY-MM-DD). Only for Leave-of-absence pay codes; Leave empty for other pay codes.
      - `id` string, uuid, required: Pay item's unique identifier. Editing `amount` or `effective_date` creates a new version with a new `id`; every `id` this API returned for a pay item edited through `PATCH` keeps working on `PATCH` and `DELETE` and resolves to the current version, except for a payment generated from a recurring pay item, which returns 422.
      - `partner_external_id` string, nullable: A reference code for the pay item record in the calling integration's own system. Private to that integration — no other integration can read or overwrite it. Null when the integration has not set one. See [Your own IDs on Remote records](https://developer.remote.com/docs/your-own-ids-on-remote-records).
      - `provider_data` PayItemProviderData, required
        - `correction_effective_date` string, date: Set this only on a correction: the original working day being corrected (YYYY-MM-DD). Its presence is what marks the pay item as a correction rather than an original submission.
        - `hourly_rate` integer: Hourly rate in cents
        - `hourly_rate_currency_code` string: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
        - `pay_rate` number: Overtime rate multiplier (e.g. 1.5)
        - `shift_code` string: Shift identifier from partner system
        - `work_day_duration` integer: Expected work day duration in seconds
      - `replaced_ids` string[], required: Earlier `id`s of this pay item, oldest first; empty if it has never been edited. Each of them still resolves to the current version on `PATCH` and `DELETE`, so tracking them is strongly advised but not necessary.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Unprocessable Entity
- `429`: Unprocessable Entity

---

[API](https://skmtc.dev/remote-com/apis/pay-compensation.md) - [All operations](https://skmtc.dev/remote-com/apis/pay-compensation/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/pay-compensation/revisions/ec29f1865c5e?raw)