---
updatedAt: 2026-03-11T14:59:57.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Overview

The Pay Rates API lets you manage employee pay rates programmatically — retrieve current and historical rates, create or update rates with effective dates, and remove rate entries.

## Endpoints

| Method | Endpoint                                                 | Description                                               |
| ------ | -------------------------------------------------------- | --------------------------------------------------------- |
| GET    | `/pay-rates/v1/pay-rates`                                | Retrieve pay rates for users within a date range          |
| PUT    | `/pay-rates/v1/pay-rates`                                | Create or update pay rates (upsert) for one or more users |
| DELETE | `/pay-rates/v1/pay-rates/users/{userId}/{effectiveDate}` | Delete a specific pay rate entry                          |

## Authentication

All endpoints require either an **API Key** or **OAuth 2.0** token.

| OAuth Scope        | Endpoints |
| ------------------ | --------- |
| `pay_rates.read`   | GET       |
| `pay_rates.write`  | PUT       |
| `pay_rates.delete` | DELETE    |

## Key Concepts

### Effective Dates

Every pay rate has an `effectiveDate` — the date from which it applies. A user can have multiple pay rates, each with a different effective date. The most recent effective date determines the user's current rate.

### Rate Types

Three rate types are supported: `hourly`, `monthly`, and `yearly`.

### Rate Hierarchy

Pay rates support a three-level hierarchy:

1. **Default Rate** — the base rate applied to the user
2. **Resource Rate** — a per-job override. Can inherit from the default via `useDefaultRate`
3. **Sub-Resource Rate** — a per-sub-job override. Can inherit from the parent resource via `useParentRate`

When inheritance flags are set, the rate value is omitted from the response.

### Upsert Semantics

The PUT endpoint uses upsert logic: sending a pay rate for a user + effective date that already exists **fully replaces** the existing entry. There is no separate create vs update endpoint.

### Locked Days Protection

If a user has approved or locked timesheet days on or after the effective date, both PUT and DELETE operations are rejected with HTTP 409 and error code `HAS_LOCKED_DAYS`. This prevents changes that would affect finalized payroll.

## Guides

Detailed documentation for each endpoint:

* [Get Pay Rates](https://developer.connecteam.com/docs/get-pay-rates) — query parameters, date range behavior, pagination, modification history
* [Set Pay Rates](https://developer.connecteam.com/docs/set-pay-rates) — request body, validation rules, resource rate configuration
* [Delete Pay Rate](https://developer.connecteam.com/docs/delete-pay-rate) — path parameters, locked days checks, behavior

## Common Integration Patterns

1. **Payroll sync** — `GET` pay rates for all users in the pay period, then push to your payroll system.
2. **Bulk rate updates** — `PUT` with up to 500 users per request for annual raises or rate adjustments.
3. **Audit trail** — Use `isIncludeHistory=true` on GET to retrieve the full modification history for compliance.
4. **Rate cleanup** — `DELETE` incorrect entries by user ID and effective date.