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. 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.
• 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.
• 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.

{
  "amount": 7800
}

{
  "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": []
    }
  }
}