Consumption Lifecycle

When users book travel, budget consumption goes through several states. Understanding this lifecycle is essential for accurate budget tracking and management.

Transaction States

Budget transactions move through these states:

State	Description	Impact on Available Budget
Pending	Budget reserved, booking not confirmed	Reduces remaining amount
Spent	Booking confirmed, budget consumed	Permanently consumed
Released	Reservation cancelled, budget returned	Returns to remaining
Refunded	Spent amount partially/fully returned	Returns to remaining

Transaction Types

The system records these transaction types:

Transaction Type	When Created	Amount Impact
`BOOKING_PENDING`	Booking started, budget reserved	+pending, -remaining
`BOOKING_COMPLETED`	Booking confirmed	+spent, -pending
`BOOKING_CANCELLED`	Pending booking cancelled	-pending, +remaining
`REFUND`	Completed booking refunded	-spent, +remaining
`ROLLOVER_IN`	Amount received from previous period	+rollover
`ROLLOVER_OUT`	Amount transferred to next period	Documents rollover

Budget Amount Fields

Each budget period tracks several monetary fields:

Field	Description
Base Amount	Original allocation for this period
Rollover Amount	Carried from previous period
Total Allocated	Base + Rollover
Spent Amount	Confirmed transactions
Pending Amount	Reserved, not yet confirmed
Remaining Amount	Total Allocated - Spent - Pending

The Reservation Flow

Step 1: Budget Reserved (Pending)

When a user starts a booking:

User selects a $500 flight
System checks budget availability ($2,000 remaining)
System reserves $500 (adds to pending, subtracts from remaining)
User proceeds to payment

Before:

Field	Amount
Total Allocated	$5,000
Spent	$3,000
Pending	$0
Remaining	$2,000

After Reservation:

Field	Amount	Change
Total Allocated	$5,000	-
Spent	$3,000	-
Pending	$500	+$500
Remaining	$1,500	-$500

Step 2a: Booking Confirmed (Spent)

When payment succeeds:

User completes payment
System processes payment successfully
System confirms the reservation (moves from pending to spent)
User receives booking confirmation

After Confirmation:

Field	Amount	Change
Total Allocated	$5,000	-
Spent	$3,500	+$500
Pending	$0	-$500
Remaining	$1,500	-

Step 2b: Booking Cancelled (Released)

If booking is cancelled before confirmation:

User cancels the booking
System releases the reservation
Pending amount decreases, remaining amount increases
Budget returns to its original state

After Release:

Field	Amount	Change
Total Allocated	$5,000	-
Spent	$3,000	-
Pending	$0	-$500
Remaining	$2,000	+$500

The budget returns to its original state.

Step 3: Refund Processed

If a confirmed booking is refunded:

Supplier processes the refund
System credits the refund to the budget
Spent amount decreases, remaining amount increases
User has more budget available for future bookings

After Refund:

Field	Amount	Change
Total Allocated	$5,000	-
Spent	$3,000	-$500
Pending	$0	-
Remaining	$2,000	+$500

Reservation Timing

The company settings control when budget is reserved:

Timing	When Reserved	Trade-off
On Request	When booking request created	Prevents overspending from concurrent requests
On Approval	When request approved	Budget not locked during approval wait
On Confirmation	When payment confirmed	Most flexible, highest overspending risk

On Request (Recommended)

Budget is reserved as soon as the booking request is created.

Stage	Budget State
Booking Started	Budget reserved (pending)
Approval Wait	Budget locked
Approved	Still pending
Payment	Pending → Spent

Pros: Prevents concurrent requests from overspending
Cons: Budget locked during approval wait
Best for: Strict budget control

On Approval

Budget is reserved only when the request is approved.

Stage	Budget State
Booking Started	No reservation
Approval Wait	Budget NOT locked
Approved	Budget reserved
Payment	Pending → Spent

Pros: Budget only locked when likely to proceed
Cons: Concurrent requests may not see accurate availability
Best for: Longer approval processes

On Confirmation

Budget is reserved and spent immediately upon payment.

Stage	Budget State
Booking Started	No reservation
Approval	No reservation
Payment	Budget reserved AND spent immediately

Pros: Maximum flexibility
Cons: Highest risk of overspending
Best for: Trust-based environments

Pending Reservations and Timeouts

Pending reservations don't last forever. The system has a timeout mechanism:

How Timeouts Work

When a reservation is created, it's timestamped
A background job runs periodically
Reservations older than the timeout (default: 72 hours) are released
Released amount returns to remaining budget

Configuring Timeout

In company settings:

Setting	Description	Default
Pending Reservation Timeout	Hours before releasing	72 hours

Timeout Example

Friday 10:00 AM: User starts booking, $500 reserved
Friday 10:00 AM: User abandons checkout
...
Monday 10:00 AM: Timeout job runs (72 hours elapsed)
Monday 10:00 AM: $500 released back to budget

The timeout prevents abandoned bookings from permanently blocking budget. Users who return after timeout will need to re-reserve.

Include Pending in Availability

The company settings control whether pending reservations count against availability:

Setting	Available Amount	Use Case
Include Pending: Yes	Total - Spent - Pending	Accurate real-time balance
Include Pending: No	Total - Spent	Optimistic balance, may overspend

With Include Pending = Yes (Default)

Total Allocated: $5,000
Spent: $3,000
Pending: $500

Available to book: $1,500 (includes pending)

With Include Pending = No

Total Allocated: $5,000
Spent: $3,000
Pending: $500

Available to book: $2,000 (ignores pending)

Setting "Include Pending: No" can lead to overspending if multiple users book concurrently. Only use this if you trust users to manage their own spending.

Refund Crediting

When refunds are processed, the system can credit them back to the budget:

Credit to Current Period

Refund goes to the current active period, even if the booking was in a previous period.

Booking: January (Period 1, now closed)
Refund: March (Period 3, active)

Refund credited to: Period 3

Pros: Increases current available budget Cons: Distorts period-over-period reporting

Credit to Original Period

Refund goes back to the period where the booking was made.

Booking: January (Period 1, now closed)
Refund: March (Period 3, active)

Refund credited to: Period 1

Pros: Accurate historical reporting Cons: Closed period can't be spent

Most companies use "Current Period" for practical reasons - refunds become available immediately.

Transaction History

Every budget maintains a complete transaction history:

Timestamp	Type	Amount	Reference	Balance After
Jan 15 10:00	BOOKING_PENDING	$500	ORD-001	$4,500 remaining
Jan 15 10:30	BOOKING_COMPLETED	$500	ORD-001	$4,500 remaining
Jan 20 14:00	BOOKING_PENDING	$1,200	ORD-002	$3,300 remaining
Jan 20 14:15	BOOKING_CANCELLED	$1,200	ORD-002	$4,500 remaining
Jan 25 09:00	BOOKING_PENDING	$800	ORD-003	$3,700 remaining
Jan 25 09:30	BOOKING_COMPLETED	$800	ORD-003	$3,700 remaining
Feb 10 16:00	REFUND	$300	ORD-001	$4,000 remaining

This provides a complete audit trail for finance and compliance.

Per User vs Shared Pool

The consumption lifecycle works differently based on allocation type:

Per User

Each user has their own UserBudgetPeriod with separate tracking
User A's pending reservations don't affect User B's availability
Transactions are recorded per user

Shared Pool

Single BudgetPeriod tracks the entire pool
User A's pending reservation reduces availability for all users
Transactions show which user made them but affect the shared pool

Handling Errors

If a transaction fails mid-process (e.g., database error), the system uses database transactions to ensure consistency:

Reservation fails: No pending amount recorded, user can retry
Confirmation fails: Pending remains, can retry confirmation
Release fails: Pending remains, timeout job will eventually clean up

All budget amount updates happen within database transactions to prevent partial updates that could corrupt budget state.

Company Settings - Configure timing and behavior
Transaction Types Reference - Complete reference
Monitoring - View transaction history

Consumption Lifecycle

On this page