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 and Spend Limits.

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.

List Spend Limits

Lists Spend Limits belonging to this account

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

A page with a list of Spend Limits

400

Bad request

401

Unauthorized

403

Forbidden

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

Create Spend Limit

Creates a Spend Limit


SecurityOAuth2 
Request 
header Parameters
Idempotency-Key
required
string
 
Request Body schema: application/json
name
string
Name for the Spend Limit.


 
description
string
Description of what the Spend Limit is used for.


 
parent_budget_id
string
ID of parent Budget.


 
owner_user_ids
Array of strings or null
User IDs of the owners of the Spend Limit.


 
member_user_ids
Array of strings or null
User IDs of the members of the Spend Limit.


 
period_type
required
string (PeriodType) 
Period type of the Spend Limit 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 Spend Limit's limit blocks spend.


 Enum: "HARD" "SOFT"  
spend_type
required
string (SpendType) 
Whether this Spend Limit only can be spent from by cards provisioned by this Spend Limit. 


 Enum: "BUDGET_PROVISIONED_CARDS_ONLY" "NON_BUDGET_PROVISIONED_CARDS_ALLOWED"  
start_date
string or null <date> 
The UTC date when the Spend Limit should start counting.


 
end_date
string or null <date> 
The UTC date when the Spend Limit should stop counting.


 
limit_visibility
required
string (BudgetLimitVisibilityType) 
Determines if Spend Limit members are allowed to view the Spend Limit's limit.


 Enum: "SHARED" "PRIVATE"  
Responses 
200
The Spend Limit that was created


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": {
    },
  • "limit_visibility": "SHARED",
  • "templateId": "string",
  • "budget_type": "BUDGET"
}

Get Spend Limit

Retrieves a Spend Limit by ID


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
The Spend Limit that was retrieved


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": {
    },
  • "limit_visibility": "SHARED",
  • "templateId": "string",
  • "budget_type": "BUDGET"
}

Update Spend Limit

Updates a Spend Limit


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 Spend Limit.


 
description
string or null
Description of what the Spend Limit is used for.


 
owner_user_ids
Array of strings or null
User IDs of the owners of the Spend Limit.


 
member_user_ids
Array of strings or null
User IDs of the members of the Spend Limit.


 
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 Spend Limit's limit blocks spend.


 Enum: "HARD" "SOFT"  
spend_type
string or null
Whether this Spend Limit only can be spent from by cards provisioned by this Spend Limit. 


 Enum: "BUDGET_PROVISIONED_CARDS_ONLY" "NON_BUDGET_PROVISIONED_CARDS_ALLOWED"  
start_date
string or null <date> 
The UTC date when the Spend Limit should start counting.


 
end_date
string or null <date> 
The UTC date when the Spend Limit should stop counting.


 
limit_visibility
string or null
Determines if Spend Limit members are allowed to view the Spend Limit's limit.


 Enum: "SHARED" "PRIVATE"  
period_type
string or null
Period type of the Spend Limit e.g. MONTHLY.


 Enum: "WEEKLY" "MONTHLY" "QUARTERLY" "YEARLY" "ONE_TIME"  
Responses 
200
The Spend Limit that was updated


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",
  • "period_type": "WEEKLY"
}
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": {
    },
  • "limit_visibility": "SHARED",
  • "templateId": "string",
  • "budget_type": "BUDGET"
}

Archive a Spend Limit

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


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
The Spend Limit that was archived


400
Bad request


401
Unauthorized


403
Forbidden


404
Not Found


post/v1/budgets/{id}/archive
Request samples 
Budget Programs
Endpoints for Budget 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
A page with a list of Budget Programs


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


SecurityOAuth2 
Request 
header Parameters
Idempotency-Key
required
string
 
Request Body schema: application/json
existing_budget_ids
Array of strings or null
IDs for existing Spend Limits 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
The Budget Program that was created    


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
The Budget Program that was retrieved


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


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 Spend Limits 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
The Budget Program that was updated


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


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
The Budget Program that was deleted


400
Bad request


401
Unauthorized


403
Forbidden


404
Not Found


delete/v1/budget_programs/{id}
Request samples 
Budgets
Endpoints for Budgets data.



Create Budget

Creates a Budget


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
ID of parent Budget.


 
owner_user_ids
Array of strings or null
User IDs of the owners of the Budget.


 
period_recurrence_type
string
Period type of the Budget e.g. MONTHLY.


 Enum: "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
string or null
Whether the Spend Limit's limit blocks spend.


 Enum: "HARD" "SOFT"  
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.


 
Responses 
200
The Budget that was created


400
Bad request


401
Unauthorized


403
Forbidden


post/v2/budgets
Request samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string",
  • "owner_user_ids": [
    ],
  • "period_recurrence_type": "MONTHLY",
  • "amount": {
    },
  • "limit_type": "HARD",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}
Response samples 
application/json
{
  • "budget_id": "string",
  • "account_id": "string",
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string",
  • "owner_user_ids": [
    ],
  • "period_recurrence_type": "MONTHLY",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "amount": {
    },
  • "spend_budget_status": "ACTIVE",
  • "limit_type": "HARD"
}

Get Budget

Retrieves a Budget by ID


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
The Budget that was retrieved


400
Bad request


401
Unauthorized


403
Forbidden


404
Not Found


get/v2/budgets/{id}
Request samples 
Response samples 
application/json
{
  • "budget_id": "string",
  • "account_id": "string",
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string",
  • "owner_user_ids": [
    ],
  • "period_recurrence_type": "MONTHLY",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "amount": {
    },
  • "spend_budget_status": "ACTIVE",
  • "limit_type": "HARD"
}
Spend Limits (v2)
Endpoints for spend limits data.



Get Spend Limit

Retrieves a Spend Limit by ID


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
The Spend Limit that was retrieved


400
Bad request


401
Unauthorized


403
Forbidden


404
Not Found


get/v2/spend_limits/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "account_id": "string",
  • "name": "string",
  • "description": "string",
  • "parent_budget_id": "string"
}
Copyright © Brex 2019–2022. All rights reserved.