---
title: "Update project"
method: PUT
path: "/v2/projects/{project_id}"
tags: ["projects"]
---

# Update project

`PUT /v2/projects/{project_id}`

## Request

- Base URL: `https://api.hubstaff.com`
- URL: `https://api.hubstaff.com/v2/projects/{project_id}`
- Auth: OAuth 2
  - Authorization code: `https://account.hubstaff.com/authorizations/new`
  - Token URL: `https://account.hubstaff.com/access_tokens` scopes: `hubstaff:read`, `hubstaff:write`
- TypeScript: <https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/docs/v2/projects/:project_id/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates a project.

Returns the updated project.

Only pass in the fields you want to change. To unset the budget, specify null. To update the budget, you must specify the complete budget configuration.

When restoring an archived project, you can only change the status column.

Rate handling for pay_rate and bill_rate:
- To remove a rate, pass null (e.g., pay_rate: null)
- Custom user rates take precedence over default project rates
- To apply default project rate to a user, remove their custom rate first

## Path parameters

- `project_id` integer, required

## Request body

- PutV2ProjectsProjectId: Update project
  - `name` string: The new name of the project
  - `description` string: The new description of the project
  - `client_id` integer: The client ID
  - `billable` boolean: Whether time logged against this project is by default billable
  - `status` 'active' | 'archived': The project status.
  - `budget` object: Budget configuration
    - `type` 'cost' | 'hours', required: The method for controlling the budget
    - `rate` 'bill_rate' | 'pay_rate': When budget type is cost, specifies which rate to use.
    - `cost` number, float: When budget type is cost. defines the cost limit.
    - `hours` number, float: When budget type is hours. defines the hours limit.
    - `start_date` string, date: The start date for the budget.
    - `recurrence` 'weekly' | 'monthly': If given, makes budget reset on a weekly or monthly basis
    - `recurrence_start` integer: Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
    - `include_non_billable` boolean: Whether the budget includes non billable time
    - `stop_timer_when_budget_reached` boolean: Whether to stop timers when budget limit is reached
    - `stop_at` integer, required: The budget percentage at which timers stop automatically
    - `alerts` object
      - `near_limit` integer: The percentage threshold for notifying when approaching the budget.
      - `notify_enabled` boolean: Whether budget notifications are enabled
      - `notify_all_members` boolean: Whether to notify all project members
      - `notify_group` 'all_members' | 'org_management': The group to notify
  - `pay_rate` number, float: Default pay rate (will be rounded to 2 decimal places). Set to null to remove the rate
  - `bill_rate` number, float: Default bill rate (will be rounded to 2 decimal places). Set to null to remove the rate

## Response `200`

A project

- object
  - `project` Project: Project model
    - `id` integer, required: Project ID
    - `name` string, required: Project name
    - `description` string: Project description
    - `created_at` string, date-time, required: When the record was created
    - `updated_at` string, date-time, required: When the record was last updated
    - `status` string, required: Project status
    - `type` string, required: Project type (project, work_order, work_break)
    - `client_id` integer: Client ID
    - `billable` boolean, required: Default state of billable attribute for new activity
    - `budget` Budget
      - `type` string, required: The budget type
      - `rate` string: The budget rate type
      - `cost` number, float: The budget cost limit
      - `hours` number, float: The budget hours limit
      - `start_date` string, date: The budget start date
      - `alerts` object, required
        - `near_limit` integer, required: The budget near limit percentage
        - `notify_enabled` boolean, required: Whether budget notifications are enabled
        - `notify_all_members` boolean, required: Whether to notify all project members
        - `notify_group` string: The group to notify
      - `recurrence` string: The budget recurrence frequency
      - `recurrence_start` integer: Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
      - `include_non_billable` boolean, required: Whether the budget includes non-billable time
      - `stop_timer_when_budget_reached` boolean, required: Whether to stop timers when budget is reached
      - `stop_at` integer: The budget percentage at which timers stop
    - `metadata` object, required: Metadata attached to the project
    - `pay_rate` number, float: Default pay rate for the project
    - `bill_rate` number, float: Default bill rate for the project

## Other responses

- `400`: Invalid parameters
- `401`: Unauthorized
- `403`: API access is only for organizations on an active plan
- `404`: Could not find record
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api.md) - [All operations](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/revisions/c6b90e4e4bdc?raw)