Listings

Overview

Listings represent rental properties in your portfolio. Each listing is the central entity connecting:

Ownership periods - Who owns the property and when
Reservations - Guest bookings
Recurring fee subscriptions - Automated fee calculations
Transactions - Expenses and deposits

Key Concepts

Listing Status

Status	Description
`active`	Property is operational, accepting bookings, included in reports
`inactive`	Property is disabled, excluded from calculations and reports

Deactivation rules:

Cannot deactivate if transactions exist in closed period
Deactivation can be scheduled via ownership periods with setListingInactive

Upcoming Deactivation

Listings track scheduled deactivation status:

Status	Description
`active`	No deactivation scheduled
`disable-upcoming`	Will be deactivated when ownership period ends
`disabled-ending`	Currently inactive, was deactivated by ownership period
`disabled-forever`	Permanently inactive

Address

Properties can have full address information:

Street address
City, state/province
ZIP/postal code
Country

Currency

Each listing has a default currency for financial calculations. All reservations and transactions for this listing use this currency.

External References

Field	Description
`uniqueRef`	Your internal property ID for cross-referencing
`connectionId`	Link to booking channel or PMS connection
`source`	External system reference (type and ID)

Active Ownership

The activeOwnership field returns the current ownership period for the listing, including:

Period dates
Owner members with split percentages
Business model (managed, co-host, etc.)

Fee Subscriptions

The activeRecurringFeePeriods field lists all active recurring fee subscriptions:

Which fees apply
Subscription date ranges
Any rate overrides

Common Scenarios

Creating a Listing with Initial Ownership

POST /listings
{
  "name": "Beach House",
  "defaultCurrency": "USD",
  "status": "active",
  "uniqueRef": "BH-001",
  "address": {
    "street": "123 Ocean Drive",
    "city": "Miami Beach",
    "state": "FL",
    "zipCode": "33139",
    "country": "US"
  },
  "initialOwnership": {
    "startAt": "2024-01-01",
    "businessModel": "managed",
    "members": [
      {
        "contactId": "owner-123",
        "split": 100
      }
    ]
  }
}

Subscribing to a Recurring Fee

POST /listings/listing-123/fee-subscriptions
{
  "recurringFeeId": "fee-mgmt-456",
  "startAt": "2024-01-01",
  "endAt": null
}

Updating Listing Status

PUT /listings/listing-123
{
  "status": "inactive"
}

Deleting a Listing

Listings can be deleted or archived depending on their usage:

DELETE /listings/listing-123

Response:

{
  "status": "deleted"  // or "archived" if has historical data
}

API Endpoints

Method	Endpoint	Description
`GET`	`/listings`	List all listings with filters
`GET`	`/listings/{id}`	Get listing details
`POST`	`/listings`	Create a new listing
`PUT`	`/listings/{id}`	Update a listing
`DELETE`	`/listings/{id}`	Delete or archive a listing
`GET`	`/listings/{id}/ownership-periods`	List ownership periods
`POST`	`/listings/{id}/ownership-periods`	Create ownership period
`GET`	`/listings/{id}/fee-subscriptions`	List fee subscriptions
`POST`	`/listings/{id}/fee-subscriptions`	Subscribe to fee

Filtering Listings

GET /listings?status=active&connectionId=conn-123

Response Structure

{
  "id": "listing-123",
  "name": "Beach House",
  "uniqueRef": "BH-001",
  "status": "active",
  "defaultCurrency": "USD",
  "connectionId": "conn-456",
  "address": {
    "street": "123 Ocean Drive",
    "city": "Miami Beach",
    "state": "FL",
    "zipCode": "33139",
    "country": "US"
  },
  "source": {
    "type": "airbnb",
    "id": "airbnb-property-789"
  },
  "upcomingDeactivation": {
    "status": "active",
    "period": null
  },
  "activeOwnership": {
    "id": "period-abc",
    "startAt": "2024-01-01",
    "endAt": null,
    "businessModel": "managed",
    "members": [
      {
        "contactId": "owner-123",
        "split": 100
      }
    ],
    "issues": []
  },
  "activeRecurringFeePeriods": [
    {
      "id": "sub-def",
      "startAt": "2024-01-01",
      "endAt": null,
      "rate": null,
      "recurringFee": {
        "id": "fee-mgmt",
        "title": "Management Fee",
        "type": "managementFee",
        "rateType": "percentage"
      }
    }
  ]
}

Ownership Periods - Property ownership details
Reservations - Bookings for this property
Recurring Fees - Fee subscriptions
Transactions - Property expenses and deposits
Connections - External system links

Listings

On this page