Replace a plan budget by external ID
const url = 'https://app.commitly.com/api/plans/2001/budgets/external/ext-123457/';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"category":1002,"name":"Consulting project","description":"","amount":150,"settlement_date":"2024-01-20","external_id":"123456","external_source":"my-integration"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://app.commitly.com/api/plans/2001/budgets/external/ext-123457/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "category": 1002, "name": "Consulting project", "description": "", "amount": 150, "settlement_date": "2024-01-20", "external_id": "123456", "external_source": "my-integration" }'Replaces the budget with the given external_id in the given plan. Send the
complete budget; name, category and settlement_date are required. Fields
not sent are reset to their defaults. Prefer PATCH to change single fields.
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”The complete budget. name, category and settlement_date are required.
Budget for create (POST) and full update (PUT). name, category and
settlement_date are required; all other fields are optional or have a
default. Recurring budgets are set with frequency, frequency_multiplier
and, for series, sequence_type, sequence_term_size, d and r.
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
{ "category": 1002, "name": "Consulting project", "description": "", "amount": 150, "settlement_date": "2024-01-20", "external_id": "123456", "external_source": "my-integration"}Responses
Section titled “Responses”Budget updated. The response contains the complete budget.
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.
Examples
Plan budget
{ "id": 9001, "category": { "id": 1002, "name": "Revenue", "description": "" }, "inter_category": null, "inter_category_name": null, "depending_categories": [], "recurring_budget": null, "settlement_date": "2023-01-15", "start_date": null, "end_date": null, "account": null, "tags": [], "integration_tags": null, "is_adjusted": false, "inter_budget": null, "name": "Consulting project", "description": "", "amount": 125, "rate": 0, "base": "FS", "time_lags": [], "frequency": "", "frequency_multiplier": 1, "sequence_type": "", "sequence_term_size": 1, "d": 0, "r": 1, "is_indefinite": false, "external_id": "123456", "external_source": "my-integration", "inter_company": null, "source": null}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"}