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

# Delete a Pay Item

`DELETE /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

Archives a pay item. Cannot delete 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.
Any `id` this API returned for a pay item edited through `PATCH`, including every entry of `replaced_ids`, is accepted and archives its current version, except for payments generated from a recurring pay item, which return 422. A pay item that was already deleted returns 404 with the message "Pay item not found because it was deleted", or 422 when it was a payment generated from a recurring pay item, so a retried delete never removes anything else.
Deleting a pay item frees its `partner_external_id`, so a later pay item can take the value.
See [Your own IDs on Remote records](https://developer.remote.com/docs/your-own-ids-on-remote-records).
Recurring pay items and the payments generated from them cannot be updated or deleted through this API and return 422.
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).

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

## Response `200`

Success

- SuccessResponse: A generic success response returned by operations that don't produce a specific resource (e.g., updates, deletes).
  - `data` object, required
    - `status` string: The result status. Always `"ok"` for successful operations.

## Other responses

- `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)