Skip to content
COMMITLYCOMMITLYCOMMITLY Developers

Budgets and external IDs

A budget is a planned or expected amount in a category on a date. The same budget structure exists in three places:

Where Endpoint Use it for
Plan /plans/{plan_id}/budgets/ Planned values of a committed plan
Scenario /scenarios/{scenario_id}/budgets/ What-if assumptions
Forecast /forecast/budgets/ Expected amounts in the current forecast

Fields

Section titled “Fields”

Required on create: name, category and settlement_date.

Field Description
category Integer ID of a leaf category, i.e. one without subcategories (Data model)
name, description Shown in COMMITLY
amount Negative for outflows, positive for inflows
settlement_date Date of the expected payment, YYYY-MM-DD
tags Optional labels (array)
external_id Your ID for this budget
external_source Name of your system, for example "crm"

Budgets can also recur: set frequency (daily, weekly, monthly, quarterly, yearly) and frequency_multiplier, and for growing or shrinking series sequence_type, sequence_term_size, d and r. The API reference lists every field.

Keep budgets in sync with external IDs

Section titled “Keep budgets in sync with external IDs”

Create the budget on the normal list URL and send external_id and external_source in the body. Read, update and delete then address the budget by your own ID, so you do not need to store COMMITLY’s internal IDs:

POST   /api/forecast/budgets/                      (external_id in the body)
GET    /api/forecast/budgets/external/deal-4711/
PATCH  /api/forecast/budgets/external/deal-4711/
DELETE /api/plans/{plan_id}/budgets/external/deal-4711/
  • external_id is unique per plan. The forecast and every scenario count as separate plans, so the same ID can exist in the forecast and in a scenario.
  • Creating a budget with an existing external_id returns 400. There is no upsert: update existing budgets with PATCH.
  • The trailing slash is required, and external_id must not contain . or /.

If you store COMMITLY’s IDs instead, update and delete budgets by internal ID with PUT, PATCH or DELETE on /plans/{plan_id}/budgets/{id}/, /scenarios/{scenario_id}/budgets/{id}/ or /forecast/budgets/{id}/.

Update with PATCH, leave out what stays

Section titled “Update with PATCH, leave out what stays”

Send only the fields you want to change. An empty string does not mean “unchanged”: it clears text fields and is rejected for most others. A PATCH response contains the budget id and the fields you sent; PUT replaces the whole budget and returns it in full.

A typical sync job creates a budget for each new record in your system, updates it when the record changes and deletes it when the record is closed or cancelled.