Budgets API (1.0)

Download OpenAPI specification:Download

Admin: developer-access@brex.com URL: https://brex.com

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
required
string
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": {
    }
}

Archive a budget

Archives a budget, making it unusable for future expenses and removing it from the UI


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
archiveBudget 200 response


400
Bad request


401
Unauthorized


403
Forbidden


404
Not Found


post/v1/budgets/{id}/archive
Request samples 
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.
If your account does not have access to budget program 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.