Budget Fields Reference

This reference documents all fields used in budget configuration.

Budget Entity

Core Fields

Field	Type	Required	Description
`name`	string	Yes	Display name (max 255 chars)
`description`	string	No	Detailed description
`costCenterId`	string	Yes	Associated cost center
`isActive`	boolean	Yes	Whether budget is active

Allocation Settings

Field	Type	Required	Default	Description
`allocationType`	enum	Yes	`PER_USER`	How budget is distributed
`amount`	number	Yes	-	Budget amount per period
`currency`	string	Yes	-	Currency code (e.g., USD)

Allocation Types:

PER_USER - Each user gets individual allocation
SHARED_POOL - All users share one pool

Supported Currencies:

USD, EUR, GBP, AED, SAR, IQD

Period Settings

Field	Type	Required	Default	Description
`periodType`	enum	Yes	-	Period duration
`periodStartDay`	number	Yes	-	Day of month (1-28)
`periodStartMonth`	number	No	1	Month for quarterly/yearly

Period Types:

MONTHLY - 1 month periods
QUARTERLY - 3 month periods
YEARLY - 12 month periods

Rollover Settings

Field	Type	Required	Default	Description
`rolloverPolicy`	enum	No	`NONE`	How unused budget rolls
`rolloverPercentage`	number	No	100	Percent to roll (1-100)
`maxRolloverAmount`	number	No	null	Maximum rollover cap

Rollover Policies:

NONE - No rollover, unused expires
PARTIAL - Percentage of unused rolls
FULL - All unused rolls

Enforcement Settings

Field	Type	Required	Default	Description
`enforcementMode`	enum	No	`WARN_WHEN_EXCEEDED`	What happens when exceeded
`notificationThresholds`	number[]	No	[50, 75, 90, 100]	Alert thresholds (%)

Enforcement Modes:

TRACK_ONLY - No restrictions
WARN_WHEN_EXCEEDED - Show warning
REQUIRE_APPROVAL_WHEN_EXCEEDED - Route to approval
BLOCK_WHEN_EXCEEDED - Block booking

System Fields

Field	Type	Description
`id`	string	Unique identifier
`companyId`	string	Parent company
`createdAt`	datetime	Creation timestamp
`updatedAt`	datetime	Last update timestamp
`deletedAt`	datetime	Soft delete timestamp

Budget Period Entity

Field	Type	Description
`id`	string	Unique identifier
`budgetId`	string	Parent budget
`periodNumber`	number	Sequential period number
`startDate`	datetime	Period start date
`endDate`	datetime	Period end date
`baseAmount`	number	Original allocation
`rolloverAmount`	number	Amount from previous period
`totalAllocated`	number	base + rollover
`spentAmount`	number	Confirmed spending
`pendingAmount`	number	Reserved, not confirmed
`remainingAmount`	number	total - spent - pending
`status`	enum	ACTIVE or CLOSED

Period Status:

ACTIVE - Current period, accepting transactions
CLOSED - Past period, no new transactions

User Budget Period Entity

For PER_USER budgets, each user has:

Field	Type	Description
`id`	string	Unique identifier
`userId`	string	User this belongs to
`budgetId`	string	Parent budget
`budgetPeriodId`	string	Parent period
`baseAmount`	number	Individual base allocation
`rolloverAmount`	number	Individual rollover
`totalAllocated`	number	Individual total
`spentAmount`	number	Individual spending
`pendingAmount`	number	Individual pending
`remainingAmount`	number	Individual remaining

Cost Center Entity

Field	Type	Required	Description
`id`	string	Auto	Unique identifier
`companyId`	string	Yes	Parent company
`code`	string	Yes	Unique code (max 50 chars)
`name`	string	Yes	Display name (max 255 chars)
`description`	string	No	Detailed description
`parentId`	string	No	Parent cost center
`isActive`	boolean	Yes	Whether active

Role Budget Assignment

Field	Type	Description
`id`	string	Unique identifier
`companyId`	string	Company scope
`roleId`	string	Assigned role
`budgetId`	string	Assigned budget

Constraints:

One budget per role per company
Unique constraint on (companyId, roleId)

User Budget Assignment

Field	Type	Required	Description
`id`	string	Auto	Unique identifier
`userId`	string	Yes	Assigned user
`budgetId`	string	Yes	Assigned budget
`effectiveFrom`	datetime	No	Start of assignment
`effectiveUntil`	datetime	No	End of assignment

Constraints:

One budget per user
Unique constraint on userId

Budget Transaction Entity

Field	Type	Description
`id`	string	Unique identifier
`budgetPeriodId`	string	Parent budget period
`userBudgetPeriodId`	string?	User period (for PER_USER budgets)
`userId`	string	User who made the transaction
`transactionType`	enum	Type of transaction
`amount`	number	Transaction amount
`currency`	string	Currency code
`referenceType`	string	What created this (ORDER, BOOKING_REQUEST)
`referenceId`	string	ID of the reference
`bookingRequestId`	string?	Related booking request
`orderId`	string?	Related order
`note`	string?	Optional note
`metadata`	object?	Additional data
`createdAt`	datetime	When created

Transaction Types:

BOOKING_PENDING - Budget reserved for booking
BOOKING_COMPLETED - Booking confirmed
BOOKING_CANCELLED - Reservation released
REFUND - Amount credited back
ROLLOVER_IN - Amount received from previous period
ROLLOVER_OUT - Amount transferred to next period

Budget Violation Log Entity

Records when users exceed their budget (for audit and analytics):

Field	Type	Description
`id`	string	Unique identifier
`companyId`	string	Company context
`userId`	string	User who exceeded
`budgetId`	string	Budget that was exceeded
`budgetPeriodId`	string	Period when exceeded
`referenceType`	string	BOOKING_REQUEST or ORDER
`referenceId`	string	Reference ID
`requestedAmount`	number	Amount user tried to book
`availableAmount`	number	Amount available at time
`excessAmount`	number	How much over budget
`currency`	string	Currency code
`enforcementMode`	enum	Mode in effect
`action`	string	Action taken (ALLOW, WARN, REQUIRE_APPROVAL, BLOCK)
`createdAt`	datetime	When violation occurred

Validation Rules

Budget Creation

Field	Validation
name	Required, max 255 chars
amount	Required, > 0
currency	Required, valid currency code
periodType	Required, valid enum
periodStartDay	Required, 1-28
periodStartMonth	Required for QUARTERLY/YEARLY, 1-12
rolloverPercentage	If PARTIAL, 1-100
maxRolloverAmount	If set, > 0

Cost Center Creation

Field	Validation
code	Required, unique per company, max 50 chars
name	Required, max 255 chars
parentId	If set, must exist and be in same company

Creating Budgets - How to use these fields
Cost Centers - Cost center management

Budget Fields Reference

On this page