Sign in

v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB
budgets

Update a budget

Update details about an existing budget.

patch/v3/spend/budgets/{budgetId}

Path parameters

budgetIdstring required

BILL-generated ID or UUID of the budget

Example:{{se_budget_uuid}}

Headers

apiTokenstring nullable

Access token for Spend & Expense API authentication

Example:{{api_token}}

Request body

namestring

Budget name

descriptionstring

Budget description

expirationDatestring date nullable

Budget expiration date. This value is in the yyyy-MM-dd format.

recurringInterval'NONE' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY'

Interval after which the budget is reset. By default, BILL uses the timezone of the company's billing address to reset a budget at 12 AM.

  • NONE: Never
  • DAILY: Each day at 12 AM
  • WEEKLY: Each Monday at 12 AM
  • MONTHLY: On the 1st of every month at 12 AM
  • QUARTERLY: Once every 3 months, on the 1st of the month at 12 AM. Set the first month with recurMonth.
  • YEARLY: Once every year, on the 1st of the month at 12 AM. Set the month with recurMonth.
recurMonthinteger

The month in which the budget will recur. Set this field only when recurringInterval is set as QUARTERLY or YEARLY. The default value is the current month.

timezonestring

Timezone in which the budget funds are reset. The default value is the timezone of the company's billing address.

Set this field in the US/{time_zone} format. For example, US/Pacific or US/Mountain.

autoAddUsersboolean

Set as true to automatically add all new users to this budget

receiptRequiredboolean

Set as true if a receipt is required for transactions in the budget

maxTxSizenumber

Maximum transaction size in the budget. Any single transaction for an amount greater than maxTxSize will be declined.

carryOverboolean

Set as true for any budget funds assigned to users and vendor cards to carry over from one budget period to the next. The budget period is set with recurringInterval.

limitlessOverspendboolean

Set as true for enabling spend amounts over the budget limit.

Note: You cannot set this field as true for budgets with recurringInterval set as DAILY or WEEKLY.

limitnumber

Spend limit for the initial budget period.

Note: This field is required unless limitlessOverspend is set as true.

limitlessGoalnumber

Spend goal for a limitless budget.

Note: You can set this field when limitlessOverspend is set as true.

recurringLimitnumber

Spend limit for all future budget periods.

Note: This field is required when recurringInterval is set as any value other than NONE.

overspendBuffernumber

Spend amount allowed above the budget limit before transactions are declined.

Note: You cannot set this field when limitlessOverspend is set as true or for budgets with recurringInterval as DAILY or WEEKLY.

shareFunds'DO_NOT_SHARE' | 'SHARE_MANUALLY'

Rule for how the budget funds are shared with budget members. The default value is SHARE_MANUALLY.

Example request

{
  "limit": 300
}

Response

Update a budget response

idstring

BILL-generated ID of the budget

uuidstring

BILL-generated UUID of the budget

namestring

Budget name

descriptionstring

Budget description

retiredboolean

Set as true if the budget is retired

startDatestring date

Budget start date

expirationDatestring date

Budget expiration date

recurringInterval'NONE' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY'

Interval after which the budget is reset. By default, BILL uses the timezone of the company's billing address to reset a budget at 12 AM.

  • NONE: Never
  • DAILY: Each day at 12 AM
  • WEEKLY: Each Monday at 12 AM
  • MONTHLY: On the 1st of every month at 12 AM
  • QUARTERLY: Once every 3 months, on the 1st of the month at 12 AM. Set the first month with recurMonth.
  • YEARLY: Once every year, on the 1st of the month at 12 AM. Set the month with recurMonth.
timezonestring

Timezone in which the budget funds are reset

autoAddUsersboolean

Set as true to automatically add all new users to this budget

receiptRequiredboolean

Set as true if a receipt is required for transactions in the budget

maxTxSizenumber

Maximum transaction size in the budget. Any single transaction for an amount greater than maxTxSize will be declined.

carryOverboolean

Set as true for any budget funds assigned to users and vendor cards to carry over from one budget period to the next. The budget period is set with recurringInterval.

defaultboolean

Set as true if the current budget is set as the default budget for the company

parentBudgetIdstring

BILL-generated ID of the parent budget

parentBudgetUuidstring

BILL-generated UUID of the parent budget

budgetGroupboolean

Set as true if this budget is a budget group. A budget group can be set as a parent of other budgets.

shareFunds'DO_NOT_SHARE' | 'SHARE_MANUALLY' | 'SHARE_WITH_ALL_OWNERS' | 'SHARE_WITH_ALL_MEMBERS' | 'SHARE_ALL_OWNERS_BUT_MEMBERS_MANUALLY'

Rule for how the budget funds are shared with budget members. The default value is SHARE_MANUALLY.

recurringLimitnumber

Spend limit for all future budget periods

limitlessOverspendboolean

Set as true for enabling spend amounts over the budget limit

limitlessGoalnumber

Spend goal for a limitless budget