Reservations

Last Updated: 2026-09-05 Version: 1.0

Mental Model

A reservation connects booking identity and stay context to accounts receivable, revenue, fees, deposits, adjustments, and owner statements. The API constructs accounting output; the client renders it.

Resources and Lifecycle

Reservations contain listing, guest, stay dates, source identity, booking status, payment lines, adjustments, and calculated financial output.

adults and children preserve the PMS occupancy breakdown. guests remains the combined count used by existing integrations and fee formulas. Reservation detail, list, and CSV expose all three values. Owner-statement layouts can use reservation.adults or reservation.children as numeric Net Revenue fields; existing reservation.guests columns retain the combined count.

The reservation's listing is required accounting context. Background connection, mapping, recurring-fee, recognition, and tax changes refresh only reservations that retain that canonical listing link. They do not infer a listing from a provider connection. An explicit refresh of legacy data without the link fails so the reservation can be repaired instead of posted to an assumed listing.

Writes accept the booking statuses booked, cancelled, canceled, inquiry, and inactive; both cancellation spellings are equivalent on write. Reads always return booked, canceled, or inactive. Booking status and generalLedgerStatus=active|inactive are separate. The normal reservation update (PUT /reservations/{id}) changes booking status; the dedicated status update (PUT /reservations/{id}/status) activates or inactivates reservation journal entries.

Creation enforces both reservation identities used by storage. A connection cannot reuse a uniqueRef, and a non-inactive reservation cannot reuse the same connection, resolved listing, and confirmationCode, even when its uniqueRef differs. Either collision returns a user-correctable HTTP 400 and persists nothing. An inactive reservation has no calculated connection, listing, and confirmation identity, matching the storage constraint.

Any transaction line or journal entry that explicitly links a reservation must reference a reservation in the same team. A missing or different-team ID is rejected before accounting data is written and is never followed across team boundaries.

Read Model

Render returned financial lines, resolved accounts, posting dates, totals, paid state, locks, and issues. Do not recreate cancellation, deferred revenue, fee calculation, or journal generation in the client.

A recurring-fee refresh updates the journal and the reservation's materialized manager, owner, tax, and payment totals together. Reservation list and detail therefore reflect the same current fee postings, including deductions from negative formula-account balances such as channel commissions.

Reservation list and detail share one materialized issues snapshot. Detail reads compute issues from live data and write them back to the snapshot. List reads serve that stored snapshot: issuesComputedAt is the completion time of its latest durable evaluation (null before the first one), and issuesStale=true means a committed change has a newer revision. The returned issues are the previous snapshot, or an empty pending snapshot for a new reservation. Keep rendering the snapshot, show pending freshness where relevant, and re-read while it is stale. Do not merge it with client-side issue calculations.

Committed reservation and account mutations mark affected snapshots and wake a serialized regional evaluator. Required effects repeat invalidation after they commit. A minute recovery task seeds and reconciles bounded batches and keeps draining while durable work remains. An immediate list re-read can briefly still return the previous snapshot. Issue computation stays out of list reads, so they do not expand journal entries and accounts for each reservation.

Financial lines omit the generated A/R mirror leg of a reservation adjustment, including each daily leg of a pro-rata adjustment. The adjustment itself and genuine deposit or other A/R-account activity remain visible. Do not recreate the accounting mirror in the client. The mirror remains an active journal entry because it balances an adjustment posted independently from the reservation A/R date. This omission applies only to the reservation financial folio; general-ledger and report surfaces must apply their own documented accounting rules.

For a booked, accounting-active reservation whose posting date is before the accounting start, a refresh persists its base journal entries as inactive with inactiveReason=generalLedgerStartAt. Until that refresh, detail reads can still derive the mapped, non-excluded guest charge without journal entries. In either shape, reservation lines have status=inactive, and issues contains priorToStartDate with context.startDate after issue evaluation. Render that warning and the inactive line state instead of treating booking status=booked as proof that the reservation posts to accounting.

A reservation-level generalLedgerPostingAt supersedes its default recognition date when evaluating the PMS accounting window and generating base journals. Refreshing with an open date at or after the accounting start moves the base entries to that date, activates them, and recalculates journal-backed payment and financial totals. A manually generalLedgerStatus=inactive reservation remains a separate explicit exclusion and keeps its zero expected-payment behavior.

Use returned source and connection state to decide which synced fields the user can edit.

For reservation preflight, pass comma-separated reservation IDs through the ids filter. An inclusive ID request is a targeted lookup: every accessible matching reservation is returned even when normal browsing hides it because of booking, connection, source, or inactive-ownership accounting state. The pagination total reflects the targeted matches. Prefixing the filter with ! keeps normal browse rules and excludes the listed reservation IDs.

Date Filters

GET /reservations and GET /reservations/csv accept the same date and dateField filters. Use dateField=cancelledAt to match the reservation's cancellation timestamp. A single date matches that calendar date; a start...end value includes both boundary dates. Other supplied filters, such as status=canceled, still apply.

CSV Export

GET /reservations/csv derives its financial view from the authenticated token. For owner users, Total is the reservation's owner revenue, matching the owner portal reservation table. A missing owner total produces 0.00. For manager users, Total, Paid, and Unpaid retain the guest payment amounts. Owner exports omit Paid and Unpaid, and team settings can hide Total or canceled reservations. Every export includes separate Adults, Children, and combined Guests columns.

Payment Status

Use the returned payment.expected, payment.received, and payment.status on reservation detail, list, and owner-statement rows. These surfaces apply the same journal-backed payment rule.

A co-host payout leaves only the manager share collectible while its active accounts-receivable payments remain below the full guest charge. When its A/R leg and other active A/R payments meet or exceed the guest charge, expected remains the full charge and received remains the actual A/R amount. An exact payment is paid; an excess remains overpaid. This covers full and remaining-balance reclasses plus later channel adjustments. Do not infer either case from the presence of a co-host line alone. Archiving or restoring a deposit recalculates linked reservation payment status after its journal entries change status.

Imported payment and transaction lines with a reservation confirmation or customer reference are linked in the background. Newer lines that cannot be matched do not prevent older candidates from being considered.

The reservation-list paidStatus filter accepts unpaid, underpaid, overpaid, and paid. Prefix one of those values with ! to exclude it, such as paidStatus=!paid. Any other value is rejected as an invalid query; clients must omit an unset filter instead of sending strings such as undefined or null.

Decision Table

Adjustments and Posting Dates

An adjustment can specify a line type or account, amount, description, owners|manager party, optional recurring fee, and optional generalLedgerPostingAt.

Recurring-fee adjustments use their own balanced journal group. If the active fee references an archived posting account, create or update returns a user error before persistence; it does not inactivate the reservation's revenue, deferred-revenue, or A/R rows. Repoint or deactivate the fee before retrying. The final materialized journal also validates derived deferred-revenue postings. An inactive derived posting account taints the refresh and preserves the existing journal instead of writing a partial replacement.

An explicit mutation of an independently balanced adjustment can post or remove its postings while its parent reservation has generalLedgerStatus=inactive. The mutation refreshes only that targeted adjustment group; it does not reactivate the rest of the reservation journal. Books-closed, statement-period, and statement-attachment locks still apply.

When a recurring-fee adjustment changes a dependent fee, any historical fee group inside a published statement period stays unchanged, including a group that has no journal rows yet. The adjustment still posts its own balanced entries on its open posting date. An unlocked dependent fee is recalculated.

When creating an adjustment for an active booking, provide either type or recurringFeeId; selecting only accountId does not classify the line. Canceled bookings may preserve an unclassified adjustment because their financial treatment is derived from the cancellation state.

Owner adjustments participate in ownership and statement locks, while manager adjustments normally avoid owner-period locking. A separate open posting date is required when a new owner adjustment would otherwise reuse a locked reservation A/R date. Use returned date previews rather than assuming stay, cancellation, or A/R date.

For a reservation that spans the accounting start, an owner adjustment posted before that date remains inactive revenue but participates in the opening guest balance. It reduces or increases opening A/R and receives a matching opening-balance assignment. An adjustment posted on or after the start keeps its independent A/R mirror. This lets pre-start reversals remove imported charges without stacking replacement post-start revenue onto the guest total. Updating or deleting an adjustment that already contributes to that shared opening-balance group rebuilds the reservation journal together. The mutation is rejected if another row in the affected group is locked.

For adjustment creation, provide a concrete generalLedgerPostingAt when the posting date is a user decision. Without one, the route keeps the natural date when it is open and otherwise resolves and persists the earliest date allowed by books closing and statement-period locks. Pass onLocked=error to reject a locked natural date instead. onLocked=nextOpen remains available explicitly, does not bypass journal locking, and cannot be combined with an explicit posting date.

The dry-run response includes the resolved concrete adjustments[].generalLedgerPostingAt without saving the adjustment. The policy applies only when creating an adjustment; adjustment updates continue to require an explicit posting date when moving the line.

Line Mappings and Revenue

Payment-line mappings translate PMS or channel line types into accounts and can override recognition. Recognition can use check-in, check-out, booked-at, or pro-rata dates. Pro-rata can cross months and ownership periods.

After a PMS is connected, centrally managed defaults for that PMS bootstrap only missing team mapping rows. Existing mapped and explicitly excluded rows are never replaced. Mapping pages jump between the selected team's distinct indexed reservation line types and union explicit mappings. Work scales with the number of line types rather than the number of historical reservation lines, and an asynchronously reported catalog cannot hide an existing type.

For a pro-rata owner adjustment, each recognized daily amount and its matching accounts-receivable amount post on the same date. This includes uneven cent splits; callers do not need to force a separate posting date to keep the generated journal balanced.

When a reservation crosses the accounting start date but its reservation-level A/R remains excluded before that date, a line recognized after the start is bridged from opening equity. For a pro-rata line, only the post-start portion uses that bridge; earlier portions remain inactive, and Deferred Revenues clears when the post-start revenue is recognized.

For a reservation sourced from a child in a listing group, journal entries keep the child listing as their source and resolve ownership through the group parent. This includes deferred-revenue legs and rebalances. A missing-ownership issue is returned only when neither the stored period nor an effective parent period covers the posting date.

To deliberately exclude a line type from journal posting, create or update its mapping with accountId: null. Use a channel mapping with accountId: null to exclude only that booking channel. Mapping status=excluded and reservation line isExcluded=true are derived read-only results; omitting a line from a reservation payload is not the exclusion control.

A single-reservation journal refresh with an active unmapped line writes nothing and returns Map or exclude unmapped reservation lines in Reservation Accounts before refreshing journal entries. Its structured error context contains unmappedReservationLines[] with each line type and description so the caller can link directly to the required mapping action.

For POST /reservations/journal-entries, exactly one explicit ID completes before success and returns total: 1. Multiple IDs or an omitted selection queue a reservation-journal-refresh operation. Follow the returned operation until it is terminal; empty or repeated ID collections are invalid. If accounting locks prevent the queued refresh, the operation fails with failure.code=journalLocked. This also applies when the operation uses a UUID identifier. The journal remains protected; retrying does not reopen published history.

Bulk background refreshes run in bounded batches per team. Larger selections can remain queued while earlier batches finish; poll the operation for progress.

Reservation list and detail reads return journalStatus. Render recalculating while queued or running refresh work can still change the journal, failed for an unresolved terminal refresh failure, and stale when known journal changes have no active recovery. Only current proves that every known reservation journal change is applied. Use the embedded operations to poll work, then re-read the reservation after it becomes terminal.

Editability

Reservation changes can be blocked by books closing, statement periods, statement attachments, inactive ownership, or source ownership of synced fields. Use the most specific entity or adjustment lock.

An adjustment with an independent open posting date can remain editable while the reservation's owner-side A/R posting is locked. Updating or deleting an adjustment is blocked when its entries are statement-attached, in closed books, or in a statement-locked period. This includes inactive pre-start entries: their status excludes them from totals but does not make their posting history editable. Use adjustments[].lock to disable the mutation before submission.

A full or targeted fee, adjustment, or A/R journal refresh can return a structured journalEntries lock when the persisted journal and complete desired journal are balanced, but applying only the unlocked changes would split a balanced group. The refresh writes nothing in that case. Treat it as locked work; a genuinely unbalanced desired journal remains an internal accounting error.

Preview and Preflight

Create, update, batch, booking/accounting status, removal, and adjustment mutations expose dry run where the generated OpenAPI declares the dryRun parameter. Journal regeneration and line-mapping changes intentionally skip generic dry run because they require consequence-oriented results.

Recalculate financial previews when channel, line type, mapping, stay dates, recognition settings, party, fee, or posting date changes.

Mutation Recipe

1. Load the reservation, financial output, mappings, and returned locks.
2. Apply source-editability and deterministic status rules.
3. Recalculate affected account and posting-date previews.
4. Add an independent adjustment posting date when required.
5. Dry-run the complete reservation or adjustment payload.
6. Render structured lock and mapping issues.
7. Confirm and apply.
8. Re-read the reservation and render returned accounting output; continue polling issue state while issuesStale=true.

Failure and Recovery

A missing mapping means the user needs to configure the exact source line type. Locked owner history calls for showing the relevant period, statement, or first open date rather than silently changing the adjustment to manager. After a source sync or concurrent mutation, reload before retrying. An inactive fee posting account requires fee or account remediation; retrying the adjustment without changing that configuration cannot succeed.

Common Recipes

Cancel a paid reservation

Update booking status through the reservation mutation, then render returned issues and adjustments. Do not locally synthesize refund journals.

PUT /reservations/{reservationId}?dryRun=true
Content-Type: application/json

{
  "status": "canceled",
  "cancelledAt": "2026-07-19"
}

Post a late owner adjustment

Choose owners, create with onLocked=nextOpen&dryRun=true, inspect the returned posting date and financial lines, then repeat without dryRun to apply. Use an explicit generalLedgerPostingAt instead when the posting date is a user decision.

POST /reservations/{reservationId}/adjustments?onLocked=nextOpen&dryRun=true
Content-Type: application/json

{
  "type": "lateFee",
  "amount": 2500,
  "description": "Late owner charge",
  "party": "owners"
}

Release or forfeit a security deposit

Map the PMS reservation's refundable deposit line to Security Deposits Payable. When captured principal is refunded, create an adjustment that reverses that liability line. When it is forfeited, create equal-value adjustments that reverse the liability and reclassify it to the explicitly selected revenue account and owners or manager party.

Use an explicit open generalLedgerPostingAt, or dry-run and apply with onLocked=nextOpen. The adjustment posts its own balanced journal group, so it can correct a locked or GL-inactive reservation without reopening the booking or changing the closed period. Record the related cash refund or processor release as a Transaction against the asset that moved. See Security Deposit Accounting for channel-held settlement and chargeback boundaries.

Webhook Reconciliation

reservation.changed is emitted after a committed public aggregate change and after required journal or payment effects finish. No-ops, dry runs, rollbacks, and journal-only work that leaves the public response unchanged do not emit. The compact body contains no guest, stay, amount, payment, source, or line data; compare resourceVersion and fetch href.

API Reference

• Get reservation detail — GET /reservations/{id}
• List reservations — GET /reservations
• Update a reservation — PUT /reservations/{id}
• PUT /reservations/{id}/status — Update general ledger status
• POST /reservations/{reservationId}/adjustments — Contract
• PUT /reservations/{reservationId}/adjustments/{id} — Contract
• PUT /reservations/line-mappings/{type} — Contract

Related

• Revenue recognition