Recurring Fees

Overview

Recurring fees automate fee calculations on reservations. Instead of manually adding management fees to each booking, you create fee templates and subscribe listings to them. The system automatically calculates and applies fees based on your rules.

Common examples:

Management fees (percentage of revenue)
Cleaning fees (flat amount per booking)
Channel fees (OTA commissions)
Merchant fees (payment processing)

Key Concepts

Fee Types

Type	Description	Common Use
`managementFee`	Property management commission	15-25% of revenue
`cleaningFee`	Cleaning service charges	Flat fee per booking
`bookingChannelFee`	OTA commissions	3-15% depending on channel
`merchantFee`	Payment processing fees	2-3% of payment amount
`additionalFee`	Custom fees	Any other recurring charge

Rate Types

Fees can be calculated two ways:

Flat Rate Fixed amount per reservation, regardless of revenue.

Rate: 15000 (= $150.00)
Every reservation gets a $150 fee

Percentage Rate Percentage of specified revenue, using basis points (1/100th of a percent).

Rate: 20000 (= 20%)
$1,000 revenue × 20% = $200 fee

Formula System

Percentage fees can specify which revenue to calculate against using formulas:

Formula	Description
`acc.rent`	Only rental income
`acc.rent + acc.cleaning`	Rent plus cleaning fees
`acc.rent + acc.cleaning - acc.discount`	Rent + cleaning minus discounts

Account references: Use acc.{accountId} to reference specific accounts.

Subscriptions

Listings subscribe to fee templates with date ranges:

Listing: Beach House
├── Management Fee (Jan 1 - ongoing)
├── Cleaning Fee (Jan 1 - ongoing)
└── Channel Fee (Mar 1 - Jun 30) ← Temporary override

Subscription properties:

Start date: When the fee begins applying (inclusive)
End date: When the fee stops (exclusive, null = ongoing)

Multiple subscriptions: A listing can have multiple active subscriptions for the same fee type. Each generates independent fee entries.

Debit and Credit Accounts

Each fee specifies where the money flows:

Account	Purpose
`debitAccountId`	Where fee is charged FROM (usually owner's share)
`creditAccountId`	Where fee is credited TO (usually manager's income)

Example: 20% management fee on $1,000 rent

Debit:  Owner Distribution    -$200
Credit: Management Income     +$200

Tax Handling

Fees can optionally include tax:

Behavior	Description	Example ($100 fee, 10% tax)
`excluded`	Tax added on top	$100 + $10 = $110 total
`included`	Fee includes tax	$90.91 base + $9.09 tax = $100 total

Filters

Control which reservations a fee applies to:

Status filter:

booked - Only booked reservations
cancelled - Only canceled reservations
(none) - All reservations

Channel filter:

includeChannels - Only these channels
excludeChannels - All except these channels

Example: Channel fee that only applies to Airbnb bookings:

{
  "type": "bookingChannelFee",
  "includeChannels": ["airbnb"]
}

Pro-Rata Fee Distribution

When pro-rata revenue recognition is enabled:

Fee amounts are split across stay nights
Each night's fee is attributed to the correct ownership period
Useful when ownership changes during a guest's stay

Common Scenarios

Standard Management Fee (20%)

POST /recurring-fees
{
  "name": "Standard Management Fee",
  "type": "managementFee",
  "rateType": "percentage",
  "rate": 20000,
  "formula": "acc.rent + acc.cleaning",
  "debitAccountId": "account-owner-distributions",
  "creditAccountId": "account-management-income"
}

Flat Cleaning Fee

POST /recurring-fees
{
  "name": "Standard Cleaning",
  "type": "cleaningFee",
  "rateType": "flat",
  "rate": 15000,
  "debitAccountId": "account-cleaning-expense",
  "creditAccountId": "account-cleaning-income"
}

Channel-Specific Fee (Airbnb Only)

POST /recurring-fees
{
  "name": "Airbnb Host Fee",
  "type": "bookingChannelFee",
  "rateType": "percentage",
  "rate": 3000,
  "formula": "acc.rent",
  "includeChannels": ["airbnb"],
  "debitAccountId": "account-channel-fees",
  "creditAccountId": "account-channel-fee-income"
}

Subscribing a Listing

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

Ending a Subscription

PUT /listings/listing-123/fee-subscriptions/sub-789
{
  "endDate": "2024-07-01"
}

API Endpoints

Method	Endpoint	Description
`GET`	`/recurring-fees`	List fee templates
`GET`	`/recurring-fees/{id}`	Get fee details
`POST`	`/recurring-fees`	Create a fee template
`PUT`	`/recurring-fees/{id}`	Update a fee template
`DELETE`	`/recurring-fees/{id}`	Delete a fee template
`GET`	`/listings/{id}/fee-subscriptions`	List subscriptions for a listing
`POST`	`/listings/{id}/fee-subscriptions`	Subscribe listing to fee
`PUT`	`/listings/{id}/fee-subscriptions/{subId}`	Update subscription
`DELETE`	`/listings/{id}/fee-subscriptions/{subId}`	Remove subscription

Response Structure

Fee Template

{
  "id": "fee-123",
  "name": "Standard Management Fee",
  "type": "managementFee",
  "rateType": "percentage",
  "rate": 20000,
  "formula": "acc.rent + acc.cleaning",
  "debitAccountId": "account-owner-dist",
  "creditAccountId": "account-mgmt-income",
  "taxRate": null,
  "taxBehavior": null,
  "statusFilter": null,
  "includeChannels": null,
  "excludeChannels": null,
  "activeSubscriptionsCount": 15
}

Fee Calculation Order

When multiple fees apply, they're calculated in dependency order:

Fees without account references first
Fees referencing other fee accounts calculated after

This allows fees to be calculated on the result of other fees.

Locking Rules

Fee templates and subscriptions are subject to locking:

Condition	Blocked Operations
Reservations before books closed	Cannot modify fees affecting locked entries
Attached to owner statement	Cannot modify fee calculations

Listings - Properties with fee subscriptions
Reservations - Where fees are applied
Accounts - Fee debit/credit accounts
Owner Statements - Fee totals in statements
Revenue Recognition - Pro-rata fee distribution

Recurring Fees

On this page