List forecast budgets

GET

/forecast/budgets/

const url = 'https://app.commitly.com/api/forecast/budgets/?budget_type=single&page_size=100';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://app.commitly.com/api/forecast/budgets/?budget_type=single&page_size=100' \
  --header 'Authorization: Bearer <token>'

Returns the budgets in the forecast. With all_budgets=true, the list contains the budgets of all plans of the company.

Note the response shape: results is an object containing the total and the budgets array, not an array.

Authorizations

commitlyOAuth

Parameters

Query Parameters

category

Array<integer>

Category ID; includes its subcategories. Repeat the parameter for several categories.

min_date

string format: date

Earliest settlement_date.

max_date

string format: date

Latest settlement_date.

min_value

number

Minimum amount.

max_value

number

Maximum amount.

source

string

Substring match on external_source. Several comma-separated values are combined with OR.

budget_type

string

Allowed values: single recurring dynamic contract

Kind of budget.

recurrent

boolean

Boolean filter on recurring budgets.

open

boolean

Boolean filter on open budgets.

contracts

boolean

Boolean filter on contract budgets.

empty_tags

boolean

true: budgets without tags.

ids

string

Comma-separated internal budget IDs.

tags

string

Comma-separated tags.

search

string

Searches name, description and tags.

ordering

string

Sort order. Allowed fields: start_date, settlement_date, amount, end_date, name. Prefix a field with - for descending order.

all_budgets

boolean

true returns the budgets of all plans of the company, not only the forecast.

page

integer

>= 1

Page number, starting at 1. When paging through results, read this value from the next link and send it to the documented base URL.

page_size

integer

default: 100 >= 1 <= 1000

Number of records per page. Default 100, maximum 1000; larger values are reduced to 1000.

Responses

200

Paginated list of budgets with total.

application/json

object

count

required

Total number of matching records.

integer

next

required

URL of the next page, or null on the last page. The host name may differ from the documented base URL; read page from it and call the documented base URL.

string | null format: uri

previous

required

URL of the previous page, or null on the first page.

string | null format: uri

sum

Sum of the amounts of all matching budgets.

number

results

Total and the budgets of the current page.

object

total

Total amount of all matching budgets.

number

budgets

Array<object>

Budget as returned by the API.

object

Internal budget ID; used in the /budgets/{id}/ paths.

integer

category

Short form of a category, embedded in transactions and budgets.

object

integer

name

string

description

string

inter_category

Category of the linked budget in the other company.

integer | null

inter_category_name

Name of inter_category.

string | null

depending_categories

Categories the budget depends on.

Array

base_categories

Stored dependency categories (set via depending_categories).

Array

recurring_budget

Summary of the recurrence settings; null if the budget is not recurring.

object

frequency

string

frequency_multiplier

integer

sequence_type

string

sequence_term_size

integer

number

settlement_date

string format: date

start_date

string | null format: date

end_date

string | null format: date

account

Bank account ID.

integer | null

tags

Array<string>

integration_tags

Array<string> | null

is_adjusted

boolean

inter_budget

The linked budget in the other company of an intercompany budget, or null.

name

string

description

string

amount

Negative for outflows, positive for inflows.

number

rate

number

base

FS forecast and scenario, S scenario, F forecast.

string

Allowed values: FS S F

time_lags

Array<integer>

frequency

string

Allowed values: daily weekly monthly quarterly yearly ""

frequency_multiplier

integer

sequence_type

string

Allowed values: AP GP HP ""

sequence_term_size

integer

number

is_indefinite

boolean

external_id

Your own ID for the budget.

string | null

external_source

Free-text name of the system that created the budget.

string | null

inter_company

Company ID for an intercompany budget.

integer | null

source

ID of the budget this one was copied from, or null. Not related to external_source.

integer | null

Examples

ForecastBudgetPage

Forecast budget list

{
  "count": 1,
  "sum": -78700,
  "next": null,
  "previous": null,
  "results": {
    "total": -78700,
    "budgets": [
      {
        "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": []
      }
    ]
  }
}

401

The access token is invalid or has expired. Request a new token. The message is localized (see Accept-Language).

application/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "Invalid token."
}

Headers

WWW-Authenticate

string

Authentication scheme, Bearer.

Example

Bearer

403

No 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".

application/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "User must be authenticated to access this resource."
}