Budgets and Users
In this section, we walk through understanding budgets and budget users at BILL.
What is a budget?
A budget enables you to set spending policies and keep entire teams of users on budget. You can set up multiple budgets based on different needs, such as expiration date, limit, and reset interval.
Who is a Spend & Expense user?
As a Spend & Expense user, you can perform a set of Spend & Expense operations based on the user role. BILL provides a set of Spend & Expense user roles.
- Administrator
- Auditor
- Bookkeeper
- Member
- No access
See What are the user roles in BILL Spend & Expense? in the BILL Help Center to learn about user roles.
Creating a user
As a user with the ADMIN
user role, you can use the Spend & Expense API to create other users and also manage user access based on roles. In addition, you can create API tokens with your Spend & Expense account.
IMPORTANT
A Spend & Expense API user must have the
ADMIN
user role to create an API token.
In your POST /v3/spend/users
request, set the required fields.
Field | Description |
---|---|
firstName | User first name |
lastName | User last name |
email | User email address |
role | User role. See What are the user roles in BILL Spend & Expense? In the BILL Help Center to learn about user roles. |
Sample request
In this cURL example, a user is created with the specified details. The role
is set as the MEMBER
user role. A budget member can view their own budgets, cards, and transactions.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/spend/users' \
--header 'apiToken: {api_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"email": "[email protected]",
"firstName": "Clark",
"lastName": "Spenderson",
"role": "MEMBER"
}'
Response
In the response, a BILL-generated user id
is available. You can use this user id
for other Spend & Expense operations.
{
"id": "{user_id}",
"firstName": "Clark",
"lastName": "Spenderson",
"email": "[email protected]",
"retired": false,
"role": "MEMBER",
"createdTime": "2024-12-15T21:10:30.000+00:00"
}
See the /v3/spend/users API for more information about the complete list of Spend & Expense user operations.
Creating a budget
In your POST /v3/spend/budgets
request, set the required fields.
Field | Description |
---|---|
name | Budget name |
owners | In the owners array, set the user ID of each budget owner. You can get the ID of the current user with GET /v3/spend/users/current . |
recurringInterval | Interval after which the budget is reset |
limit | Spend limit of the initial budget |
recurringLimit | Spend limit of all future budgets. This field is required if recurringInterval is set as a value other than NONE . |
See the /v3/spend/budgets API for more information about the other budget fields you can set.
Sample request
In this cURL example, a budget is created with the specified details. Policy rules and an owner is set for the budget. You can get the ID of the current user with GET /v3/spend/users/current
.
In this example, a monthly budget is set up with an initial spend limit of $100
and a recurring spend limit of $200
.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/spend/budgets' \
--header 'apiToken: {api_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"name": "Happy Music Supplies monthly spending budget",
"owners": [
"{user_id}"
],
"recurringInterval": "MONTHLY",
"limit": 100,
"recurringLimit": 200
}'
Response
In the response, a BILL-generated budget id
is available. The currentPeriod
object provides information about the current budget. After the MONTHLY
recurring interval, the budget will be reset based on the specified endDate
.
{
"id": "{budget_id}",
"name": "Happy Music Supplies monthly spending budget",
"retired": false,
"startDate": "2024-12-15",
"recurringInterval": "MONTHLY",
"timezone": "US/Eastern",
"autoAddUsers": false,
"receiptRequired": true,
"carryOver": false,
"budgetGroup": false,
"shareFunds": "SHARE_MANUALLY",
"recurringLimit": 200.00,
"limitlessOverspend": false,
"currentPeriod": {
"startDate": "2024-12-01",
"endDate": "2025-01-01",
"limit": 100.00,
"overspendBuffer": 0.00,
"assigned": 0.00,
"spent": {
"cleared": 0.00,
"pending": 0.00,
"total": 0.00
}
},
"default": false
}
See the /v3/spend/budgets API for more information about the complete list of Spend & Expense budget operations.
Adding a user to a budget
When you add a user to a budget, the user can spend from the assigned budget funds.
In your PUT /v3/spend/budgets/{budgetId}/members/{userId}
request, set the required fields.
Field | Description |
---|---|
budgetId | BILL-generated ID of the budget |
userId | BILL-generated ID of the user |
limit | Current budget spend limit assigned to the user |
recurringLimit | Future budgets spend limit assigned to the user This field is required if the budget recurringInterval is set as a value other than NONE . You can get the budget details with GET /v3/spend/budgets/{budgetId} . |
See the /v3/spend/budgets/{budgetId}/members/{userId} API for more information about the other budget fields you can set.
Sample request
In this cURL example, a user is added to a budget that resets on a monthly basis. User-level policy rules are set for spending limits in the current budget and all future budgets.
In this example, the user is assigned a current budget spend limit of $50
and future budgets spend limit of $100
.
curl --request PUT \
--url 'https://gateway.stage.bill.com/connect/v3/spend/budgets/{budget_id}/members/{user_id}' \
--header 'apiToken: {api_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"limit": "50",
"recurringLimit": "100"
}'
Response
In the response, the budget spend limit policy rules are assigned to the specified user.
{
"userId": "{user_id}",
"spent": 0.00,
"limit": 50.00,
"recurringLimit": 100.00,
"recurring": true,
"budgetRole": "MEMBER",
"name": "Clark Spenderson",
"retired": false,
"shareBudgetFunds": false
}
See the /v3/spend/budgets API for more information about the complete list of Spend & Expense budget operations.
Updated about 2 months ago