# Wikiup channel management: preview API workflow

Every property channel-setup action is available to a white-label client without
using Wikiup Console. This guide covers the currently enabled **preview** rollout.
Production distribution mutations remain blocked; production release flags do not
bypass certification or billing requirements. No production subscription is charged
by a preview enablement.

## Authentication and environment

Use `https://api-preview.wikiup.app` for this workflow. Authenticate server-side
with `Authorization: Bearer <owner-api-key>` or an owner account session. An API
key needs `read_write` access, a grant for the target property, and a current Owner
membership. `property.manage` is required. Read-only keys may read the workspace
but cannot POST, including review and callback completion. A property header cannot
override the ID in the request path. Never put API keys in a browser or OTA URL.

Start with an existing property or create one with the normal property API.
Channel management is enabled separately, so both new and existing properties
follow the same explicit pricing-consent step. Configure the property time zone,
room maximum guest counts and positive nightly prices. A one-listing rental plan
allows one bookable Wikiup room; separate hotel rooms use the hotel plan.

All property commands below use:

`POST /api/properties/{id}/channel-management`

Send JSON with `Content-Type: application/json`. All these commands return 200
on success. The sandbox reservation simulator has separate 202 submission semantics.
The API never asks customers for upstream API keys, provider property IDs or webhook
secrets. It provisions and stores those mappings internally.

## 1. Read pricing; obtain explicit consent

`GET /api/properties/{id}/channel-management`

The response contains `workspace`, `catalog`, `catalogError`, and `plans`:

```json
{
  "plans": {
    "hotel": {
      "version": "channel-management-hotel-2026-11-08-v2",
      "monthlyPriceUsd": 15,
      "currency": "USD",
      "interval": "month",
      "scope": "property",
      "includedRoomTypes": null,
      "includedRooms": 5,
      "additionalRoomMonthlyPriceUsd": 1
    },
    "rental": {
      "version": "channel-management-rental-2026-10-28-v1",
      "monthlyPriceUsd": 10,
      "currency": "USD",
      "interval": "month",
      "scope": "property",
      "includedRoomTypes": null
    }
  }
}
```

This is a partial response example. Display the selected plan's price and scope,
and require the owner's acceptance. Use the version returned by the current GET,
not a version hardcoded from this example:

```json
{"action":"enable","plan":"hotel","termsVersion":"<plans.hotel.version>","accepted":true}
```

The response is the updated workspace, including `enabled:true`. Enable provisions
the distribution property and its reservation webhook. It does not connect a
channel or import bookings. Read GET again to obtain the current catalog. Disabled
properties intentionally return an empty catalog. `catalogError` means retry catalog
loading; persisted workspace data remains usable.

## 2. Connect the chosen channel

Use the exact `code`, `authorization`, `fields` and `status` returned by the catalog.
`verification_required` channels cannot be connected. Production catalogs expose
only approved channels. Unknown channels can be requested using
`{"action":"request_channel","name":"Channel name","notes":"Optional context"}`.

### OAuth and preview sample-account consent

```json
{"action":"connect","code":"AirBNB","redirectUrl":"https://partner.example/channel-callback?flow=setup"}
```

`redirectUrl` is optional; omission uses Wikiup's hosted callback. Your custom URL
must use HTTPS, contain no credentials or fragment, and not predefine `success`,
`token` or `channel_id` query parameters. Preview also accepts HTTP loopback
callbacks, such as `http://localhost:4000/channel-callback`. URLs are browser
destinations; the server does not fetch them. Configure a URL controlled by your
application, never an arbitrary destination supplied by an untrusted user.

An OAuth result looks like:

```json
{
  "status":"authorization_required",
  "url":"<authorization-url>",
  "sessionId":"<session-id>",
  "token":"<sensitive-owner-bound-token>",
  "expiresAt":"<ISO-timestamp>",
  "redirectUrl":"https://partner.example/channel-callback?flow=setup",
  "simulated":true,
  "channelId":"<sample-channel-id>"
}
```

`simulated` and `channelId` are provided by the preview sample adapter. Retain the
returned session details server-side and do not log the URL/token. For a browser
flow, open `url`. On success, your callback receives `success=true`, `token` and
`channel_id` query parameters. Check them against your initiating session, remove
them from browser history, then have your backend complete the session:

```json
{"action":"complete","token":"<exact-returned-token>","channelId":"<echoed-channel_id>"}
```

Alternatively use `POST /api/channel-management/authorization` with just
`{"token":"<exact-token>","channelId":"<echoed-channel-id>"}`. This alternative
returns both `propertyId` and the Wikiup `connectionId`.

In preview, your own UI may collect **sample-account** consent and send `complete`
directly with the returned token and sample channelId. No Wikiup browser session is
needed. This is a simulated authorization, never permission to bypass a real OTA's
OAuth. Live OAuth still requires the channel's consent screen and callback.

Tokens expire after 30 minutes. The same owner must initiate and complete the
session, with access to the same property. Identical successful completion retries
return the saved connection. A foreign, revoked or expired token is rejected.

If the user abandons authorization, revoke its pending session with
`{"action":"cancel_authorization","token":"<exact-token>"}`. Repeating this
command returns `{"ok":true}`. It invalidates callback completion but does not
claim to revoke an OTA-side grant. A completed session requires `remove` with the
saved connectionId instead; canceling it returns 409.

### Settings channels and Vrbo preview

For ordinary settings channels, send `settings` using the returned descriptor.
A response of `settings_required` supplies the fields to collect; submit `connect`
again with those settings. Success returns
`{"status":"mapping_required","connectionId":"<wikiup-connection-id>"}`.

Vrbo preview exercises preparation → sample credentials → sign-in code → test:

```json
{
  "action":"connect",
  "code":"Vrbo",
  "settings":{
    "previousManagerDisconnected":true,
    "calendarImportsRemoved":true,
    "username":"host@example.test",
    "password":"wikiup-vrbo-preview",
    "verificationCode":"123456"
  }
}
```

Use the exact catalog code; the HomeAway alias follows the same flow. Show separate
preparation, authentication and verification steps in your UI. These are public
test fixtures. No SMS is sent; real credentials are rejected in preview. Incorrect
codes return 422 and can be corrected by resubmitting. Passwords and verification
codes are not persisted. Real Vrbo is production-only, and this preview is a Wikiup sample simulation. The real adapter rejects Vrbo/HomeAway connection attempts before provider requests; generic Test Connection is not authentication. Hosted authorization is planned pending the private production connection contract. Live Vrbo authentication has not been enabled or certified.

## 3. List, optionally import, then map each listing and rate

```json
{"action":"listings","connectionId":"<wikiup-connection-id>"}
```

The result is `{ "listings": [...], "mappingFields": [...] }`. Each listing has
`externalListingId`, `name`, `rates`, and `mappedRoomId` when already mapped. A
connection may contain dozens of listings. Show all of them in your UI; do not
assume one listing per account.

To import content into a new Draft room before mapping:

```json
{"action":"preview_import","connectionId":"<wikiup-connection-id>","externalListingId":"<listing-id>"}
```

Review the returned `listing` and use its returned `id` as `importId`:

```json
{"action":"import","importId":"<returned-id>","name":"Garden Suite","description":"Reviewed room description.","capacity":4,"nightlyRate":120,"reviewed":true}
```

`name` (1–255 characters) and `description` (up to 10,000 characters) are optional
reviewed overrides for the new room. Omit them to keep the channel content.
A resumed `preview_import` includes `room` with the existing room ID, reviewed
name/description, capacity and nightly rate when a prior import created the room.
Import retries preserve those saved details. A listing mapped to a different
Wikiup room is rejected rather than duplicated.

In the console, a newly connected channel opens a choice to import its listings
or map existing Wikiup rooms. Import is selected when the property has no rooms;
otherwise mapping is selected. Hotel owners may select multiple unmapped listings;
a rental imports one listing. Review each room's details, guest capacity, nightly
rate and any required channel rate. Import each room until ready, then map it
before offering activation. The import command itself does not activate sales.

Repeat the same import until `status:"ready"`; photos copy in resumable batches.
The result includes `roomId`, `photosCopied`, `totalPhotos`, and `status`. A whole
home creates one room, not one room per bedroom. Hotel plans allow multiple
room imports, up to 500 room types; each becomes a separate Draft room. Import
reviews must supply maximum guest capacity and a positive nightly rate. Common
hotel channels expose room names through mapping details; descriptions and photos
are imported only when the source provides them. Unknown values are not invented.
Importing content does not map or
activate it, import reservations, change it to Active, or create a payment/email.
Review and update its normal room configuration through the room API as needed.

Map once per listing, using either an existing Wikiup room or that imported room:

```json
{
  "action":"map",
  "connectionId":"<wikiup-connection-id>",
  "externalListingId":"<listing-id>",
  "roomId":"<wikiup-room-id>",
  "settings":{"rate_plan_code":"standard"}
}
```

`rate_plan_code:"standard"` is the Vrbo preview example, not a universal rate ID.
Use `mappingFields` and the selected listing's `rates` for other channels. Airbnb
preview needs no extra mapping settings. Submit mappings sequentially, retain
successful results, and retry only failed mappings. Read `listings` to resume.
Booking.com preview exposes `room_type_code` (the selected externalListingId) and
`rate_plan_code` (a rate from that listing). The console preselects a sole rate;
when multiple rates exist, the owner chooses one explicitly.
Existing mappings cannot silently move an external listing onto a different room.
Pause an active connection before changing mappings. Maximum guests and a positive
nightly price are required; Draft/Inactive rooms remain closed when inventory is sent.

## 4. Activate with sales closed

```json
{"action":"activate","connectionId":"<wikiup-connection-id>","reviewed":true,"testListingAcknowledged":true}
```

This checks mapping/readiness, prevents booking during setup, activates the
connection and requests the source's available reservations. It returns
`{"ok":true}`. That is not confirmation that reservation delivery is complete.
The source may not provide all past/future reservations or all personal/fee details.
Preview sample accounts start without historical bookings.

New activation clears a property's previous availability approval. The following
sync does not automatically open the new setup. Nothing is charged in preview.

## 5. Synchronize, read the review, obtain approval

```json
{"action":"sync","reservationsOnly":true}
```

Result: `{"applied":0,"blocked":0,"complete":true}`.
`reservationsOnly:true` skips the full restriction/listing-settings stage but still invokes automatic availability checks/delivery. It is not a provider-read-only flag. For isolated Booking CRS ingestion without publication, use sandbox-reservations action=verify. Omit the flag for the broader operational sync.
These counts describe this check, not all-time reservation totals. An incomplete check or blocked update
requires correction before approval. Poll the workspace for persisted issues,
activity and timestamps; mutation responses are synchronous, not streaming jobs.

```json
{"action":"review"}
```

The review is **property-wide**, covering every active connection and mapped room:

```json
{
  "propertyId":"<property-id>",
  "scope":"property",
  "status":"approval_required",
  "canApprove":true,
  "blockers":[],
  "reservations":{
    "feedComplete":true,
    "lastCheckedAt":"<ISO-timestamp>",
    "appliedUpdates":0,
    "pendingUpdates":0,
    "importedReservations":0,
    "historyCoverage":[]
  },
  "availability":{"approvedAt":null,"lastSentAt":null,"roomsRemainingClosed":0,"status":"not_sent","retryAt":null},
  "nextActions":["approve","pause","remove"]
}
```

This is a partial example; the response also includes accepted `terms`,
`connections`, mapped `rooms` with prices and statuses, and `issues`.
`appliedUpdates` and `importedReservations` in review are cumulative counts of
persisted revisions and unique local reservations. `historyCoverage` is source
coverage recorded by content imports, not proof of complete reservation history.
`roomsRemainingClosed` counts mapped non-Active rooms, not occupied nights.
`availability.status` is `not_sent`, `pending`, `failed` or `accepted`. A failed
send is retried with `approve`, not `sync` or `review`. When `retryAt` is set,
disable retry until that timestamp and show a countdown; the server also enforces it.

`review` does not contact channels or run sync. `canApprove` is an advisory snapshot;
checks can become stale. Stable blocker codes include `not_enabled`,
`terms_not_accepted`, `no_active_channel`, `no_mapped_rooms`,
`test_connection_not_acknowledged`, `reservation_issues`,
`reservation_check_required`, `invalid_room_price`, and `time_zone_required`.
Checks older than two minutes require a new sync. Use blocker messages in your UI.

Present the summary and require the owner's approval:

```json
{"action":"approve","reviewed":true}
```

Approval rechecks reservations under the property mutation lock, then sends
absolute availability and nightly rates for all mapped rooms to the property's
active connections. Occupied nights and non-Active rooms remain closed. Result:
`{"status":"accepted","days":365}`. `days` is the rolling snapshot horizon,
not an instruction to close all rooms for that duration. Provider acceptance is
not proof of OTA delivery. `publish` remains a compatibility alias for approve.

If the owner does not approve: leave setup closed and return later; run `sync` and
`review` again; `pause` the connection before correcting mappings; inspect and
correct reservations through the reservation API; or `remove` the connection.
There is no endpoint to bypass a conflict by acknowledging an unsaved reservation.

## 6. Operate and test

`pause` and `remove` each take `connectionId`. Pause retains mappings. Airbnb
Pause closes only this property's availability; confirmed `resume` removes its
owned close-out. Remove detaches this property's Airbnb mappings and membership
when authorization is shared; it does not deactivate or delete the shared account.
An exclusive connection can be deactivated/removed. Local mappings and pending
authorizations are retired; existing Wikiup reservations remain. Retry failed removal
with the same connection ID. Reconnect using `connect`, then reauthorize/map/review.
Do not create another property just to reconnect a channel.

`GET /api/properties/{id}/channel-management` reports connection status, mapped
rooms, imports, activity, issues, and reservation/availability timestamps. Activation
can report `activation_pending` after an uncertain response; retry activate for the
same connection. A failed inventory send appears in workspace issues and is retried
through approval; it is not a successful delivery.

After a simulated connection is mapped and active, use
`POST /api/properties/{id}/channel-management/sandbox-reservations` with
`connectionId` to test only its mapped rooms. `create`, `modify`, and `cancel` take
client UUID `requestId` values and return 202 submitted. Reuse an ID with the
identical request when retrying; changed input returns 409. Poll
`GET /api/properties/{id}/channel-management/sandbox-reservations?connectionId=<id>`
until `delivery:"applied"` or use its `verify` command. This proves Wikiup's
staging booking import path, not real OTA authorization/delivery. See the main
API reference for simulator fields.

## Errors, retries and credential handling

| HTTP | Meaning and recovery |
|---|---|
| 401 | Missing/invalid bearer credential. |
| 403 | Missing ownership, read/write or property grant; wrong/expired authorization; production rollout guard. |
| 404 | Unknown channel, room, listing or connection in this property. |
| 409 | Stale pricing, concurrent property change, unresolved reservations, unready activation, or uncertain external create requiring reconciliation. Read workspace and correct the stated condition before retrying. |
| 422 | Invalid command/redirect, price/capacity/plan limits, rejected settings or sample sign-in code. Correct input. |
| 429 | Channel update limit reached. Honor the Retry-After header and retryAfterSeconds response field; review returns availability.retryAt. Do not repeatedly send updates during this cooldown. |
| 503 | Channel adapter configuration is unavailable. |

Channel errors normally use `{"error":"message","code":"optional-code"}`.
Do not blindly retry an uncertain external create. Enable and completed
authorization reuse saved state; mappings and imports retain completed work.
Connect is not a general-purpose idempotency-key API. Save the returned session
or connection before proceeding and reload the workspace after a lost response.

Authorization and workspace responses use `Cache-Control: no-store`; authorization
also uses `Referrer-Policy: no-referrer`. Keep tokens and credential fields out of
logs, analytics and durable client state. Wikiup manages the upstream reservation
webhook internally. Webhooks and the configured backup polling workflow use the
same durable inbox; deploying/configuring that workflow is an operator concern,
not an action a hotel owner must run from their integration.

## Import a new property from a channel

Use this flow instead of `POST /api/properties`. It works with an owner session
or an unrestricted owner read/write API key. Property-restricted keys cannot
create an import. The rollout remains preview-only.

1. Read `GET /api/channel-management/property-import` for `catalog`, `plans` and pending owner-bound `imports`.
   Obtain explicit acceptance of the selected plan and its exact terms version.
2. POST to the same endpoint:
   ```json
   {"action":"start","requestId":"<client UUID>","plan":"hotel","code":"BookingCom","accepted":true,"termsVersion":"channel-management-hotel-2026-11-08-v2","timeZone":"America/Los_Angeles"}
   ```
   Save `sessionId` and `propertyId`; reuse the same requestId on a lost response.
   An internal provisional property supports channel authorization. It remains
   hidden from the property list until the import finishes.
3. Use the returned propertyId with the normal `connect` command. Set your
   `redirectUrl`, complete authorization, then call `listings`. These steps use
   the same channel-specific authentication as adding a channel to an existing
   property, including Vrbo account preparation and sign-in verification.
4. Select up to 500 hotel rooms or one vacation-rental listing. Call
   `preview_import` for each selected externalListingId. Keep each import `id`.
   Source descriptions, photos and address fields can be absent; never invent
   them. Show returned source values for review and allow manual corrections.
5. POST `save_details` to `/api/channel-management/property-import`:
   ```json
   {
     "action":"save_details","sessionId":"<session-id>",
     "details":{
       "name":"Coastal Inn","description":"A coastal inn.",
       "email":"host@example.com","phone":"8585550100","websiteUrl":"",
       "timeZone":"America/Los_Angeles",
       "address":{"line1":"123 Coast Road","line2":"","city":"Encinitas","state":"CA","postalCode":"92024","country":"US"}
     },
     "rooms":[{"externalListingId":"<channel-room-id>","importId":"<preview-import-id>","name":"Garden Suite","description":"Reviewed room description.","capacity":4,"nightlyRate":150,"rateId":"<channel-rate-id>"}]
   }
   ```
   Email, phone, name, time zone, street/city/state/postal/country are required.
   Country is a two-letter code; nightlyRate is USD. Supply a rate from that
   listing's returned rates (required for Booking.com and Vrbo). Saving starts
   the import; reviewed details are immutable during retries.
6. For each reviewed room POST
   `{"action":"import_room","sessionId":"...","connectionId":"...","room":{...}}`.
   Use exactly the reviewed room object. Repeat while `status:"copying_photos"`;
   receipts resume photos and reuse rooms. `status:"ready"` means that
   the local listing details and photos are imported. It does not mean a channel
   mapping exists. Imported rooms remain Draft; no mapping or activation occurs.
7. POST `{"action":"finish","sessionId":"...","connectionId":"..."}`.
   Wikiup verifies that all reviewed local listings finished importing, exposes
   the imported property and returns `{propertyId,membership}`. Retry safely after
   a lost response. This step does not map, activate, request historical bookings,
   send closures or publish prices/availability. Mapping, reservation migration
   and publication require separate reviewed workflows; imported listing content
   is not evidence of complete calendar or booking coverage.

Staging can connect real Airbnb accounts. Preview is not blocked by an operator
property allowlist. Wikiup Draft/Active visibility does not determine Airbnb
availability. Import does not map, activate or publish automatically.

For a real Airbnb connection, `review` reads the current remote calendar and
returns `publicationReviewId`, `publicationExpiresAt`, `proposedInventory`, and
`proposedChanges`. Changes list each date's current/proposed availability and
nightly price, with room, destination and currency. Reservations, imported calendar
blocks, and booking-window restrictions remain preserved. Booked/host-blocked
nightly prices remain unchanged. A price-only update omits stop-sell and stay
restriction fields. An unavailable or incomplete source calendar is a read error,
not a Draft or staging restriction.

POST `{"action":"approve","reviewed":true,"reviewId":"..."}` (or `publish`)
to approve that exact proposal. Under the property/inventory writer claims the
server re-reads inputs and rejects expired, consumed, cross-property or changed
proposals before sending anything. Reviews expire after 15 minutes. A zero-change
proposal finishes setup without external writes. A non-empty proposal sends only
its exact delta, with no blanket closing pass. A prior approval does not authorize
new background changes to real accounts; those await a fresh owner review.
Errors/holds on real connections stop further sending rather than closing sales.
Provider task acceptance remains distinct from booking-channel confirmation.

Exact live-calendar comparison currently supports Airbnb, one unambiguous active
calendar source per mapped room. Other real channel types need a corresponding
calendar reader before this reviewed publication path can calculate a proposal.
Simulation fixtures retain their separate certification delivery path.

`GET /api/channel-management/property-import?sessionId=...` returns the current
status (`draft`, `importing`, `completed`, `canceling`, `canceled`), reviewed details/rooms,
source import receipts and connections. Only the session owner can resume it.
Keep the session ID to resume after authorization or an interrupted import.

`{"action":"cancel","sessionId":"..."}` disconnects provisional channels,
revokes outstanding authorization sessions and discards an unfinished import.
Its retained audit records remain hidden; a completed import cannot be discarded
through this command. Start a new requestId after cancellation. Closing the
console wizard preserves the pending import; Back from the channel step offers
an explicit discard confirmation.

## Durable inventory delivery

The preview implementation captures reservation/block, room availability and pricing writes at the shared persistence boundary. After the initial owner-reviewed approval, the configured background dispatcher coalesces those events and sends current absolute changes; clients do not need to press `sync` after each save. The scheduled runtime requires preview secret configuration and deployment before this becomes automatic. Production activation remains blocked.

A queued change is not confirmation that a booking partner has received it. `workspace.lastAvailabilityUpdate` and review `availability.status: "accepted"` indicate provider acceptance. Failed outboxes remain visible in workspace issues, with retry times in the activation review. Temporary provider limits retain the work and manual publish returns HTTP 429 with `Retry-After`; do not repeatedly invoke publish during that cooldown. Permanent/ambiguous failures may require operator review.

A business write can return `MUTATION_IN_PROGRESS` (409) while inventory is fenced by another writer/delivery. Retry after that operation finishes. `CHANNEL_CHANGE_UNCERTAIN` (503, `domainWriteCompleted: true`) means the business change was saved but queue finalization needs reconciliation: reload the record and do not repeat an unknown create blindly. Recovery recomputes authoritative inventory rather than replaying an uncertain reservation creation.

The signed `/api/internal/channel-inventory/deliver` job is service-only. Property API keys and user sessions cannot trigger account-wide dispatch. Clients continue using the property-scoped commands documented above.

### Imported reservation source and actions

Reservation list/detail responses include derived `bookingSource` metadata for
channel-imported reservations: canonical `code`, display `name`,
`reservationCode`, `canCancel`, and `canChangeStay`. The source comes from the
property-scoped booking receipt; it is not inferred from editable notes or client
payloads and needs no Reservation schema change. Existing imports are enriched on
read. Local status/notes and check-in/out are separate from provider-owned booking
terms.

Current imported-provider capabilities do not include initiating cancellations or
stay/room changes. Those operations return JSON 409 with
`RESERVATION_MANAGED_BY_PROVIDER` and the originating provider's name. This applies
to cancellation quotes/confirmation, the legacy DELETE path, generic PUT booking
changes, and stay/room modification endpoints. Native Wikiup bookings keep their
existing capabilities. Provider revision ingestion remains separate and continues
to apply externally canceled or modified bookings to Wikiup.

#### Read back a published Airbnb update

`POST /api/properties/{id}/channel-management`

```json
{"action":"verify_publication","reviewId":"<published-review-id>"}
```

Uses the existing property-owner authorization. The review must belong to that
property and have status `published`. Reads the affected listing dates through
Channex without sending rates or availability. Returns `status` (`verified`,
`not_verified`, or `unavailable`), `checkedAt`, and `reviewId`; a completed
comparison also includes `mismatches`. Workspace connections expose the saved
`verification` and `publicationReviewId` for reload/retry. Verification describes
observed calendar values at the check time, not a task-delivery acknowledgment.

#### Enable automatic availability sync

`POST /api/properties/{id}/channel-management`

```json
{"action":"enable_availability_sync","reviewId":"<verified-published-review-id>"}
```

Owner-only, property-scoped. Requires a verified published setup with unchanged active
Airbnb mappings. Enables occupancy-only reconciliation, refreshes inbound bookings,
and attempts pending availability updates. Returns reconciliation status; an accepted
send remains `pending` until Airbnb calendar readback matches. Does not publish prices,
create OTA bookings, send guest details, or reopen external blocks. Workspace connection
`availabilitySync` includes `enabled`, `pending`, `lastVerifiedAt`, and attention `message`.


## Staging data and rule/publication command updates

Use [the staging test-data workflow](https://api.wikiup.app/staging-test-data.md) for standalone Booking CRS. Commands are prepare, create, modify, cancel and verify. No simulated OTA connection is required. Main channel commands also include minimum_stay, booking_rules_review, verify_publication and enable_availability_sync. Read the interactive reference for each request/response and side effects; verify_publication may reconcile restrictions, while sandbox verify is ingestion-only.

Preview may contain real OTA connections; simulated sample-account behavior must not be generalized to every preview connection.

## Room/channel price adjustments

`priceAdjustment` belongs to the saved **room/channel mapping**, not room base pricing. Onyx persists it in `ChannelManagementRecord` with `kind: "channel-mapping"`, alongside `connectionId`, `roomId` and `externalListingId`. No new table or schema publication is required.

An adjustment is either `null` (explicit no increase) or `{type:"percentage"|"fixed",value:number}`. Percentage values are 0–1000; fixed values are 0–100000 major listing-currency units **per night**. Both allow at most two decimal places. Zero is equivalent to no increase. Negative adjustments and compounded/multiple custom rules are outside this API's supported contract.

For example, a source nightly price of USD 200 with `{type:"percentage",value:20}` produces USD 240 on that mapping. `{type:"fixed",value:30}` produces USD 230. Direct-booking prices are unchanged. Channex applies its native mapping-level modifier; Wikiup must continue sending the unadjusted source amount, never apply the increase a second time.

### During setup

Include the optional field in the ordinary map command:

```json
{"action":"map","connectionId":"<connection-id>","roomId":"<room-id>","externalListingId":"<listing-id>","settings":{},"priceAdjustment":{"type":"percentage","value":20}}
```

Omitting the field leaves upstream adjustment behavior unchanged. Explicit `null` overrides an inherited connection-level price increase with no mapping rate adjustment. Descriptor-defined settings are still required where applicable. Existing mapping changes retain their pause/review requirements; use the dedicated command below to change only pricing on an existing mapping.

### Change an existing mapping

Send `POST /api/properties/{id}/channel-management` with an owner session or owner read/write API key scoped to the property:

```json
{"action":"price_adjustment","connectionId":"<connection-id>","roomId":"<room-id>","externalListingId":"<listing-id>","priceAdjustment":{"type":"fixed","value":30}}
```

The server finds exactly the saved mapping, journals intent before network I/O, and updates that native mapping's rate modifier. It preserves its other settings and derived booking restrictions. It does not disconnect, remap, publish room base prices, or alter another mapping.

`{status:"configured",priceAdjustment:...,delivery:"pending"}` means the native configuration was read back, **not** that all OTA prices are verified. The console exposes these controls in the room mapping **Rate Plan** column, with a representative base-price preview and separate Save adjustment / Verify prices actions.

### Verify

```json
{"action":"verify_price_adjustment","connectionId":"<connection-id>","roomId":"<room-id>","externalListingId":"<listing-id>"}
```

This reads the native modifier and, where supported, compares the actual channel calendar against actual provider source prices plus the adjustment. It does not assume Wikiup currently owns base-price publication. Results distinguish `configured` with unverified delivery, `not_verified`, and `verified`. Missing/custom/unrepresentable settings fail closed rather than being treated as zero. Unknown configuration outcomes are not blindly resent or replaced; verification can settle a lost successful response locally.

This field controls the mapping's markup, not automatic source-price ownership. Automatic-price authorization is separately reviewed and scoped to connectionId. `enable_rate_sync` opts in only that channel; `disable_rate_sync` stops future sends for it. An independent opt-in is rejected when another active channel shares the same room source rate, rather than letting an opted-out channel receive updates. Separate per-channel source-rate provisioning is not part of this adjustment feature.


### Per-listing booking-rule overrides

Use `action: "booking_rule_overrides"` on `POST /api/properties/{id}/channel-management` with owner/property.manage access:

```json
{"action":"booking_rule_overrides","connectionId":"airbnb-connection","roomId":"room-id","externalListingId":"airbnb-listing-id","overrides":{"minimumStay":3,"advanceNoticeHours":48}}
```

`overrides` replaces the saved policy for this exact listing/channel mapping. Omitted keys inherit future room changes; `{}` returns all supported rules to room defaults. Minimum stay remains at least the room floor. Maximum stay must not be below effective minimum. The remaining supported keys are `maximumStay`, `preparationDays`, and `bookingWindowDays`. Numeric values/ranges are documented in the command reference. Same-day cutoff remains room-controlled because the provider cutoff is property-wide; unknown fields are rejected.

The Booking rules tab exposes **Synced / Override** per supported rule, its current channel value, and effective rule. Saving an explicit policy authorizes replacing the preserved base restrictions with the chosen room/default or override values. Until that explicit save, existing setup preservation remains intact. Stricter preexisting date-specific minimum-stay exceptions are retained. Active connections queue scoped publication and require readback; inactive ones return `queued`. `pending` is not proof of delivery, and unresolved previous writes block a different policy. Unsupported channel types and shared-source independent stay overrides fail closed. No Onyx schema addition is required: the policy lives in the existing `ChannelManagementRecord` mapping payload as `bookingRuleOverrides` and `bookingRulesManaged`.

`booking_rules_review` returns `ruleSettings` with `room`, `overrides`, `editable`, `stayOverridesSupported`, and `status`. Refresh is read-only. Direct bookings continue to use room rules, never channel overrides.


### Automatic pricing per listing mapping

The mapping's Pricing tab contains **Automatically sync prices to {channel}**; saved single-rate mappings no longer show the redundant rate-plan display. `enable_rate_sync` and `disable_rate_sync` accept `roomId` + `externalListingId` together with `connectionId`. The pair selects exactly one saved mapping. Enabling still requires an owner-reviewed, published and verified baseline and sends no prices itself. Both delta selection and the final pre-send authorization check enforce the mapping scope. Turning off one mapping leaves sibling listings enabled, and does not change occupancy synchronization or pricing adjustments.

The listings response includes `automaticPriceSync` for each mapped listing. Existing connection-wide opt-ins remain effective until an explicit change materializes their enabled mapping keys; deployment alone never opts anyone in or out. Legacy commands omitting both listing/room identifiers retain whole-channel behavior. `mappingKeys` is stored in the existing managed-inventory record; no schema publication is needed. Independent price consent on a shared source rate remains blocked to avoid affecting an opted-out listing.


### One save for the mapping dialog

Mapping, automatic price-sync, price adjustment, and booking-rule edits are drafts until the owner clicks **Save changes**. The console submits one `PUT /api/properties/{id}/channel-management/mappings` containing a UUID `requestId`, `connectionId`, optional verified `reviewId`, and `changes` array. Each change identifies `roomId` + `externalListingId` and includes only edited settings: `settings` for a new mapping, `priceAdjustment`, `automaticPriceSync`, and/or replacement `bookingRuleOverrides`. There are no per-field saves in this dialog.

Retry an identical failed/uncertain save with the same request ID and body. The server validates local identities and values first and journals settled steps. Provider APIs do not provide a cross-listing transaction; failures may leave settled steps applied, and existing unknown-outcome journals must be reconciled before conflicting writes. Never claim an all-or-nothing provider transaction.

Automatic-price opt-in can be saved before the review is verified. It remains `pending_review` until publication verification authorizes the exact mapping. Opt-out revokes future sends at save time. The publication review remains an explicit subsequent approval for source rates and availability; saving settings does not publish base-rate inventory. The request intent is stored separately from mapping identity so opt-in status updates do not invalidate verified mapping timestamps. No Onyx schema publication is required.


### Room-count estimates at consent

Console hotel consent asks for the total physical room count and displays the monthly estimate: $15 for the first five rooms, plus $1 per additional room. Single vacation rentals remain $10/month. Editing the count clears acceptance.

`enable` and property-import `start` accept `roomCount` and `estimatedMonthlyPriceUsd` together (for example, 8 and 18). The API recomputes the amount, rejects a mismatch, and retains `{roomCount, monthlyPriceUsd}` under `consent.estimate`; import sessions also retain the reviewed estimate. Existing accepted consent is preserved. These are estimates and consent records, not subscription collection requests. The first month remains free.


### Property-only Airbnb pause and resume

`{action:"pause",connectionId}` creates an open-ended close-out for this property's mapped room types on the selected Airbnb connection. It never deactivates a shared Airbnb account. Mappings, prices and booking restrictions remain unchanged. A successful response requires rule readback and all of the next 365 nights confirmed unavailable in each mapped listing calendar. Pending processing retains `pause_pending`; repeat Pause to verify. Unknown create outcomes require reconciliation rather than another POST.

`{action:"resume",connectionId,reviewed:true}` explicitly removes only the exact, unchanged Wikiup-owned close-out. Existing reservations, blocks and booking restrictions remain in effect. The response verifies rule removal, not downstream calendar availability. Other channels retain their existing exclusive-connection pause behavior. Owner/property.manage authorization applies to both commands.
