# Feature OP-20197 - API v3: full CRUD for cost entries, matching time entries

Project: OpenProject
Status: new
URL: https://community.openproject.org/work_packages/OP-20197

## Planning

| Attribute | Value |
| --- | --- |
| Date |  |
| Priority | Medium |
| Target versions | Wish List |
| Sprint |  |
| Backlog bucket |  |
| Votes | 1 |
| List |  |
| Roadmap |  |
| Relevance |  |

## OPEN POINTS / FEEDBACK

_No work packages_

## Features and Chunks

_No work packages_

## Bugs and other work packages

_No work packages_

## Technical Details

| Attribute | Value |
| --- | --- |
| Module | API, Modules and project features / Costs and budgets |
| Feature Flag |  |
| Requires doc change | No |
| Enterprise plan |  |

## Details

| Attribute | Value |
| --- | --- |
| Pull preview |  |
| Mockups |  |
| Accessibility | No |

## People

| Attribute | Value |
| --- | --- |
| Assignee |  |
| Accountable |  |
| Product manager |  |
| Feature Lead |  |
| Developers |  |
| Designer |  |
| Ordered by |  |
| Signed off by |  |
| Interest by |  |

## Estimates and progress

| Attribute | Value |
| --- | --- |
| PD (min) |  |
| PD (max) |  |
| Work |  |
| Labor costs |  |

## Description

**As an** API user  
**I want to** create, update and delete cost entries via the API  
**so that** unit costs can be logged programmatically, the same way labor time already can.

**Acceptance criteria**

  - POST /api/v3/cost\_entries creates a cost entry and returns 201, mirroring POST /api/v3/time\_entries.

  - The payload accepts units, spentOn and comment, plus \_links to workPackage, costType, project and user.

  - PATCH /api/v3/cost\_entries/{id} updates an existing entry.

  - DELETE /api/v3/cost\_entries/{id} removes one and returns 204.

  - Invalid input returns 422 with a standard error body; insufficient permissions return 403.

  - Changes are reflected in the work package's materialCosts and overallCosts.

  - The endpoints appear in the OpenAPI specification.

**Technical notes**

  - API v3 supports full CRUD for time entries but GET only for cost entries, despite the two being parallel resources in the same module.

  - modules/costs/lib/api/v3/cost\_entries/cost\_entries\_api.rb defines GET only. OPTIONS on the collection returns "Allow: OPTIONS, GET, HEAD".

  - Cost entries are missing from the OpenAPI specification, which suggests an unfinished endpoint rather than a deliberate restriction.

  - <mention class="mention" data-id="76412" data-type="work_package" data-text="#76412">#76412</mention> already introduced contracts for cost entries, so the validation layer exists and could be reused. <mention class="mention" data-id="69494" data-type="work_package" data-text="#69494">#69494</mention> shows the time entry API is actively being extended.

**Permissions and visibility considerations**

**To whom is this feature visible?**

  - API users holding the permissions that already gate the "Log unit costs" form: log\_costs for entries on behalf of another user, log\_own\_costs for their own. No new permission is introduced.

**When is it not visible?**

  - When the "Time and costs" module is disabled for the project.

  - When the user lacks the logging permission, in which case the endpoints return 403, as the equivalent time entry endpoints do.

  - Reads remain subject to the existing view\_cost\_entries and view\_own\_cost\_entries rules.

**Translation considerations**

Key terms and phrases in the key languages

  - No new user-facing strings. The endpoints are API-only and return machine-readable error identifiers, reusing the existing cost entry contract translations already used by the "Log unit costs" form.

**Out of scope**

  - Any change to the web UI, including the "Log unit costs" form.

  - Bulk or batch creation of cost entries.

  - Changes to cost reports, budgets, or cost aggregation.

  - Changes to cost type administration.

*Set the* **To be informed/consulted teams** *field to include all teams necessary to be informed of the changes.*
