Status & Lifecycle

Overview

Entities in VRPlatform have statuses that control their behavior, visibility, and available operations. Understanding status transitions helps you:

• Build reliable integrations
• Handle edge cases properly
• Understand why certain operations may be blocked

Entity Status Summary

Listings

Lifecycle:

active ⟷ inactive

Transition Rules:

• Cannot deactivate if transactions exist before books closed date
• Can schedule deactivation via ownership period setListingInactive

Deactivation Variants:

• disable-upcoming - Will deactivate when ownership ends
• disabled-ending - Inactive due to ownership ending
• disabled-forever - Permanently inactive

Reservations

Lifecycle:

booked ⟷ canceled
   ↓
inactive

Transition Rules:

• Cannot cancel/uncancel if reservation is in closed period
• Cannot cancel/uncancel if attached to owner statement
• Canceling marks revenue entries as inactive
• Uncanceling reactivates revenue entries

Canceled Behavior:

• Payment lines become inactive (not counted in revenue)
• Adjustments remain active (visible on guest folio)
• AR is cleared

Transactions

Lifecycle:

active ⟷ inactive

Transition Rules:

• Cannot change status if transaction date is before books closed
• Cannot change status if attached to owner statement

Archive/Unarchive:

POST /transactions/{id}/archive
POST /transactions/{id}/unarchive

Contacts

Lifecycle:

active ⟷ inactive

Transition Rules:

• No restrictions on status changes
• Inactive contacts can still appear in historical data

Accounts

Lifecycle:

active ⟷ inactive

Transition Rules:

• Cannot deactivate if account has entries in closed period
• Cannot deactivate if account has entries attached to statements
• Cannot deactivate if account is assigned to system function

Owner Statements

Lifecycle:

draft → inReview → published
           ↓
          void

Transition Rules:

• Can only move forward in the lifecycle (no "unpublishing")
• Once saved (inReview or later), underlying data is locked
• Void is for statements that shouldn't be used but need to be preserved

Status Priority: When multiple statements exist for the same period, priority determines which is authoritative:

1. published (highest)
2. inReview
3. void
4. draft (lowest)

Payment Status (Expenses)

Expense transactions track payment separately from status:

Calculation:

If payment = 0 → unpaid
If payment < total → underpaid
If payment = total → paid
If payment > total → overpaid

Recording Payment:

PUT /transactions/{id}
{
  "paidStatus": "paid",
  "paidAt": "2024-06-15",
  "paymentAccountId": "bank-account-123"
}

Connections

Error States: Connections can also have isErrorState: true when:

• Credentials expired
• API limits reached
• External service unavailable

Status Change API Patterns

Direct Update:

PUT /{entity}/{id}
{
  "status": "inactive"
}

Archive/Unarchive:

POST /{entity}/{id}/archive
POST /{entity}/{id}/unarchive

Cancel/Uncancel (Reservations):

POST /reservations/{id}/cancel
POST /reservations/{id}/uncancel

Error Handling

When status changes are blocked, the API returns:

• Error code indicating the reason
• Context about what's blocking the change

Common blocking reasons:

• locked_period - Data is in closed period
• attached_to_statement - Data is attached to owner statement
• has_locked_entries - Account has locked entries

Related Topics

• Locking - Understanding lock constraints
• Listings - Property lifecycle
• Reservations - Booking lifecycle
• Transactions - Transaction lifecycle
• Owner Statements - Statement lifecycle
• Data Integrity - Validation and issues