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.

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.

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 $200 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": 200,
  "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": 200.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.

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.