Transaction Types Reference

This reference documents all budget transaction types and their impact on budget amounts.

Transaction Type Values

Type	Enum Value	Description
Booking Pending	`BOOKING_PENDING`	Budget reserved for in-progress booking
Booking Completed	`BOOKING_COMPLETED`	Booking confirmed, budget spent
Booking Cancelled	`BOOKING_CANCELLED`	Pending booking cancelled, budget released
Refund	`REFUND`	Confirmed booking refunded
Rollover In	`ROLLOVER_IN`	Amount received from previous period
Rollover Out	`ROLLOVER_OUT`	Amount transferred to next period

Creates a reservation for a booking in progress.

Amount changes: Pending increases by $500, remaining decreases by $500.

Confirms a pending reservation as spent.

Amount changes: Spent increases by $500, pending decreases by $500. Remaining stays the same.

Releases a pending reservation.

Aspect	Behavior
When created	User cancels booking, timeout, rejection
Amount impact	-pending, +remaining
Reference	Original booking reference
Visible to user	Indirectly (remaining restored)

Amount changes: Pending decreases by $500, remaining increases by $500 (budget restored).

Credits back a previously spent amount.

Aspect	Behavior
When created	Refund processed for completed booking
Amount impact	-spent, +remaining
Can be partial	Yes
Period target	Current or original (configurable)

Amount changes: Spent decreases by $300, remaining increases by $300.

Records budget amount received from the previous period during rollover.

Aspect	Behavior
When created	Period transition (rollover job)
Amount impact	Increases rollover amount in new period
Reference	Previous period ID
Visible to user	As "rollover" in period details

Records budget amount transferred to the next period during rollover.

Aspect	Behavior
When created	Period transition (rollover job)
Amount impact	Documents the outgoing rollover
Reference	Next period ID
Visible to user	In period history

Each transaction contains:

Field	Type	Description
`id`	string	Unique transaction ID
`budgetPeriodId`	string	Period this transaction belongs to
`userBudgetPeriodId`	string?	User period (for PER_USER)
`userId`	string	User who made the transaction
`transactionType`	enum	One of the types above
`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

Transactions can be filtered by:

Filter	Description
Budget Period	All transactions in a specific period
User	All transactions by a specific user
Transaction Type	Only specific types (e.g., BOOKING_COMPLETED)
Date Range	Transactions within a time range
Reference	Transactions for a specific order or request

The system prevents duplicate reservations for the same reference:

Before creating a BOOKING_PENDING, it checks for existing pending transactions with the same referenceType and referenceId
If found, a ConflictException is thrown: "Budget already reserved for [referenceType]:[referenceId]"
This prevents the same booking from consuming budget twice

The metadata field stores additional context. Common metadata fields:

originalTransactionId - For confirmations/cancellations, links to the pending transaction
originalAmount - For refunds, the original booking amount
conversionRate - If currency conversion was applied