Create a forecast budget
const url = 'https://app.commitly.com/api/forecast/budgets/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"category":1006,"settlement_date":"2024-04-08","tags":["my-integration","direct-API"],"name":"Tax prepayment","description":"Created via API","amount":-78700,"external_id":"ext-123457","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 POST \ --url https://app.commitly.com/api/forecast/budgets/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "category": 1006, "settlement_date": "2024-04-08", "tags": [ "my-integration", "direct-API" ], "name": "Tax prepayment", "description": "Created via API", "amount": -78700, "external_id": "ext-123457", "external_source": "my-integration" }'Creates a budget directly in the forecast. The forecast is the central planning view in COMMITLY; use with care.
- Required:
name,category(ID of a leaf category),settlement_date. external_idmust be unique within the forecast; a duplicate returns 400{"external_id": ["This field must be unique."]}. Create never updates an existing budget.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”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": 1006, "settlement_date": "2024-04-08", "tags": [ "my-integration", "direct-API" ], "name": "Tax prepayment", "description": "Created via API", "amount": -78700, "external_id": "ext-123457", "external_source": "my-integration"}Responses
Section titled “Responses”Budget created.
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
Forecast budget
{ "id": 9003, "category": { "id": 1006, "name": "Other taxes and fees", "description": "" }, "inter_category_name": null, "depending_categories": [], "recurring_budget": null, "settlement_date": "2024-04-08", "start_date": null, "end_date": null, "account": null, "tags": [ "my-integration", "direct-API" ], "integration_tags": null, "is_adjusted": false, "name": "Tax prepayment", "description": "Created via API", "amount": -78700, "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": "ext-123457", "external_source": "my-integration", "inter_company": null, "source": null, "inter_budget": null, "base_categories": []}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."}