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.

FieldDescription
firstNameUser first name
lastNameUser last name
emailUser email address
roleUser 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.

FieldDescription
nameBudget name
ownersIn 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.
recurringIntervalInterval after which the budget is reset
limitSpend limit of the initial budget
recurringLimitSpend 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.

FieldDescription
budgetIdBILL-generated ID of the budget
userIdBILL-generated ID of the user
limitCurrent budget spend limit assigned to the user
recurringLimitFuture 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.