deleteContractBudgets

Overview

Deletes a pending Adjustment or Credit line from fm_contract_budgets, mirroring the legacy Lease screen's Delete button exactly — including its type/status restriction, now enforced server-side rather than only by a disabled button. This is a hard delete with no undo, matching legacy behaviour.

This method requires the ContractBudgets:Delete permission to be associated with your role.

Permissions

The permission for this api is stored in [gb_api_permissions]permission as ContractBudgets:Delete.

Only roles with a stored link to this permission in [gb_role_api_permissions] can run this api.

HTTP Method

Use the HTTP Method DELETE for consuming this web service.

URL Examples

https://api.demo.catch-e.com/fm/contract/budgets 
https://api.{{environment}}.catch-e.com/fm/contract/budgets https://api.test.catch-e.com/fm/contract/budgets

Input Fields (JSON)

{ "contract_id": 12345, "billing_period": 1, "billing_period_item_no": 2 }

Key	Format	Notes	Mandatory
contract_id	integer	Identifies the contract.	Yes
billing_period	integer (or fractional `period.item_no` form)	Identifies the target billing period.	Yes*
billing_period_item_no	integer	Explicit item number, usable alongside or instead of the fractional form.	Yes*

*One valid combination of billing_period/billing_period_item_no must resolve to a specific row.

Response Details

Success

204 No Content

Deletes the targeted row and writes a single audit record, keyed by contract_id, matching legacy gb_audit @delete parity.

Error Response Details

Validation Message	Comments
422 - Unprocessable Entity	`contract_id` is missing — required field.

{ "validation_messages": { "contract_id": { "isEmpty": "Value is required and can't be empty" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

Validation Message	Comments
422 - Unprocessable Entity	`billing_period` / `billing_period_item_no` combination doesn't exist.

{ "validation_messages": { "billing_period_item_no": { "billingPeriodItemNoInvalid": "Specified billing period / billing period item number does not exist" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

Validation Message	Comments
422 - Unprocessable Entity	The targeted row is a Periodic line — these can't be deleted via this endpoint.

{ "validation_messages": { "billing_type_flag": { "periodicNotDeletable": "Periodic budget lines cannot be deleted. Use updateContractBudgets to set the amount to 0 instead." } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

Validation Message	Comments
422 - Unprocessable Entity	The line exists but is no longer `pending` (already billed, or changed by a concurrent operation).

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "The budget line is no longer pending and cannot be deleted. Please refresh the data and try again." }

Validation Message	Comments
423 Locked	The row is locked by a concurrent delete/update/billing operation on the same contract. One call wins; the other gets this response with no data affected. (Confirmed against final QA sign-off — the ticket's own description described this only as "a clean lock/conflict error" without naming the status code.)

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Locked", "status": 423, "detail": "Locked" }

Validation Message	Comments
401 Unauthorized	1. You have not authenticated before running this API or 2. The token_timeout of the current session has passed. You need to authenticate again.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" }

Validation Message	Comments
403 Forbidden	You do not have the ContractBudgets:Delete permission.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" }

Validation Message	Comments
406 Not Acceptable

json

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Acceptable", "status": 406, "detail": "Not Acceptable" }

Validation Message	Comments
415 Unsupported Media Type

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unsupported Media Type", "status": 415, "detail": "Not Acceptable" }

Validation Message	Comments
500 Internal Error

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }

Validation Message	Comments
default Unexpected Error

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }