Company Budget Settings Reference

This reference documents all company-level budget settings.

Settings Entity

Field	Type	Required	Default	Description
`id`	string	Auto	-	Unique identifier
`companyId`	string	Yes	-	Parent company
`requireBudgetForBooking`	boolean	No	false	Whether budget is required
`defaultEnforcementMode`	enum	No	WARN_WHEN_EXCEEDED	Default for new budgets
`reserveBudgetAt`	enum	No	ON_REQUEST	When to reserve budget
`includePendingInAvailability`	boolean	No	true	Count pending as used
`pendingReservationTimeoutHours`	number	No	72	Hours before releasing
`approvalExpirationHours`	number	No	48	Hours to complete after approval
`creditRefundsToBudget`	boolean	No	true	Whether refunds credit budget
`refundCreditPeriod`	enum	No	CURRENT_PERIOD	Which period gets credit
`sendBudgetAlerts`	boolean	No	true	Whether to send alerts
`alertRecipients`	string[]	No	[]	Email addresses for alerts

Field Details

requireBudgetForBooking

Value	Behavior
`false`	Users without budgets can book freely
`true`	Users must have budget to book

Impact when true:

Users with no budget assignment cannot book
Ensures all travel is budget-tracked
May block contractors/guests unexpectedly

defaultEnforcementMode

Sets the default for new budgets.

Value	Description
`TRACK_ONLY`	No restrictions, monitoring only
`WARN_WHEN_EXCEEDED`	Show warning, allow proceed
`REQUIRE_APPROVAL_WHEN_EXCEEDED`	Route to approval
`BLOCK_WHEN_EXCEEDED`	Prevent booking

Usage:

Pre-fills enforcement mode in budget creation form
Individual budgets can override

reserveBudgetAt

Controls when budget is reserved.

Value	When Reserved	Trade-off
`ON_REQUEST`	Booking request created	Safest, locks budget early
`ON_APPROVAL`	Request approved	Balanced
`ON_CONFIRMATION`	Payment confirmed	Most flexible, highest risk

Recommended: ON_REQUEST for accurate availability

includePendingInAvailability

Value	Available Calculation
`true`	Total - Spent - Pending
`false`	Total - Spent

Impact:

true: Accurate real-time availability
false: Optimistic, may overspend

pendingReservationTimeoutHours

Hours before releasing abandoned reservations.

Range	1 - 720 (30 days)
Default	72 hours

Behavior:

Background job checks periodically
Reservations older than timeout are released
Released amount returns to available

approvalExpirationHours

Hours to complete booking after approval.

Range	1 - 168 (7 days max)
Default	48 hours

Behavior:

After approval, user has this long to pay
If expired, budget reservation released
User would need to re-request

creditRefundsToBudget

Value	Behavior
`true`	Refunds increase available budget
`false`	Refunds don't affect budget

refundCreditPeriod

Which period receives refund credit.

Value	Behavior
`CURRENT_PERIOD`	Credit to active period
`ORIGINAL_PERIOD`	Credit to booking's period

Considerations:

CURRENT_PERIOD: User gets budget back now
ORIGINAL_PERIOD: Accurate historical reporting

sendBudgetAlerts

Value	Behavior
`true`	Send threshold and violation alerts
`false`	No automated alerts

alertRecipients

Array of email addresses to receive alerts.

Example: finance@company.com, travel.admin@company.com

Default Values

When company settings aren't configured:

Setting	Default Value
requireBudgetForBooking	false
defaultEnforcementMode	WARN_WHEN_EXCEEDED
reserveBudgetAt	ON_REQUEST
includePendingInAvailability	true
pendingReservationTimeoutHours	72
approvalExpirationHours	48
creditRefundsToBudget	true
refundCreditPeriod	CURRENT_PERIOD
sendBudgetAlerts	true
alertRecipients	(empty)

Settings Interactions

Reservation Timing + Pending

Combination	Effect
ON_REQUEST + includePending=true	Most accurate
ON_REQUEST + includePending=false	Optimistic, concurrent risk
ON_CONFIRMATION + any	Highest overspend risk

Refunds + Period

Combination	Use Case
creditRefunds=true + CURRENT	Practical - user gets budget
creditRefunds=true + ORIGINAL	Reporting - accurate history
creditRefunds=false	Budget is one-way spend only

Company Settings Guide - How to configure
Consumption Lifecycle - How settings affect flow

Company Settings Reference