API Reference
System Status

Create a budget

post
https://gateway.stage.bill.com/connect/v3/spend/budgets

Create a new budget for a company.

See Budgets and Users in the Guides section for more information, sample requests, and responses.

Body Params
string
required
length ≥ 1

Budget name

string

Budget description

owners
array of strings
required
length ≥ 1

List of BILL-generated user IDs or UUIDs of budget owners. You must specify at least one budget owner.

owners*
members
array of strings

List of BILL-generated user IDs or UUIDs of budget members

members
observers
array of strings

List of BILL-generated user IDs or UUIDs of budget observers

observers
date | null

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

string
enum
required

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.
Allowed:
int64
1 to 12

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.

string

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.

boolean

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

boolean

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

number

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

boolean

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.

string

BILL-generated ID or UUID of the parent budget. Set this field if this budget is a child budget.

boolean

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

boolean

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.

number

Spend limit for the initial budget period.

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

number

Spend goal for a limitless budget.

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

number

Spend limit for all future budget periods.

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

number

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.

string
enum

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

Allowed:
Headers
string | null

Access token for Spend & Expense API authentication

Responses

Updated 4 months ago

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 4 months ago