Budgets API (1.0)

Download OpenAPI specification:Download

The budgets API lets you manage your Brex budgets.

Budgets

Endpoints for budgets data.

List Budgets

Lists Budgets belonging to this account

SecurityOAuth2
Request
query Parameters
cursor
string or null
limit
integer or null <int32>
Responses
200

listBudgets 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v1/budgets
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create Budget

Creates a Budget. This endpoint requires budget management. If your account does not have access to budget management features, a 403 response status will be returned. If this is the case and you want to gain access to this endpoint, please contact Brex support.

SecurityOAuth2
Request
header Parameters
Idempotency-Key
required
string
Request Body schema: application/json
name
string

Name for the Budget.

description
string

Description of what the Budget is used for.

parent_budget_id
string or null

ID of parent Budget.

owner_user_ids
Array of strings or null

User IDs of the owners of the Budget.

member_user_ids
Array of strings or null

User IDs of the members of the Budget.

period_type
required
string (PeriodType)

Period type of the Budget e.g. MONTHLY.

Enum: "WEEKLY" "MONTHLY" "QUARTERLY" "YEARLY" "ONE_TIME"
required
object (Money)

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_type
required
string (LimitType)

Whether the Budget limit blocks spend.

Enum: "HARD" "SOFT"
spend_type
required
string (SpendType)

Whether this Budget only can be spent from by cards provisioned by this Budget.

Enum: "BUDGET_PROVISIONED_CARDS_ONLY" "NON_BUDGET_PROVISIONED_CARDS_ALLOWED"
start_date
string or null <date>

The UTC date when the Budget should start counting.

end_date
string or null <date>

The UTC date when the Budget should stop counting.

limit_visibility
required
string (BudgetLimitVisibilityType)

Determines if budget members are allowed to view the budget limit.

Enum: "SHARED" "PRIVATE"
Responses
200

createBudget 200 response

400

Bad request

401

Unauthorized

403

Forbidden

post/v1/budgets
Request samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string",
  • "owner_user_ids": [
    ],
  • "member_user_ids": [
    ],
  • "period_type": "WEEKLY",
  • "limit": {
    },
  • "limit_type": "HARD",
  • "spend_type": "BUDGET_PROVISIONED_CARDS_ONLY",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "limit_visibility": "SHARED"
}
Response samples
application/json
{
  • "budget_id": "string",
  • "account_id": "string",
  • "creator_user_id": "string",
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string",
  • "owner_user_ids": [
    ],
  • "member_user_ids": [
    ],
  • "period_type": "WEEKLY",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "limit": {
    },
  • "budget_status": "APPROVED",
  • "limit_type": "HARD",
  • "spend_type": "BUDGET_PROVISIONED_CARDS_ONLY",
  • "current_period_balance": {
    }
}

Get Budget

Retrieves a Budget by ID

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getBudgetById 200 response

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

get/v1/budgets/{id}
Request samples
Response samples
application/json
{
  • "budget_id": "string",
  • "account_id": "string",
  • "creator_user_id": "string",
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string",
  • "owner_user_ids": [
    ],
  • "member_user_ids": [
    ],
  • "period_type": "WEEKLY",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "limit": {
    },
  • "budget_status": "APPROVED",
  • "limit_type": "HARD",
  • "spend_type": "BUDGET_PROVISIONED_CARDS_ONLY",
  • "current_period_balance": {
    }
}

Update Budget

Updates a Budget. This endpoint requires budget management. If your account does not have access to budget management features, a 403 response status will be returned. If this is the case and you want to gain access to this endpoint, please contact Brex support.

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
required
string
Request Body schema: application/json
name
string or null

Name for the Budget.

description
string or null

Description of what the Budget is used for.

owner_user_ids
Array of strings or null

User IDs of the owners of the Budget.

member_user_ids
Array of strings or null

User IDs of the members of the Budget.

object 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_type
string or null

Whether the Budget limit blocks spend.

Enum: "HARD" "SOFT"
spend_type
string or null

Whether this Budget only can be spent from by cards provisioned by this Budget.

Enum: "BUDGET_PROVISIONED_CARDS_ONLY" "NON_BUDGET_PROVISIONED_CARDS_ALLOWED"
start_date
string or null <date>

The UTC date when the Budget should start counting.

end_date
string or null <date>

The UTC date when the Budget should stop counting.

limit_visibility
string or null

Determines if budget members are allowed to view the budget limit.

Enum: "SHARED" "PRIVATE"
Responses
200

updateBudget 200 response

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

put/v1/budgets/{id}
Request samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner_user_ids": [
    ],
  • "member_user_ids": [
    ],
  • "limit": {
    },
  • "limit_type": "HARD",
  • "spend_type": "BUDGET_PROVISIONED_CARDS_ONLY",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "limit_visibility": "SHARED"
}
Response samples
application/json
{
  • "budget_id": "string",
  • "account_id": "string",
  • "creator_user_id": "string",
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string",
  • "owner_user_ids": [
    ],
  • "member_user_ids": [
    ],
  • "period_type": "WEEKLY",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "limit": {
    },
  • "budget_status": "APPROVED",
  • "limit_type": "HARD",
  • "spend_type": "BUDGET_PROVISIONED_CARDS_ONLY",
  • "current_period_balance": {
    }
}

Budget Programs

Endpoints for budgets programs data.

List Budget Programs

Lists Budget Programs belonging to this account

SecurityOAuth2
Request
query Parameters
cursor
string or null
limit
integer or null <int32>
Responses
200

listBudgetPrograms 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v1/budget_programs
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create Budget Program

Creates a Budget Program. This endpoint requires budget management. If your account does not have access to budget management features, a 403 response status will be returned. If this is the case and you want to gain access to this endpoint, please contact Brex support.

SecurityOAuth2
Request
header Parameters
Idempotency-Key
required
string
Request Body schema: application/json
existing_budget_ids
Array of strings or null

IDs for existing budgets associated with this Budget Program.

required
Array of objects (CreateBudgetBlueprintRequest)
object or null

A filter used to determine if a user adheres to a Budget Program.

name
required
string
description
string or null
Responses
200

createBudgetProgram 200 response

400

Bad request

401

Unauthorized

403

Forbidden

post/v1/budget_programs
Request samples
application/json
{
  • "existing_budget_ids": [
    ],
  • "budget_blueprints": [
    ],
  • "employee_filter": {
    },
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "budget_blueprints": [
    ],
  • "existing_budget_ids": [
    ],
  • "employee_filter": {
    },
  • "budget_program_status": "BUDGET_PROGRAM_STATUS_ACTIVE",
  • "creator_user_id": "string",
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24"
}

Get Budget Program

Retrieves a Budget Program by ID

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getBudgetProgramById 200 response

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

get/v1/budget_programs/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "budget_blueprints": [
    ],
  • "existing_budget_ids": [
    ],
  • "employee_filter": {
    },
  • "budget_program_status": "BUDGET_PROGRAM_STATUS_ACTIVE",
  • "creator_user_id": "string",
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24"
}

Update Budget Program

Updates a Budget Program. This endpoint requires budget management. If your account does not have access to budget management features, a 403 response status will be returned. If this is the case and you want to gain access to this endpoint, please contact Brex support.

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
required
string
Request Body schema: application/json
existing_budget_ids
Array of strings or null

IDs for existing budgets associated with this Budget Program.

Array of objects or null (UpdateBudgetBlueprintRequest)

The Blueprints to update the budget program with. Blueprints without an ID are treated as new blueprints to be created. Blueprints that exist currently on the Budget Program, but are missing from the input, will be deleted.

object or null

A filter used to determine if a user adheres to a Budget Program.

name
string or null
description
string or null
Responses
200

updateBudgetProgram 200 response

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

put/v1/budget_programs/{id}
Request samples
application/json
{
  • "existing_budget_ids": [
    ],
  • "budget_blueprints": [
    ],
  • "employee_filter": {
    },
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "budget_blueprints": [
    ],
  • "existing_budget_ids": [
    ],
  • "employee_filter": {
    },
  • "budget_program_status": "BUDGET_PROGRAM_STATUS_ACTIVE",
  • "creator_user_id": "string",
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24"
}

Delete Budget Program

Delete a Budget Program by ID. This endpoint requires budget management. If your account does not have access to budget management features, a 403 response status will be returned. If this is the case and you want to gain access to this endpoint, please contact Brex support.

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

deleteBudgetProgram 200 response

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

delete/v1/budget_programs/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "budget_blueprints": [
    ],
  • "existing_budget_ids": [
    ],
  • "employee_filter": {
    },
  • "budget_program_status": "BUDGET_PROGRAM_STATUS_ACTIVE",
  • "creator_user_id": "string",
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24"
}
Copyright © Brex 2019–2022. All rights reserved.