Update a plan budget by external ID
const url = 'https://app.commitly.com/api/plans/2001/budgets/external/ext-123457/';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"amount":777000}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://app.commitly.com/api/plans/2001/budgets/external/ext-123457/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "amount": 777000 }'Updates the budget with the given external_id in the given plan. Send only
the fields to change; see BudgetUpdate for how empty strings are handled. The
response contains id and the fields that were sent.
external_id in the body is not required. If it differs from the path, the
budget’s external_id is changed to the new value.
Note: Budgets of a committed plan cannot be updated or deleted (403). Other
checks that the COMMITLY app applies may not apply to the API. Only change
budgets that your integration created, for example by filtering on
external_source (list parameter source).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Plan ID (id from GET /plans/).
Example
2001The external_id set when the budget was created. Budgets whose
external_id contains . or / cannot be addressed by this path. The
trailing slash after the external_id is required.
Example
ext-123457Request Bodyrequired
Section titled “Request Bodyrequired”Only the fields to change.
Budget for partial update (PATCH). Send only the fields to change. Empty strings do not mean “unchanged”:
| Field | Effect of "" |
|---|---|
description, external_source, frequency, sequence_type | Clears the field |
account, inter_company, inter_category | Sets the field to null |
name, category, external_id | 400 |
Numbers (amount, rate, d, r, …), dates, booleans, lists | 400 |
Leave out fields you want to keep.
object
ID of a leaf category (a category without subcategories). A numeric string is also accepted.
Decimal with at most 12 digits and 2 decimal places. Negative for outflows, positive for inflows. A JSON number or a numeric string.
Your own ID for the budget; used in the /external/{external_id}/ paths.
Unique per plan: the forecast and each scenario count as separate plans.
Creating a budget with an external_id that already exists in the same
plan returns 400. Do not use . or /. In an update, a value different
from the current one changes the budget’s external_id.
Free-text name of the system that created the budget. Filter with the list parameter source.
Bank account ID.
Decimal rate with 4 decimal places. Default 0.
FS forecast and scenario (default), S scenario, F forecast.
Recurrence period. Empty for a one-time budget.
Repeat every N periods. Default 1.
Series type of a recurring budget; AP arithmetic, GP geometric, HP harmonic, empty for none.
Term size of the series. Default 1.
Common difference of an arithmetic series. Default 0.
Common ratio of a geometric series. Default 1.
IDs of the categories the budget depends on.
The recurring budget runs indefinitely.
Company ID for an intercompany budget.
Category of the linked budget in the other company. Only valid together with inter_company.
Tag list for integrations.
Example
{ "amount": 777000}Responses
Section titled “Responses”Budget updated. The response contains id and the fields that were sent.
Budget as returned by the API.
object
Internal budget ID; used in the /budgets/{id}/ paths.
Short form of a category, embedded in transactions and budgets.
object
Category of the linked budget in the other company.
Name of inter_category.
Categories the budget depends on.
Stored dependency categories (set via depending_categories).
Summary of the recurrence settings; null if the budget is not recurring.
object
Bank account ID.
The linked budget in the other company of an intercompany budget, or null.
Negative for outflows, positive for inflows.
FS forecast and scenario, S scenario, F forecast.
Your own ID for the budget.
Free-text name of the system that created the budget.
Company ID for an intercompany budget.
ID of the budget this one was copied from, or null. Not related to external_source.
Example
{ "id": 9002, "amount": 777000}Invalid request body or parameters. The body lists the errors per field; errors
not tied to a field are listed under non_field_errors. For request bodies
that are arrays, the body is a list with one error object per item. Messages
are localized (see Accept-Language).
Validation errors. Each key is a field of the request body; its value is the
list of messages for that field. Errors not tied to a field are listed under
non_field_errors.
object
Validation errors. Each key is a field of the request body; its value is the
list of messages for that field. Errors not tied to a field are listed under
non_field_errors.
object
Example
{ "settlement_date": [ "This field is required." ]}The access token is invalid or has expired. Request a new token. The message is
localized (see Accept-Language).
object
Error message.
Present only if the company’s edition does not include the function; value billing_plan_permission_denied.
Example
{ "detail": "Invalid token."}Headers
Section titled “Headers”Authentication scheme, Bearer.
Example
BearerNo access token was sent, or the credentials are not allowed to call this
endpoint. If the company’s COMMITLY edition does not include the requested
function, the body additionally contains
"code": "billing_plan_permission_denied".
object
Error message.
Present only if the company’s edition does not include the function; value billing_plan_permission_denied.
Example
{ "detail": "User must be authenticated to access this resource."}The resource does not exist or is not accessible with these credentials.
object
Error message.
Present only if the company’s edition does not include the function; value billing_plan_permission_denied.
Examplegenerated
{ "detail": "example", "code": "example"}