Skip to content
APIs/Budgets & Limits/
/
Get Budget

Budgets API (1.0)

The budgets API lets you manage your Brex Budgets and Spend Limits.

Download OpenAPI description
budgets_api.json
budgets_api.yaml
Overview
URL
https://brex.com
Admin
developer-support@brex.com
Languages
Servers
Production
https://api.brex.com
Staging (Note: This is not a sandbox. It will not work with customer tokens.)
https://api-staging.brex.com

Spend Limits (v1)

Endpoints for Spend Limits data. Please note that /v1/budgets targets spend limits, and will soon be deprecated in favor of /v2/spend_limits.

Operations

Budget Programs

Endpoints for Budget Programs data.

Operations

Budgets

Endpoints for Budgets data.

Operations

List Budgets

Request

Retrieves a list of Budgets

Security
OAuth2(Required scopes:
budgets.readonly
budgets
)
Query
cursorstring or null
limitinteger or null(int32)
curl -i -X GET \
  https://api.brex.com/v2/budgets \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A page with a list of Budgets

Bodyapplication/json
next_cursorstring or null
itemsArray of objects(SpendBudget)required
items[].​budget_idstringrequired

Unique ID for the Budget.

items[].​account_idstringrequired

The Brex account this Budget belongs to.

items[].​namestringrequired

Name for the Budget.

items[].​descriptionstring or null

Description of what the Budget is used for.

items[].​parent_budget_idstring or null

ID of parent Budget.

items[].​owner_user_idsArray of stringsrequired

User IDs of the owners of the Budget.

items[].​period_recurrence_typestringrequired

Period type of the Budget e.g. MONTHLY.

Enum"WEEKLY""MONTHLY""QUARTERLY""YEARLY""ONE_TIME"
items[].​start_datestring or null(date)

The date when the Budget should start counting.

items[].​end_datestring or null(date)

The date when the Budget should stop counting.

items[].​amountobject or null

Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

items[].​spend_budget_statusstringrequired

Status of the Budget e.g. ACTIVE.

Enum"ACTIVE""ARCHIVED""DELETED""EXPIRED"
items[].​limit_typestring or null

Whether the Budget amount blocks spend.

Enum"HARD""SOFT"
Response
application/json
{
  "next_cursor": "string",
  "items": [
    { … }
  ]
}

Create Budget

Request

Creates a Budget

Security
OAuth2(Required scopes:
budgets
)
Headers
Idempotency-Keystringrequired
Bodyapplication/jsonrequired
namestringrequired

Name for the Budget.

descriptionstringrequired

Description of what the Budget is used for.

parent_budget_idstringrequired

ID of parent Budget.

owner_user_idsArray of strings or null

User IDs of the owners of the Budget.

period_recurrence_typestringrequired

Period type of the Budget e.g. MONTHLY.

Enum"WEEKLY""MONTHLY""QUARTERLY""YEARLY""ONE_TIME"
amountobject(Money)required

Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

amount.​amountinteger(int64)required

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.

Example: 700
amount.​currencystring or null

The type of currency, in ISO 4217 format.

Default "USD"
Example: "USD"
limit_typestring or null

Whether the Budget amount blocks spend.

Enum"HARD""SOFT"
start_datestring or null(date)

The date when the Budget should start counting.

end_datestring or null(date)

The date when the Budget should stop counting.

curl -i -X POST \
  https://api.brex.com/v2/budgets \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "name": "string",
    "description": "string",
    "parent_budget_id": "string",
    "owner_user_ids": [
      "string"
    ],
    "period_recurrence_type": "WEEKLY",
    "amount": {
      "amount": 700,
      "currency": "USD"
    },
    "limit_type": "HARD",
    "start_date": "2019-08-24",
    "end_date": "2019-08-24"
  }'

Responses

The Budget that was created

Bodyapplication/json
budget_idstringrequired

Unique ID for the Budget.

account_idstringrequired

The Brex account this Budget belongs to.

namestringrequired

Name for the Budget.

descriptionstring or null

Description of what the Budget is used for.

parent_budget_idstring or null

ID of parent Budget.

owner_user_idsArray of stringsrequired

User IDs of the owners of the Budget.

period_recurrence_typestringrequired

Period type of the Budget e.g. MONTHLY.

Enum"WEEKLY""MONTHLY""QUARTERLY""YEARLY""ONE_TIME"
start_datestring or null(date)

The date when the Budget should start counting.

end_datestring or null(date)

The date when the Budget should stop counting.

amountobject or null

Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

spend_budget_statusstringrequired

Status of the Budget e.g. ACTIVE.

Enum"ACTIVE""ARCHIVED""DELETED""EXPIRED"
limit_typestring or null

Whether the Budget amount blocks spend.

Enum"HARD""SOFT"
Response
application/json
{
  "budget_id": "string",
  "account_id": "string",
  "name": "string",
  "description": "string",
  "parent_budget_id": "string",
  "owner_user_ids": [
    "string"
  ],
  "period_recurrence_type": "WEEKLY",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "amount": {
    "amount": 700,
    "currency": "USD"
  },
  "spend_budget_status": "ACTIVE",
  "limit_type": "HARD"
}

Get Budget

Request

Retrieves a Budget by ID

Security
OAuth2(Required scopes:
budgets.readonly
budgets
)
Path
idstringrequired
curl -i -X GET \
  'https://api.brex.com/v2/budgets/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The Budget that was retrieved

Bodyapplication/json
budget_idstringrequired

Unique ID for the Budget.

account_idstringrequired

The Brex account this Budget belongs to.

namestringrequired

Name for the Budget.

descriptionstring or null

Description of what the Budget is used for.

parent_budget_idstring or null

ID of parent Budget.

owner_user_idsArray of stringsrequired

User IDs of the owners of the Budget.

period_recurrence_typestringrequired

Period type of the Budget e.g. MONTHLY.

Enum"WEEKLY""MONTHLY""QUARTERLY""YEARLY""ONE_TIME"
start_datestring or null(date)

The date when the Budget should start counting.

end_datestring or null(date)

The date when the Budget should stop counting.

amountobject or null

Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

spend_budget_statusstringrequired

Status of the Budget e.g. ACTIVE.

Enum"ACTIVE""ARCHIVED""DELETED""EXPIRED"
limit_typestring or null

Whether the Budget amount blocks spend.

Enum"HARD""SOFT"
Response
application/json
{
  "budget_id": "string",
  "account_id": "string",
  "name": "string",
  "description": "string",
  "parent_budget_id": "string",
  "owner_user_ids": [
    "string"
  ],
  "period_recurrence_type": "WEEKLY",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "amount": {
    "amount": 700,
    "currency": "USD"
  },
  "spend_budget_status": "ACTIVE",
  "limit_type": "HARD"
}

Update Budget

Request

Updates a Budget

Security
OAuth2(Required scopes:
budgets
)
Path
idstringrequired
Headers
Idempotency-Keystringrequired
Bodyapplication/jsonrequired
namestring or null

Name for the Budget.

descriptionstring or null

Description of what the Budget is used for.

parent_budget_idstring or null

ID of parent Budget.

owner_user_idsArray of strings or null

User IDs of the owners of the Budget.

period_recurrence_typestring or null

Period type of the Budget e.g. MONTHLY.

Enum"WEEKLY""MONTHLY""QUARTERLY""YEARLY""ONE_TIME"
amountobject or null

Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

limit_typestring or null

Whether the Budget amount blocks spend.

Enum"HARD""SOFT"
start_datestring or null(date)

The date when the Budget should start counting.

end_datestring or null(date)

The date when the Budget should stop counting.

curl -i -X PUT \
  'https://api.brex.com/v2/budgets/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "name": "string",
    "description": "string",
    "parent_budget_id": "string",
    "owner_user_ids": [
      "string"
    ],
    "period_recurrence_type": "WEEKLY",
    "amount": {
      "amount": 700,
      "currency": "USD"
    },
    "limit_type": "HARD",
    "start_date": "2019-08-24",
    "end_date": "2019-08-24"
  }'

Responses

The Budget that was updated

Bodyapplication/json
budget_idstringrequired

Unique ID for the Budget.

account_idstringrequired

The Brex account this Budget belongs to.

namestringrequired

Name for the Budget.

descriptionstring or null

Description of what the Budget is used for.

parent_budget_idstring or null

ID of parent Budget.

owner_user_idsArray of stringsrequired

User IDs of the owners of the Budget.

period_recurrence_typestringrequired

Period type of the Budget e.g. MONTHLY.

Enum"WEEKLY""MONTHLY""QUARTERLY""YEARLY""ONE_TIME"
start_datestring or null(date)

The date when the Budget should start counting.

end_datestring or null(date)

The date when the Budget should stop counting.

amountobject or null

Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

spend_budget_statusstringrequired

Status of the Budget e.g. ACTIVE.

Enum"ACTIVE""ARCHIVED""DELETED""EXPIRED"
limit_typestring or null

Whether the Budget amount blocks spend.

Enum"HARD""SOFT"
Response
application/json
{
  "budget_id": "string",
  "account_id": "string",
  "name": "string",
  "description": "string",
  "parent_budget_id": "string",
  "owner_user_ids": [
    "string"
  ],
  "period_recurrence_type": "WEEKLY",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "amount": {
    "amount": 700,
    "currency": "USD"
  },
  "spend_budget_status": "ACTIVE",
  "limit_type": "HARD"
}

Archive a Budget

Request

Archives a Budget, making any Spend Limits beneath it unusable for future expenses and removing it from the UI

Security
OAuth2(Required scopes:
budgets
)
Path
idstringrequired
curl -i -X POST \
  'https://api.brex.com/v2/budgets/{id}/archive' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The Budget that was archived

Spend Limits (v2)

Endpoints for spend limits data.

Operations
Copyright © Brex 2019–2026. All rights reserved.