Ownership Periods

Overview

Ownership periods define who owns a property and when. Properties can change hands over time, and each period captures the ownership details for accurate financial attribution on owner statements.

This is one of the most important concepts in VRPlatform because it determines:

• Who receives revenue from reservations
• How expenses are allocated
• Which owner statements are generated
• How recurring fees are applied

Key Concepts

What is an Ownership Period?

An ownership period represents a time range during which specific owners have a stake in a property. Each period includes:

• Start date: When ownership begins (inclusive)
• End date: When ownership ends (exclusive, can be null for ongoing ownership)
• Owner members: One or more owners with their percentage splits
• Business model: How the property is managed

Date Range Behavior

Ownership periods use inclusive start, exclusive end dates:

Period: January 1 - March 1

Includes: January 1, January 2, ... February 28/29
Excludes: March 1 and later

This allows seamless transitions between periods without gaps or overlaps.

Ownership Splits

When a property has multiple owners, each owner's percentage determines their share of revenue and expenses.

Rules:

• Percentages must total exactly 100%
• Each member must be a valid contact of type "owner"
• Minimum one member required

Business Models

The business model affects how revenue is recognized and which accounts are used:

Impact on accounting:

• Different business models use different accounts receivable accounts
• Affects how channel payouts are processed
• May change fee calculation behavior

Transitions Between Periods

When ownership changes:

1. End the current period: Set an end date on the existing period
2. Create a new period: Start date should match the previous end date
3. Reservations are attributed correctly: Revenue recognition respects period boundaries

Example: Property Sale

Period 1: 2024-01-01 to 2024-07-01 (Original owner)
Period 2: 2024-07-01 to null (New owner)

Reservation: Check-in June 28, Check-out July 3

With pro-rata revenue recognition:
- June 28-30 revenue → Original owner
- July 1-2 revenue → New owner

Pro-Rata Attribution

When using pro-rata revenue recognition, each night of a stay is attributed to the correct ownership period. This ensures accurate owner statements even when reservations span ownership changes.

Common Scenarios

Single Owner Property

{
  "startDate": "2024-01-01",
  "endDate": null,
  "businessModel": "managed",
  "members": [
    {
      "contactId": "owner-123",
      "percentage": 100
    }
  ]
}

Joint Ownership (50/50 Split)

{
  "startDate": "2024-01-01",
  "endDate": null,
  "businessModel": "managed",
  "members": [
    {
      "contactId": "owner-123",
      "percentage": 50
    },
    {
      "contactId": "owner-456",
      "percentage": 50
    }
  ]
}

Changing Ownership Mid-Year

Step 1: End the current period

PUT /ownership-periods/period-abc
{
  "endDate": "2024-07-01"
}

Step 2: Create new period

POST /listings/listing-123/ownership-periods
{
  "startDate": "2024-07-01",
  "endDate": null,
  "businessModel": "managed",
  "members": [
    {
      "contactId": "new-owner-789",
      "percentage": 100
    }
  ]
}

API Endpoints

Validation Rules

• Start date is required
• End date must be after start date (if provided)
• Member percentages must total 100%
• All member contact IDs must exist and be of type "owner"
• Cannot overlap with existing periods for the same listing
• Cannot modify periods that affect locked data

Related Topics

• Listings - Property management
• Contacts - Owner records
• Owner Statements - Financial reporting by period
• Revenue Recognition - Pro-rata attribution
• Locking - Modification restrictions