---
title: "Set a timekeeper's rate in a rate table category from a date"
method: POST
path: "/rate_table_rates.json"
tags: ["Rate Table Rates"]
---

# Set a timekeeper's rate in a rate table category from a date

`POST /rate_table_rates.json`

## Request

- Base URL: `https://app.clio.com/api/v4`
- URL: `https://app.clio.com/api/v4/rate_table_rates.json`
- Auth: none declared

Sets a timekeeper's rate in a Rate Table category from `effective_from`. `rate_table_category` must be a category on `rate_table`. If a rate already starts on that date it's replaced; otherwise a new rate is added, the rate before it now ends the day before, and the new rate runs until the next rate starts. A scheduled removal of the timekeeper from the table is kept. `effective_from` defaults to today and can't be in the past, and an existing rate's date can't be moved: set a rate on the new date instead. `rate` is required; `null` clears the timekeeper's rate from that date, so billing falls back to the next rate source. `effective_until` is worked out from the timeline and can't be set; it's ignored if sent. The timekeeper is a firm User, or an ad hoc Group when rate table groups are turned on for the account; name it with `timekeeper[id]` and `timekeeper[type]`. The timekeeper must already be on the Rate Table on `effective_from`; add them with the Rate Table Timekeepers endpoint first.

Send up to 200 rates at once as an array with the `X-BULK: true` header. The whole payload is checked first: if any item is invalid, nothing is saved and the `422` response lists each bad item by its position in `data`. Otherwise the response is `202 Accepted` and the rates are saved in the background; items sent without `effective_from` all start on the date they were checked against. Poll the bulk action, whose id is in the `X-Bulk-Action` header, for the results, which hold one result per item, in request order. The table can change between the check and the save, so a completed bulk action can still contain failed items: check each item's `status`.

## Query parameters

- `fields` string

## Headers

- `X-API-VERSION` string

## Request body

- object
  - `data` object, required
    - `effective_from` string, date: The date the rate starts, in YYYY-MM-DD format. Can't be in the past. If a rate already starts on this date it's replaced. Default: today.
    - `rate` number, required: The hourly rate, in the Rate Table's currency. Required. Use `null` to clear the timekeeper's rate from `effective_from`, so billing falls back to the next rate source.
    - `rate_table` object, required
      - `id` integer, required: The unique identifier for a single RateTable associated with the RateTableRate. The keyword `null` is not valid for this field.
    - `rate_table_category` object, required
      - `id` integer, required: The unique identifier for a single RateTableCategory associated with the RateTableRate. The keyword `null` is not valid for this field.
    - `timekeeper` object, required
      - `id` integer, required: The unique identifier for the User or Group whose rate this is. Required.
      - `type` 'User' | 'Group': Whether `timekeeper[id]` is a `User` or a `Group`. Default: `User`. A `Group` must be an ad hoc group on the Rate Table, and is only accepted when rate table groups are turned on for the account.

## Response `201`

Created

- RateTableRateShow
  - `data` RateTableRate, required
    - `id` integer: Unique identifier for the *RateTableRate*
    - `etag` string: ETag for the *RateTableRate*
    - `rate` number: The hourly rate, in the rate table's currency. Null when the timekeeper has no rate set on the table from this date
    - `effective_from` string, date: The date the rate starts
    - `effective_until` string, date: The last date the rate applies, the day before the next rate starts or the date the timekeeper leaves the table. Null when the rate has no end date
    - `created_at` string, date-time: The time the *RateTableRate* was created (as a ISO-8601 timestamp)
    - `updated_at` string, date-time: The time the *RateTableRate* was last updated (as a ISO-8601 timestamp)
    - `timekeeper` object: The user or ad hoc group the rate is for: `id`, `etag`, `name`, and `type` (`User` or `Group`)
    - `rate_table` RateTableBase
      - `id` integer: Unique identifier for the *RateTable*
      - `etag` string: ETag for the *RateTable*
      - `name` string: The name of the rate table
      - `description` string: A detailed description of the rate table
      - `currency_id` integer: The ID of the currency the rate table's rates are denominated in
      - `status` string: The status of the rate table. Can be either "active" or "archived"
      - `created_at` string, date-time: The time the *RateTable* was created (as a ISO-8601 timestamp)
      - `updated_at` string, date-time: The time the *RateTable* was last updated (as a ISO-8601 timestamp)
    - `rate_table_category` RateTableCategoryBase
      - `id` integer: Unique identifier for the *RateTableCategory*
      - `etag` string: ETag for the *RateTableCategory*
      - `name` string: The name of the rate table category
      - `position` integer: The position of the category within its rate table, used for display ordering
      - `created_at` string, date-time: The time the *RateTableCategory* was created (as a ISO-8601 timestamp)
      - `updated_at` string, date-time: The time the *RateTableCategory* was last updated (as a ISO-8601 timestamp)
    - `created_by_user` UserBase
      - `account_owner` boolean: Whether the *User* is the owner of the account
      - `clio_connect` boolean: Whether the *User* is a Clio Connect user
      - `court_rules_default_attendee` boolean: Whether the *User* is a default attendee for court rules events
      - `created_at` string, date-time: The time the *User* was created (as a ISO-8601 timestamp)
      - `default_calendar_id` integer: Default calendar id for *User*.
      - `email` string: The email of the *User*
      - `enabled` boolean: Whether the *User* is allowed to log in
      - `etag` string: ETag for the *User*
      - `first_name` string: The first name of the *User*
      - `id` integer: Unique identifier for the *User*
      - `initials` string: The initials of the *User*
      - `last_name` string: The last name of the *User*
      - `name` string: The full name of the *User*
      - `phone_number` string: The primary phone number for the *User*.
      - `rate` number, float: Default user activity rate for *User*.
      - `roles` string[]: An array of roles assigned to this *User*
      - `subscription_type` 'Attorney' | 'NonAttorney': The subscription type of the *User*
      - `time_zone` string: The selected time zone of the *User*
      - `updated_at` string, date-time: The time the *User* was last updated (as a ISO-8601 timestamp)
      - `locale` string: The locale of the *User*

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests

## Changes

- **2026-10-22** `1587091ed74d`: 1 warning, 4 info
  - removed the optional property `data/allOf[subschema #2]/timekeeper` from the response with the `201` status
  - added the new optional request property `data/timekeeper/type` (media type: application/json)
  - added the new optional request property `data/timekeeper/type` (media type: application/x-www-form-urlencoded)
  - added the new optional request property `data/timekeeper/type` (media type: multipart/form-data)
  - …1 more
- **2026-10-15** `17c165eee941`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/clio/apis/clio-api-documentation/changes/rate_table_rates.json/post.md)

---

[API](https://skmtc.dev/clio/apis/clio-api-documentation.md) - [All operations](https://skmtc.dev/clio/apis/clio-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/clio/apis/clio-api-documentation/revisions/73770595be52?raw)