Skip to documentation
Wikiup Developers
⌘ K
Console

API Reference

Build a better stay.

Connect your property, reservations, and guest experience with the Wikiup API.

The Wikiup API powers room management, bookings, guest messaging, payments, and hosted widgets. Most endpoints return JSON; hosted widgets return HTML and communicate through iframe postMessage events.

Get started
Productionhttps://api.wikiup.app
Previewhttps://api-preview.wikiup.app
Your first request
cURL
curl https://api.wikiup.app/api/health
Example response
JSON
{
  "status": "ok"
}

Get started

Choose how to get started.

Use the console to set up your property visually, or create an account and integration credential through the API.

01

Use Wikiup Console

Create an account, verify your email, then create a property or accept an invitation. Create integration credentials from the console’s API keys page.

Open Console Manage API keys
02

Set up through the API

Verify an email address you own, create your account, and receive your first API key. No console session is needed for the registration flow.

Follow the quickstart

Programmatic quickstart

From email to your first property.

  1. Request a verification code

    POST your email to /api/accounts/registration. Save the returned registrationId and expiresAt. Retrieve the code from your inbox.

  2. Confirm your account

    Send the registration ID, emailed code, and your name to /api/accounts/registration/confirm. An optional password lets you choose a console password now; otherwise use the console password-reset flow later.

    The response includes your API key in apiKey.key. Capture it directly into a server-side secret store. The full key is returned only when issued; listing keys returns metadata. Remove temporary key files after the credential is safely stored.

  3. List your properties

    Set WIKIUP_API_KEY from your secret store and call GET /api/properties. A new account returns an empty list. Keep an existing property ID when one already matches your setup.

  4. Create a property when needed

    POST a property object with its name, contact details, and address. Include the inn's IANA time zone so dates and check-in cutoffs use local time. Save the returned membership's propertyId as WIKIUP_PROPERTY_ID.

  5. Make a scoped request

    Send both the Bearer credential and x-property-id to list rooms. An empty list is expected before rooms have been configured.

Use one environment throughout setup. The preview API is https://api-preview.wikiup.app; credentials and property IDs belong to their environment.

1. Request a code
cURL
curl -X POST 'https://api.wikiup.app/api/accounts/registration' \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com"}'
2. Confirm account
cURL
umask 077
WIKIUP_SETUP_DIR=$(mktemp -d)
curl -X POST 'https://api.wikiup.app/api/accounts/registration/confirm' \
  -H 'Content-Type: application/json' \
  -d '{"registrationId":"<registration-id>","code":"<emailed-code>","givenName":"Alex","familyName":"Morgan"}' \
  --output "$WIKIUP_SETUP_DIR/account.json"
WIKIUP_API_KEY=$(jq -er '.apiKey.key' "$WIKIUP_SETUP_DIR/account.json")
3. List properties
cURL
curl 'https://api.wikiup.app/api/properties' \
  -H "Authorization: Bearer $WIKIUP_API_KEY"
4. Create a property
cURL
curl -X POST 'https://api.wikiup.app/api/properties' \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"property":{"name":"Cedar Ridge Inn","phone":"+17605550100","email":"stay@example.com","timeZone":"America/Los_Angeles","address":{"line1":"100 Main Street","city":"Julian","state":"CA","postalCode":"92036","country":"US"}}}'
5. List rooms
cURL
curl 'https://api.wikiup.app/api/rooms' \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H "x-property-id: $WIKIUP_PROPERTY_ID"

AI-assisted integration

Give your assistant a clear starting point.

Use the prompt alongside the machine-readable onboarding guide. You remain in control of the inbox verification step and the property details.

Use a key matched to the job

The first key has account-wide read/write access. Use the console’s API keys page to issue a separate key for each integration, with read_only access and a property allowlist where possible. Key listing and issuance require an interactive account session. Creating a key requires sign-in within the past five minutes; Console handles reauthentication. API keys cannot create or manage other keys.

Keys expire after 90 days by default (up to 365). Rotate through the console: create and verify a replacement, then revoke the previous key. Existing property permissions still apply.

API keys cannot read connected mailbox messages, delete an account, or perform password, profile, or Google email connect/disconnect operations, delete a property, leave its membership, access team/invitation management, or accept an invitation. Use an interactive session for those account actions.

Prompt for your assistant
Text
Help me connect to Wikiup using https://api.wikiup.app/ai-onboarding.md.
Read the live API reference and follow its programmatic account setup.
Ask which environment to use and which email I own. Request its verification code,
then wait for me to provide it. Never ask for my email password.
Keep API keys in a server-side secret store; do not print, commit, or put them in browser code.
List my accessible properties first. Use an existing property if it matches my request;
ask for my property details before creating a new one.
Use Console to issue a restricted, read-only key unless my integration needs writes.
Tell me what was created and verified without revealing credentials.

Partner integration

Listing partners

Owner requests, affiliate approval and listing eligibility

Destination IDs: distinguish towns, states, and countries

Affiliate ratings: manage ratings and request fetch=ratings

Affiliate Integration Guide: listings, photos, availability and checkout

Affiliate listing API reference and response contracts

Listing suspension, removal and resuming

Affiliate login, API keys, attribution and commission reports

Fast area catalog and lazy availability integration

Hotel room details: See Details, room galleries and Reserve

Listing fields: description, tagline, stay type and ratings

Exact property map locations

Rollout verification: deployed revision, live results and remaining checks

Listing photos: owner management and affiliate image sources

Photo groups: listing gallery contract and Hidden San Diego implementation handoff

Show live stays on a destination guide, tourism site, or partner website such as Hidden San Diego. Your server searches participating properties with one request; visitors continue to Wikiup to complete their booking.

1. Create an email-associated partner key

Create a dedicated Wikiup account with your integration contact’s email and verify it. Open Console → Affiliate Portal to create your partner profile, then Affiliate API keys → Create key and choose Affiliate. Name the key for your site and set its expiration. Store the one-time secret on your server.

This affiliate key follows the verified account and adds signed attribution to booking links. It permits area catalogs, batch availability, regional search and direct listing content/availability reads, without property membership or access to guest records. No x-property-id header is required. Existing property keys remain limited to their permitted properties and published listings.

2. Choose which properties to show

Owners request inclusion from Property → Listing Partners. Review each property in Affiliate Portal → Requests and approve or deny with a reason. Every property requires your approval, including your own and existing listings. Use Affiliate Portal → Listings to hide approved properties from your site. Regional searches use a saved destination or an exact, unambiguous city match; unmapped properties remain in the portal catalog until their geography is corrected.

3. Connect your server and search

For fast browse-first pages, load GET /api/travel/listings?destination=julian-ca without dates. Render these cards as unchecked, then call POST /api/travel/listings/availability with up to 12 visible listing IDs or property IDs and the selected dates and party. Load later batches as visitors scroll. See the lazy-loading guidefor examples, per-card states, and handling late responses after date changes.

Set WIKIUP_API_ORIGIN to https://api-preview.wikiup.app for preview or https://api.wikiup.app for production, and store the matching key as WIKIUP_API_KEY. The travel endpoint and schema must be deployed in that environment first. Keep credentials out of client bundles, URLs, browser storage, and logs.

Use stable catalog IDs: julian-ca for a destination, east-county-san-diego-ca for its parent region, or san-diego-county-ca for the county. Send calendar dates as YYYY-MM-DD, plus adults and children. Pets are optional. Supported stays are 1–28 nights, with up to 20 guests per search.

4. Display the returned listings

Render the returned listings directly, using id as the card key. Wikiup returns one hotel card per property and one rental card per bookable item. Hotel prices are labeled “From.” Use imageVariants for responsive photos. Do not infer listing types or regroup rooms.

Catalog-only cards contain no prices or booking links. Once availability returns, format prices in the returned currency. Label nightlyRate as an average per night and staySubtotal as the accommodation subtotal excluding taxes and fees. Null taxes, fees, and final totals mean they are not yet calculated; never display them as zero or an all-inclusive price.

5. Handle incomplete searches and retries

Each request checks up to 12 properties. Offer another page when meta.nextPage is present, keeping the same search criteria. Preserve failures and meta.partial across pages; a last page alone does not prove the whole search is complete. Price sorting applies to loaded listings, not the entire region.

Show loading, no-availability, partial-results, and retry states. An empty result with failures is not sold out. A successful HTTP 200 can still contain provider failures. Never substitute sample inventory. The account budget is one search per second across its keys; honor Retry-After on 429 responses. Treat 401/403 as credential or access errors, 422 as invalid criteria, and 503 as temporary failure.

6. Send the guest to Wikiup checkout

For a hotel’s See Details page, request GET /api/travel/listings/{listingId}/rooms/{roomId} using the parent listing ID and exact availability option ID. This date-free response supplies the room or pooled room type’s description, amenities and gallery, without prices or booking links. Refresh parent availability for the selected dates and party, match options[].id exactly, and enable Reserve only when that option is currently available. See the room-detail cURL examples, fields and integration steps.

Set LISTING_ID to the selected catalog card’s exact ID, URL-encoded as a path segment. Request GET /api/travel/listings/{listingId}/availability with the guest’s current dates and party. A hotel returns available room or room-type choices in options; a rental returns its matching bookable option. Let the guest select an option and use that option’s bookingUrl as the Reserve button’s destination.

Navigate the guest’s browser to the whole returned URL unchanged. It carries the selected property, room or room type, dates, guests, pets, and signed affiliateReferral. Do not rebuild the URL, substitute the property’s website, or attach your API key. Affiliate keys do not create bookings through the owner reservation endpoints.

Wikiup checkout collects guest details and payment, rechecks availability, calculates taxes and fees, and handles reservation confirmation and the guest portal. The referral preserves affiliate attribution. Opening checkout is not a reservation or payment confirmation. Do not show booking success based on a Reserve click; this integration does not provide a partner booking-completion webhook.

If status is sold_out, disable Reserve and offer another stay. Keep request failures distinct from sold out. Fetch a new matching URL whenever dates or guests change; availability is not a hold and checkout can reject inventory that has since been booked.

The populated response example uses fictional IDs and an invalid example referral token. For the cURL checkout check, set BOOKING_URL to an actual selected option’s returned URL. This downloads HTML only; it does not book or charge. In your site, navigate to that URL rather than serving the downloaded HTML.

7. Verify your integration

Before launch, verify cross-owner inclusion, blacklist/restore, inactive inventory exclusion, matching destinations, guest capacity, unavailable dates, pooled counts, price labels, pagination, and retry states with isolated fixtures. Confirm that booking links retain the selected dates and guest count.

See the availability endpoint and full affiliate listing contract and rollout for field definitions, permissions, limits, and rollout requirements.

Browse listings without dates
cURL
curl --silent --show-error --fail-with-body --max-time 25 \
  --get "$WIKIUP_API_ORIGIN/api/travel/listings" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-store' \
  --data-urlencode 'destination=julian-ca' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=12'
Search live availability
cURL
curl --silent --show-error --fail-with-body --max-time 25 \
  --get "$WIKIUP_API_ORIGIN/api/travel/availability" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-store' \
  --data-urlencode 'destination=julian-ca' \
  --data-urlencode 'checkIn=2027-01-10' \
  --data-urlencode 'checkOut=2027-01-12' \
  --data-urlencode 'adults=2' \
  --data-urlencode 'children=0' \
  --data-urlencode 'pets=0' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=12'
Get bookable options for the selected listing
cURL
curl --silent --show-error --fail-with-body --max-time 25 \
  --get "$WIKIUP_API_ORIGIN/api/travel/listings/$LISTING_ID/availability" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-store' \
  --data-urlencode 'checkIn=2027-02-09' \
  --data-urlencode 'checkOut=2027-02-12' \
  --data-urlencode 'adults=2' \
  --data-urlencode 'children=0' \
  --data-urlencode 'pets=0'
Bookable options response
JSON
{
  "listingId": "hotel:property_example",
  "status": "available",
  "options": [
    {
      "id": "room_example",
      "roomId": "room_example",
      "roomTypeId": null,
      "name": "Garden King",
      "capacity": 2,
      "availableCount": 1,
      "currency": "USD",
      "nightlyRate": 200,
      "staySubtotal": 600,
      "priceBasis": "accommodation_subtotal",
      "taxes": null,
      "fees": null,
      "finalTotal": null,
      "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&roomId=room_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN",
      "photos": [
        "https://images.example.com/hotel/original.jpg"
      ],
      "coverImage": {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      },
      "maxGuests": 2,
      "image": "https://images.example.com/hotel/original.jpg",
      "imageVariants": [
        {
          "url": "https://images.example.com/hotel/640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ]
    }
  ],
  "complete": true,
  "generatedAt": "2027-01-10T09:00:00-08:00"
}
Check the returned checkout page (does not book)
cURL
curl --silent --show-error --fail-with-body --max-time 25 \
  "$BOOKING_URL" \
  -H 'Accept: text/html' \
  --output wikiup-checkout.html

Get started

Authentication

Use a session access token for an interactive Wikiup client, or an API key for a server-side integration. Both use the Bearer header. For property-scoped operations, also send the selected property ID from your property list.

Internal
Signed service requests only. Account sessions and property API keys cannot authorize these jobs.
Public
No bearer token is required. Public endpoints may still validate inputs, host names, signed paths, or third-party provider callbacks.
Bearer
Send a Wikiup session access token or an eligible API key as Authorization: Bearer <credential>. API keys cannot perform account/profile, password, connected-mailbox, Google OAuth, team/invitation, or key-management operations; those require a session token. A key can revoke itself.
Property
Send a Wikiup session access token or eligible API key. Header-scoped routes require x-property-id: <property-id>; path-scoped property routes authorize their explicit {id}. Current membership, permissions, key access level and property allowlist are enforced together. A header cannot override path ownership.
Widget
Public/widget flow endpoint. It validates widget or payment inputs and uses property/room identifiers supplied by the embed flow.
OAuth
Google OAuth browser redirect/callback endpoint. Query parameters are created by the OAuth handshake.
Guest
Uses a reservation-scoped guest portal session, not an innkeeper account. Follow the endpoint's token instructions; session-authenticated calls use Authorization: Bearer <guest-session-token>.
Webhook
Integration callback with signature verification. Use the provider's configured webhook delivery, not a user access token.
List your properties
cURL
curl https://api.wikiup.app/api/properties \
  -H 'Authorization: Bearer <access-token>'

Get started

Conventions

Request format
JSON mutation requests include Content-Type: application/json.
Dates & identifiers
Date-only parameters use YYYY-MM-DD in the property time zone. Values in braces, such as {id}, are placeholders.
Responses
Examples show representative shapes. Actual records may include additional fields.
Money
Units are endpoint-specific. Reservation prices and arrival/departure fees generally use major currency units (15 = $15.00); payment intents and modification/cancellation quotes use minor units (1500 = $15.00 for USD). Read each field's unit before displaying or submitting an amount.
Allowed values & partial updates
Enum values are case-sensitive. Omitted fields, null, and empty strings are not interchangeable. PATCH and PUT behavior varies by endpoint; use the documented wrapper and required fields.
Lists & retries
There is no universal pagination envelope or idempotency header. Use the pagination and retry fields listed for the specific operation. After an uncertain payment result, check its status before creating another charge.

HTTP status codes

200 / 201
Completed successfully / resource created
202
Request accepted; not proof of delivery or completion
204
Completed successfully with no body; do not parse JSON
400 / 422
Validation failed
401
Authentication required
403
Authenticated, but this action is forbidden
404
Resource not found or unavailable in this scope
409
Conflict, changed data, or additional confirmation required
429
Request or resource limit reached
5xx
Service or integration failure; check state before retrying a mutation

Errors may contain error as a string, error.message, or message. Some also include code and reason; handle the HTTP status first.

Get started

Common workflows

Work with a property

  1. Create an API key or sign in to Wikiup, then call GET /api/properties with the account's session access token or API key.
  2. Select a returned propertyId and send it in x-property-id on staff operations.
  3. Load GET /api/rooms or GET /api/reservations. Membership alone does not grant every action; the assigned permission group determines access. API key access levels and property allowlists narrow this further.

Complete a guest booking

  1. Use the hosted availability and booking widgets to collect the room, dates, guest details, and selected add-ons.
  2. POST /api/widget-bookings/payment-intent validates the booking and prepares payment. When requiresPayment is true, use the returned paymentSessionSecret with the payment UI. When false, skip payment collection and proceed to confirmation.
  3. Once payment is complete or no payment is required, call POST /api/widget-bookings/confirm. Use its reservationId, confirmation number, and payment status to finish the flow.

A payment intent alone is not a confirmed booking. Bank payments may be processing during the confirmation handoff; inspect the returned paymentStatus.

Let a guest manage their stay

  1. POST /api/guest-portal/access/request sends an access link when the supplied reservation and guest details match.
  2. Exchange the link credential using POST /api/guest-portal/access/exchange. Use the returned guest session for GET /api/guest-portal/context and subsequent guest operations.
  3. For an arrival/departure change, GET the available options, POST a quote, then PATCH to confirm at /api/guest-portal/reservation/arrival-departure. Show the quoted charge or refund before confirmation. Send the quoteId in the PATCH body and authorizeCharge: true for a positive charge only after the guest authorizes it.

Guest sessions are scoped to a reservation. Keep staff access tokens and guest sessions separate.

Cancel a paid reservation

  1. Use the cancellation eligibility and quote operations to calculate the fee and refundable amount.
  2. Present that quote to the guest or innkeeper. Complete any required payment step, then submit the quote to its matching confirmation endpoint.
  3. Refresh the reservation and payment records after confirmation. Requote when the API reports that a quote expired or the reservation changed.

DELETE /api/reservations/{id} changes reservation status; it does not execute a financial refund. Use POST /api/reservations/{id}/cancel/quote and POST /api/reservations/{id}/cancel/confirm for the staff cancellation workflow.

PMS integration

Staging test data

Build a complete property and reservation lifecycle through owner-authorized Wikiup APIs. Booking CRS creates external synthetic bookings; the normal revision consumer imports them back into Wikiup.

Choose an isolated target

Preview can control real booking-channel accounts. Use a separate property with no real OTA connections. A preview hostname, test-looking name or different login does not establish isolation.

Confirm the property ID and owner with GET /api/properties. Never reuse a real property, listing or rate mapping for test convenience.

Set up through ordinary APIs

  1. Create a synthetic property with POST /api/properties, explicit timezone and address. Property-restricted keys cannot create new properties.
  2. Create its room with POST /api/rooms and x-property-id. Save normal room pricing and booking rules. New rooms start Draft.
  3. Read channel management terms. The owner reviews and accepts the current version using enable; do not auto-accept terms.
  4. Submit prepare for the returned room ID. Existing completed setup operations and mappings are reused. No OTA authorization or fake channel connection is required.

Know which direction you are testing

POST /api/reservations tests direct booking creation in Wikiup. Booking CRS create, modify and cancel test external booking revisions arriving into Wikiup. These are complementary paths.

Use ordinary room pricing/rules and reservation screens for outbound scenario changes. A scripted provider payload or a test-only control is not proof that an ordinary PMS save propagates correctly.

Read the staging workflow as Markdown ↗

Preparation is not a booking

Prepare isolated room
JSON
{
  "action": "prepare",
  "roomId": "<isolated-room-id>"
}

Send to POST /api/properties/{id}/channel-management/sandbox-reservations with an owner credential. HTTP 200 with status: ready confirms preparation. It does not publish inventory or create a reservation.

Submitted → imported

  1. create returns HTTP 202 and a simulationId. Retain both that ID and the UUID requestId.
  2. Poll GET staging reservations. delivery: pending means not imported; received can require review; applied confirms ingestion.
  3. verify runs guarded reservation ingestion and acknowledgement only. It does not publish rates, rules or availability. Check verification.complete and blocked, not HTTP status alone.
  4. Modify or cancel only the recorded simulationId. Verify again and inspect its ordinary Wikiup reservation through the returned reservationIds.
Verify ingestion
JSON
{
  "action": "verify"
}

Retry without duplicate bookings

Reuse an identical requestId and body after a client/network interruption. Changed input requires a new UUID. Uncertain upstream creation requires reconciliation; never reset a journal or submit a different ID just to force a retry.

401 means authentication failed; 403 means environment/owner/permission denied; 404 identifies a missing scoped resource; 409 covers conflicting or unsafe state; 422 covers invalid input or provider validation; 503 indicates unavailable configuration. See command-specific constraints below.

Keep the boundary explicit

No real OTA booking, payment or guest email is created by Booking CRS operations. Synthetic records are still persisted in the staging databases. There is no bulk test-data reset endpoint: cancel only recorded test bookings and review any teardown separately.

This workflow does not certify an integration. Provider review, production credentials and paid agreements remain separate, human-reviewed processes. Never submit keys, guest data or unverified task IDs as evidence.

White-label API · Sandbox rollout

Channel management

Complete API workflow and request examples · Build the entire setup in your own application with an owner-bound read/write API key.

Import an existing hotel or rental

Use /api/channel-management/property-import to start an owner-bound import without the manual property creation endpoint. Choose and authorize a channel, select up to 500 hotel rooms or one rental listing, review source values and complete missing property details, then import and map each room. Finish activates with sales closed and reconciles reservations. The property becomes visible after completion; availability still requires explicit review and approval. The complete request shapes and resume/cancel operations are in the linked API workflow.

Enable a property

Read GET /api/properties/{id}/channel-management for the current workspace, both pricing choices in plans, and channel catalog. The property owner accepts the terms with the enable action on the same endpoint.

A single vacation rental costs $10 USD per property per month. A hotel, inn or B&B costs $15 USD per property per month for the first 5 physical rooms, plus $1 USD per additional room each month. Vacation-rental portfolios require a quote. Use the returned terms and owner review for the current billing policy. Sandbox acceptance does not collect payment; production activation is blocked.

Authorize and map

  1. Send connect with a catalog channel code and any required settings. Open the returned authorization URL when authorization is required. Set redirectUrl to return to your application. Preview sample consent can also be completed directly through the API using the returned token and channelId.
  2. Complete the authenticated, expiring, owner-bound callback at POST /api/channel-management/authorization. Provider identifiers never establish Wikiup ownership.
  3. Use listings and the returned mapping fields to connect an external listing and rate to a Wikiup room with map.
  4. Run activate after reviewing the mappings. Sandbox activation starts with sales closed and requests available existing reservations. pause deactivates the connection.
  5. Run sync, then review for reservation counts, rooms, prices, source coverage and stable approval blockers. After explicit owner approval, send approve with reviewed:true. Approval covers every active channel at this property. A new activation clears previous availability approval.

Preview can contain real account connections as well as simulated samples. Check the simulated flag and property mappings; never assume a preview hostname prevents changes to real listing availability or prices. Vrbo uses a separate account-preparation, sample-credential and sign-in-code flow, followed by a connection test and room/rate mapping. Its preview connect command uses settings with previousManagerDisconnected and calendarImportsRemoved set to true, username host@example.test, password wikiup-vrbo-preview and verificationCode 123456. These are public test fixtures; do not submit real Vrbo credentials in preview. Production shows only channels explicitly enabled after validation. Owners can request another channel with the request_channel action. Authorization on external sites may identify the connectivity partner.

Test reservation delivery in preview

Use /api/properties/{id}/channel-management/sandbox-reservations on the preview API with an owner token or owner-bound API key. Enable a dedicated test property with no real connected booking channels. Simulated preview connections are allowed. No real OTA booking, payment or guest email is created.

Start with prepare and the saved roomId; this installs/reuses Booking CRS and the room mapping without creating a booking. Submit create, modify or cancel with a unique UUID requestId. Reuse that ID and the identical body when retrying. Poll GET until delivery: applied confirms the update reached Wikiup. Use verify for guarded revision ingestion and acknowledgement only; it does not publish rates, rules or availability. See the staging test-data workflow for setup, status interpretation and errors. Production rejects these operations.

Import hotel rooms or an existing rental

Use preview_import to review an authorized listing, then import to create a Draft room. Hotel plans support multiple room imports, up to 500 room types. A vacation rental creates one bookable home; bedrooms do not become separate rooms. Photos, when supplied by the channel, copy in resumable batches.

Import only the reservations the source makes available. Full reservation history, guest details and fees are not guaranteed. Review coverage and reconcile existing reservations before opening sales. Imports create no payments or guest emails.

Synchronize bookings and availability

Incoming revisions are sanitized and saved durably. Revisions are acknowledged only after a successful save. Unmapped rooms and booking conflicts remain unacknowledged and appear as issues. Duplicate revisions reuse the same local reservation identifiers.

Authenticated webhook signals and a 15-minute backup polling workflow use the same inbox. sync runs an owner-requested check. Missing mappings, unresolved revisions and stale reservation checks block opening inventory.

The reviewed approve action (publish remains an alias) sends absolute inventory and standard nightly rates for 365 property-local dates. Occupied nights and inactive rooms stay closed. Provider acceptance is shown separately from OTA delivery; it does not guarantee delivery or eliminate double-booking risk. Production rollout and recurring billing are not enabled.

API Reference

Account

Submits an iOS profile setup error report to Wikiup support.

Body fields

screenstringRequired

profile-photo-setup

operationstringRequired

upload-profile-image, complete-profile or load-profile-image

messagestringRequired

Bounded plain diagnostic summary without personal data or credentials.

httpStatusintegerOptional

Optional HTTP status; omit if unavailable. Null is rejected.

requestPathstringOptional

Optional diagnostic path: /api/signed-url, /api/users/profile or /api/profile-photo-upload. Null is rejected.

appVersionstringRequired

App version and build.

platformstringRequired

ios

Behavior & constraints

  • User session required; API keys are denied. Recipient is fixed to Wikiup support. Raw HTML, credential-like text, URLs and recipient overrides are rejected. One submission per account per minute; 429 responses include Retry-After. A 202 response confirms provider acceptance, not inbox delivery.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/support/error-reports' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"screen":"profile-photo-setup","operation":"upload-profile-image","message":"Profile photo setup could not be completed.","httpStatus":500,"requestPath":"/api/signed-url","appVersion":"1.0 (3)","platform":"ios"}'
Example response
JSON
{
  "status": "submitted",
  "reportId": "generated-id"
}

Reads personal push notification preferences for a property.

Query parameters

propertyIdstringRequired

A property the authenticated user belongs to.

Behavior & constraints

  • Times follow the property timezone, including daylight saving. Quiet hours and off-shift alerts are suppressed, not queued. Inbox history is unchanged. Preferences never grant access to notifications.
  • Reservation change types appear under Reservation changes in console and iOS. Disabling the master switch preserves its child choices. Pricing and fee-waiver edits do not send modification alerts. Cancellation retains its separate switch. One notification per recipient includes only enabled changes.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/users/me/notification-preferences' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "message": "success"
}

Saves personal push notification types, shift-only delivery and quiet hours for a property.

Query parameters

propertyIdstringRequired

A property the authenticated user belongs to.

Body fields

chatMessagesbooleanOptional

Chat message alerts; defaults to true

shiftCoverageRequestsbooleanOptional

Shift coverage request alerts; defaults to true

newReservationsbooleanRequired

New reservation alerts

changedReservationsbooleanRequired

Master switch for reservation modification alerts

reservationChangeTypesobjectOptional

Per-type booleans: dates, room, checkinCheckout, status, restored, guestDetails, guestCounts, arrivalDeparture, selfCheckin, notes, addOns. Missing stored choices default to true; omitted PUT choices retain their saved values.

canceledReservationsbooleanRequired

Canceled reservation alerts

onlyDuringShiftsbooleanRequired

Only during assigned shifts

quietHoursEnabledbooleanRequired

Suppress alerts during quiet hours

quietStartstringRequired

HH:mm in property timezone

quietEndstringRequired

HH:mm in property timezone

Behavior & constraints

  • Times follow the property timezone, including daylight saving. Quiet hours and off-shift alerts are suppressed, not queued. Inbox history is unchanged. Preferences never grant access to notifications.
  • Reservation change types appear under Reservation changes in console and iOS. Disabling the master switch preserves its child choices. Pricing and fee-waiver edits do not send modification alerts. Cancellation retains its separate switch. One notification per recipient includes only enabled changes.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/users/me/notification-preferences' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "message": "success"
}

API Reference

Add-ons

List the property's add-on catalog for catalog management and innkeeper reservation selection. Paid early check-in/late check-out offers are synthesized from property fee settings rather than stored as ordinary catalog items.

Console add-on catalog and reservation editor; native iOS reservation add-ons.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires addons.manage or reservations.manage (or owner access).
Request
cURL
curl 'https://api.wikiup.app/api/reservation-add-ons' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
[
  {
    "id": "addon_123",
    "propertyId": "PROPERTY_ID",
    "label": "Fresh flowers",
    "amount": 48,
    "description": "A seasonal bouquet in your room.",
    "image": null,
    "icon": "flower",
    "maxQuantity": 1,
    "status": "Active"
  }
]

Create a catalog extra that guests and innkeepers can select for a stay. The label must be unique within the property.

Console add-on catalog editor.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

labelstringRequired

Unique catalog display name.

amountnumberRequired

Unit price in major currency units.

descriptionstring | nullOptional

Guest-facing description.

imagestring | nullOptional

Catalog image URL; existing selections retain their saved snapshot.

iconstringRequired

Icon identifier; supply an empty string when no icon is needed.

maxQuantityintegerRequired

Maximum selectable quantity.

statusstringOptional

Use Active to offer the add-on in booking; Inactive hides it from new selections.

Allowed valuesActiveInactive

Behavior & constraints

  • Requires addons.manage. The server assigns the ID and property; duplicate labels return 409.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservation-add-ons' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"label":"Fresh flowers","amount":48,"description":"A seasonal bouquet in your room.","icon":"flower","maxQuantity":1,"status":"Active"}'
Response · 201
JSON
{
  "id": "addon_123",
  "propertyId": "PROPERTY_ID",
  "label": "Fresh flowers",
  "amount": 48,
  "description": "A seasonal bouquet in your room.",
  "image": null,
  "icon": "flower",
  "maxQuantity": 1,
  "status": "Active"
}

Retrieve a single property-owned add-on catalog entry.

Catalog detail API; reservation editors normally load the catalog collection.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires addons.manage or reservations.manage.
Request
cURL
curl 'https://api.wikiup.app/api/reservation-add-ons/addon_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "id": "addon_123",
  "propertyId": "PROPERTY_ID",
  "label": "Fresh flowers",
  "amount": 48,
  "description": "A seasonal bouquet in your room.",
  "image": null,
  "icon": "flower",
  "maxQuantity": 1,
  "status": "Active"
}

Update the catalog entry for future selections. Existing reservations retain their saved add-on prices and descriptions, so changing the catalog does not retroactively reprice paid extras.

Console add-on editor and active/inactive toggle.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

labelstringOptional

Unique catalog display name.

amountnumberOptional

Unit price in major currency units.

descriptionstring | nullOptional

Guest-facing description.

imagestring | nullOptional

Catalog image URL; existing selections retain their saved snapshot.

iconstringOptional

Icon identifier; supply an empty string when no icon is needed.

maxQuantityintegerOptional

Maximum selectable quantity.

statusstringOptional

Use Active to offer the add-on in booking; Inactive hides it from new selections.

Allowed valuesActiveInactive

Behavior & constraints

  • Requires addons.manage. Both PUT and PATCH merge supplied fields with the existing entry. Duplicate labels return 409.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/reservation-add-ons/addon_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amount":50,"status":"Active"}'
Response · 200
JSON
{
  "id": "addon_123",
  "propertyId": "PROPERTY_ID",
  "label": "Fresh flowers",
  "amount": 50,
  "description": "A seasonal bouquet in your room.",
  "image": null,
  "icon": "flower",
  "maxQuantity": 1,
  "status": "Active"
}

Update the catalog entry for future selections. Existing reservations retain their saved add-on prices and descriptions, so changing the catalog does not retroactively reprice paid extras.

Console add-on editor and active/inactive toggle.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

labelstringOptional

Unique catalog display name.

amountnumberOptional

Unit price in major currency units.

descriptionstring | nullOptional

Guest-facing description.

imagestring | nullOptional

Catalog image URL; existing selections retain their saved snapshot.

iconstringOptional

Icon identifier; supply an empty string when no icon is needed.

maxQuantityintegerOptional

Maximum selectable quantity.

statusstringOptional

Use Active to offer the add-on in booking; Inactive hides it from new selections.

Allowed valuesActiveInactive

Behavior & constraints

  • Requires addons.manage. Both PUT and PATCH merge supplied fields with the existing entry. Duplicate labels return 409.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/reservation-add-ons/addon_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amount":50,"status":"Active"}'
Response · 200
JSON
{
  "id": "addon_123",
  "propertyId": "PROPERTY_ID",
  "label": "Fresh flowers",
  "amount": 50,
  "description": "A seasonal bouquet in your room.",
  "image": null,
  "icon": "flower",
  "maxQuantity": 1,
  "status": "Active"
}

Delete an add-on from the property catalog. Reservation snapshots already containing it remain part of their invoices.

Console catalog deletion.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires addons.manage.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/reservation-add-ons/addon_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "message": "ReservationAddOn deleted successfully."
}

API Reference

Affiliates

Read your affiliate ratings for a property.

Path parameters

propertyIdstringRequired

Raw property ID, not the prefixed hotel/rental ID.

Response fields

propertyIdstringRequired

Raw property ID.

starRatingnumber | nullRequired

Affiliate editorial classification; not guest reviews. Null is unset. minimum: 1; maximum: 5; multipleOf: 0.5

priceTierinteger | nullRequired

1 Budget, 2 Value, 3 Mid-range, 4 Upscale, 5 Luxury; null is unset. Not a price quote. minimum: 1; maximum: 5

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.
404
Property does not exist.
429
Account-wide rate limit; honor Retry-After: 1.

Behavior & constraints

  • Private, no-store. Keep credentials server-side.
  • Pending local contract; schema publication and deployment are not yet verified. See /affiliate-listing-ratings.md.
  • GET listings omits ratings by default. fetch=ratings resolves this affiliate’s nested ratings object. Different affiliates have independent values; multiple keys for the same account share them.
  • PUT requires both nullable fields and rejects unknown fields. DELETE clears ratings only, preserving blacklist selection. Neither method modifies owner fields or booking commission.
Request
cURL
curl 'https://api-preview.wikiup.app/api/affiliates/listings/property_example/ratings' \
  -H 'Authorization: Bearer <affiliate-api-key>'
Response · 200
JSON
{
  "propertyId": "property_example",
  "starRating": 4.5,
  "priceTier": 3
}
Response JSON schema

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Create or replace your affiliate ratings for a property.

Path parameters

propertyIdstringRequired

Raw property ID, not the prefixed hotel/rental ID.

Body fields

starRatingnumber | nullRequired

1–5 in increments of 0.5; null clears the classification.

priceTierinteger | nullRequired

1 Budget, 2 Value, 3 Mid-range, 4 Upscale, 5 Luxury; null clears the tier.

Response fields

propertyIdstringRequired

Raw property ID.

starRatingnumber | nullRequired

Affiliate editorial classification; not guest reviews. Null is unset. minimum: 1; maximum: 5; multipleOf: 0.5

priceTierinteger | nullRequired

1 Budget, 2 Value, 3 Mid-range, 4 Upscale, 5 Luxury; null is unset. Not a price quote. minimum: 1; maximum: 5

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.
404
Property does not exist.
429
Account-wide rate limit; honor Retry-After: 1.

Behavior & constraints

  • Private, no-store. Keep credentials server-side.
  • Pending local contract; schema publication and deployment are not yet verified. See /affiliate-listing-ratings.md.
  • GET listings omits ratings by default. fetch=ratings resolves this affiliate’s nested ratings object. Different affiliates have independent values; multiple keys for the same account share them.
  • PUT requires both nullable fields and rejects unknown fields. DELETE clears ratings only, preserving blacklist selection. Neither method modifies owner fields or booking commission.
Request
cURL
curl -X PUT 'https://api-preview.wikiup.app/api/affiliates/listings/property_example/ratings' \
  -H 'Authorization: Bearer <affiliate-api-key>' \
  -H 'Content-Type: application/json' --data '{"starRating":4.5,"priceTier":3}'
Response · 200
JSON
{
  "propertyId": "property_example",
  "starRating": 4.5,
  "priceTier": 3
}
Response JSON schema

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Clear ratings while preserving your blacklist.

Path parameters

propertyIdstringRequired

Raw property ID, not the prefixed hotel/rental ID.

Response fields

propertyIdstringRequired

Raw property ID.

starRatingnumber | nullRequired

Affiliate editorial classification; not guest reviews. Null is unset. minimum: 1; maximum: 5; multipleOf: 0.5

priceTierinteger | nullRequired

1 Budget, 2 Value, 3 Mid-range, 4 Upscale, 5 Luxury; null is unset. Not a price quote. minimum: 1; maximum: 5

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.
404
Property does not exist.
429
Account-wide rate limit; honor Retry-After: 1.

Behavior & constraints

  • Private, no-store. Keep credentials server-side.
  • Pending local contract; schema publication and deployment are not yet verified. See /affiliate-listing-ratings.md.
  • GET listings omits ratings by default. fetch=ratings resolves this affiliate’s nested ratings object. Different affiliates have independent values; multiple keys for the same account share them.
  • PUT requires both nullable fields and rejects unknown fields. DELETE clears ratings only, preserving blacklist selection. Neither method modifies owner fields or booking commission.
Request
cURL
curl -X DELETE 'https://api-preview.wikiup.app/api/affiliates/listings/property_example/ratings' \
  -H 'Authorization: Bearer <affiliate-api-key>'
Response · 200
JSON
{
  "propertyId": "property_example",
  "starRating": null,
  "priceTier": null
}
Response JSON schema

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Read your affiliate profile and commission terms.

Response fields

accountobject | nullRequired

Null until the profile is created.

account.idstringRequired

Affiliate account UID, derived from the authenticated account.

account.namestringRequired

Affiliate display name.

account.websitestringRequired

HTTPS affiliate website or social profile URL.

account.activebooleanRequired

Whether the platform permits affiliate activity. Self-service cannot reactivate a suspended account.

account.createdAtstringRequired

Account creation time. ISO 8601 instant; format displayed times in the relevant property timezone. format: date-time

account.imageUrlstring | nullOptional

Affiliate card image path under /api/web-assets/affilate-profile-pics/{uid}/, separate from user profile photos. Null means no image.

account.descriptionstring | nullOptional

Affiliate card description, plain text; null when absent. maxLength: 500

account.regionstring | nullOptional

Affiliate card region, plain text; null when absent. maxLength: 120

termsobject | nullRequired

Read-only fixed Wikiup commission policy, including before affiliate onboarding.

terms.idstringRequired

Affiliate account UID.

terms.commissionBps75Required

Fixed 75 basis points (0.75%) of accommodation after discounts only; excludes add-ons, fees and taxes.

emailstringRequired

Verified email of the authenticated session.

platformAdminbooleanRequired

Whether this session has the platform administration claim.

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.

Behavior & constraints

  • Verified-email session only. GET can return account:null before onboarding; terms always reports the fixed Wikiup rate.
  • PUT cannot set commission or reactivate suspension; hosting access is unchanged. Unknown body fields are rejected.
Request
cURL
curl 'https://api-preview.wikiup.app/api/affiliates/account' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "account": {
    "id": "affiliate_example",
    "name": "Example Travel Guide",
    "description": "Independent guides to remarkable stays.",
    "region": "San Diego County",
    "website": "https://example.com/",
    "imageUrl": "/api/web-assets/affilate-profile-pics/affiliate_example/card.jpg",
    "active": true,
    "createdAt": "2027-01-10T09:00:00-08:00"
  },
  "terms": {
    "id": "affiliate_example",
    "commissionBps": 75
  },
  "email": "partner@example.com",
  "platformAdmin": false
}
Response JSON schema
Not yet enrolled
Not yet enrolled
JSON
{
  "account": null,
  "terms": {
    "id": "affiliate_example",
    "commissionBps": 75
  },
  "email": "partner@example.com",
  "platformAdmin": false
}

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Create or update your affiliate profile.

Body fields

descriptionstring | nullOptional

Optional plain text, up to 500 characters. Omit to preserve; null or blank clears.

regionstring | nullOptional

Optional region text, up to 120 characters. Omit to preserve; null or blank clears.

imageUrlstring | nullOptional

Optional card image uploaded under /api/web-assets/affilate-profile-pics/{uid}/. Omit to preserve; null removes it. Separate from the user profile photo.

namestringRequired

Trimmed display name; 1–120 characters.

websitestringRequired

HTTPS website or social profile URL; at most 2000 characters, no embedded credentials.

Response fields

accountobject | nullRequired

Null until the profile is created.

account.idstringRequired

Affiliate account UID, derived from the authenticated account.

account.namestringRequired

Affiliate display name.

account.websitestringRequired

HTTPS affiliate website or social profile URL.

account.activebooleanRequired

Whether the platform permits affiliate activity. Self-service cannot reactivate a suspended account.

account.createdAtstringRequired

Account creation time. ISO 8601 instant; format displayed times in the relevant property timezone. format: date-time

account.imageUrlstring | nullOptional

Affiliate card image path under /api/web-assets/affilate-profile-pics/{uid}/, separate from user profile photos. Null means no image.

account.descriptionstring | nullOptional

Affiliate card description, plain text; null when absent. maxLength: 500

account.regionstring | nullOptional

Affiliate card region, plain text; null when absent. maxLength: 120

termsobject | nullRequired

Read-only fixed Wikiup commission policy, including before affiliate onboarding.

terms.idstringRequired

Affiliate account UID.

terms.commissionBps75Required

Fixed 75 basis points (0.75%) of accommodation after discounts only; excludes add-ons, fees and taxes.

emailstringRequired

Verified email of the authenticated session.

platformAdminbooleanRequired

Whether this session has the platform administration claim.

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.

Behavior & constraints

  • Verified-email session only. GET can return account:null before onboarding; terms always reports the fixed Wikiup rate.
  • PUT cannot set commission or reactivate suspension; hosting access is unchanged. Unknown body fields are rejected.
Request
cURL
curl -X PUT 'https://api-preview.wikiup.app/api/affiliates/account' \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Content-Type: application/json' --data '{"name":"Example Travel Guide","website":"https://example.com/","imageUrl":"/api/web-assets/affilate-profile-pics/affiliate_example/card.jpg","description":"Independent guides to remarkable stays.","region":"San Diego County"}'
Response · 200
JSON
{
  "account": {
    "id": "affiliate_example",
    "name": "Example Travel Guide",
    "description": "Independent guides to remarkable stays.",
    "region": "San Diego County",
    "website": "https://example.com/",
    "imageUrl": "/api/web-assets/affilate-profile-pics/affiliate_example/card.jpg",
    "active": true,
    "createdAt": "2027-01-10T09:00:00-08:00"
  },
  "terms": {
    "id": "affiliate_example",
    "commissionBps": 75
  },
  "email": "partner@example.com",
  "platformAdmin": false
}
Response JSON schema
Not yet enrolled
Not yet enrolled
JSON
{
  "account": null,
  "terms": {
    "id": "affiliate_example",
    "commissionBps": 75
  },
  "email": "partner@example.com",
  "platformAdmin": false
}

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Search your listing requests across owners and open their review and management details.

Query parameters

pageintegerOptional

One-based page, 1–1000; defaults to 1. Page size is fixed at 12.

searchstringOptional

Case-insensitive property name, listing title or town substring; at most 200 characters. Applied before pagination.

statusstringOptional

all, pending, approved, denied, owner_suspended, affiliate_suspended, both_suspended, withdrawn, removed. Omit for approved/suspended only.

Response fields

listingsArray<object>Required

Up to 12 matching properties, ordered by propertyId. Search and status filtering happen before pagination.

listings[]objectRequired

Private affiliate management listing; status=all includes every request state. Only the newest request per property is returned.

listings[].propertyIdstringRequired

Raw Wikiup property ID; not a hotel/rental listing ID.

listings[].namestringRequired

Public listing title, falling back to property name.

listings[].destinationstring | nullRequired

Display destination name, falling back to saved city/state. Null when geography is unavailable. Not a destination search ID.

listings[].visiblebooleanRequired

Compatibility field derived from status: true only for approved. Inventory eligibility is checked separately for public reads.

listings[].requestIdstringRequired

Newest request ID used to retrieve private review details and change listing status.

listings[].status"pending" | "approved" | "denied" | "owner_suspended" | "affiliate_suspended" | "both_suspended" | "withdrawn" | "removed"Required

Current listing lifecycle state, including both parties’ suspensions.

listings[].listingIdstring | nullRequired

Stable public hotel/rental listing ID when approved with eligible inventory and a single public listing target. Null for other request states, unavailable inventory, or a property with multiple rental targets. Use requestId for private management regardless.

listings[].coverImageobject | nullRequired

First saved listing photo using the public image contract; null when no photo is available. No slideshow fallback.

listings[].coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listings[].coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listings[].coverImage.altstringRequired

Image alternative text for accessible presentation.

listings[].coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listings[].coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listings[].coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

listings[].coverImage.variants[]objectRequired

Response structure: ImageVariant.

listings[].coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listings[].coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listings[].coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listings[].coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

listings[].coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

listings[].coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listings[].coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

listings[].tagLinestring | nullRequired

Owner-supplied property tagline; null when unset. maxLength: 100

metaobjectRequired

Pagination for this management catalog.

meta.pageintegerRequired

Requested one-based page.

meta.nextPageinteger | nullRequired

Next page number, or null at the end.

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.

Behavior & constraints

  • Verified-email session and active affiliate account required. This is a management catalog, not the public date-free travel catalog.
  • The newest request per property determines status. Pending requests sort first before pagination, with stable property-ID ordering within each group. status=all includes pending, approved, denied, suspended, withdrawn and removed requests belonging to this affiliate. Omitted status retains approved/suspended behavior. visible is derived from status; public eligibility is unchanged.
  • destination is a display name or city/state fallback, not the stable ID accepted by travel search. No dates, pricing or room details are returned here. Follow meta.nextPage with the same filters, restarting at page 1 when they change. Results use stable propertyId order. listingId points to eligible public detail when available; requestId always opens private review details. Photos and inventory are loaded only for the returned page. A provider failure returns 503, never a successful empty result.
Request
cURL
curl 'https://api-preview.wikiup.app/api/affiliates/listings?page=1&status=all&search=Julian' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "listings": [
    {
      "propertyId": "property_example",
      "requestId": "request_example",
      "status": "approved",
      "name": "Example Hotel",
      "destination": "Julian",
      "visible": true,
      "listingId": "hotel:property_example",
      "tagLine": "A peaceful mountain stay",
      "coverImage": {
        "id": "photo_example",
        "url": "https://example.com/listing-cover.jpg",
        "alt": "Hotel entrance",
        "width": 1600,
        "height": 900,
        "variants": [],
        "group": null
      }
    },
    {
      "propertyId": "property_hidden",
      "requestId": "request_hidden",
      "status": "affiliate_suspended",
      "name": "Example Cottage",
      "destination": "Julian",
      "visible": false,
      "listingId": null,
      "tagLine": "A quiet cottage",
      "coverImage": null
    }
  ],
  "meta": {
    "page": 1,
    "nextPage": null
  }
}
Response JSON schema
Empty management page
Empty management page
JSON
{
  "listings": [],
  "meta": {
    "page": 1,
    "nextPage": null
  }
}

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Hide or restore a property for your affiliate account.

Body fields

propertyIdstringRequired

Raw property ID, 1–128 characters.

visiblebooleanRequired

False hides the property; true restores default inclusion.

Response fields

propertyIdstringRequired

Raw Wikiup property ID; not a prefixed listing ID.

visiblebooleanRequired

True includes this property; false blacklists it for this affiliate only.

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.
409
Property is no longer eligible for affiliate listing.

Behavior & constraints

  • Verified-email session and active affiliate account required. Only this affiliate’s selection changes. Ratings are preserved.
  • Compatibility endpoint: visible:false suspends for the affiliate; visible:true clears only the affiliate suspension. It never overrides the owner suspension. Use the listing-request PATCH route for new integrations. The response echoes the requested propertyId and visible; GET returns effective visibility.
Request
cURL
curl -X PUT 'https://api-preview.wikiup.app/api/affiliates/listings' \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Content-Type: application/json' --data '{"propertyId":"property_example","visible":false}'
Response · 200
JSON
{
  "propertyId": "property_example",
  "visible": false
}
Response JSON schema

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Read attributed bookings and pending or earned commission without guest records.

Query parameters

searchstringOptional

Case-insensitive property name or listing title match; max 120 characters. Filters before pagination.

fromstringOptional

Inclusive check-in date, YYYY-MM-DD. Optional.

tostringOptional

Inclusive check-in date, YYYY-MM-DD. Must not precede from.

cursorstringOptional

Opaque previous meta.nextCursor, max 4096 characters. Omit for first page.

Response fields

bookingsArray<object>Required

Up to 25 attributed bookings, newest creation first.

bookings[]objectRequired

Attributed booking projection without guest or access details.

bookings[].idstringRequired

Reservation ID for report correlation.

bookings[].propertyNamestringRequired

Current public property title/name, or Unavailable property if no longer readable.

bookings[].bookedAtstringRequired

Booking creation instant. ISO 8601 instant; format displayed times in the relevant property timezone. format: date-time

bookings[].checkInstringRequired

Property-local arrival date, YYYY-MM-DD.

bookings[].checkOutstringRequired

Property-local departure date, YYYY-MM-DD; checkout is not an occupied night.

bookings[].reservationStatusstringRequired

Stored reservation lifecycle status, such as upcoming, checkedin, checkedout or canceled.

bookings[].currencystringRequired

Three-letter currency code. Money is in major currency units.

bookings[].accommodationSubtotalnumberRequired

Accommodation subtotal after discounts captured at attribution; excludes taxes and fees.

bookings[].refundsnumberRequired

Successful completed ledger refunds for this reservation; conservatively reduce commission base dollar-for-dollar.

bookings[].commissionBps75Required

Fixed 75 basis points (0.75%) of accommodation after discounts only; excludes add-ons, fees and taxes.

bookings[].pendingCommissionnumberRequired

Fixed-rate estimated commission before checkout; zero after checkout/cancellation.

bookings[].earnedCommissionnumberRequired

Fixed-rate commission after checkedout status, reduced by refunds and limited to collected funds; not a payout.

bookings[].commissionStatus"canceled" | "earned" | "pending"Required

Commission calculation state. Legacy missing rates use the fixed policy.

metaobjectRequired

Report pagination and accounting scope.

meta.nextCursorstring | nullRequired

Opaque cursor for the next request; null when finished.

meta.totalsScope"page"Required

Values apply to the returned page, not an account-wide aggregate.

meta.payoutsTrackedfalseRequired

Payouts are not tracked here. Never label earned commission as paid.

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.

Behavior & constraints

  • Verified-email session and active affiliate account required. 25 bookings per page, newest creation first. Follow meta.nextCursor.
  • No guest names, email, access codes or confirmation codes are exposed.
  • Commission is fixed at 0.75% of the booking’s captured accommodation subtotal after discounts, excluding add-ons, fees and taxes. Refunds reduce the base; checkedout status makes commission earned, limited to collected funds. This does not mean paid. Legacy missing or different rates use the fixed policy; no terms setup is needed.
Request
cURL
curl 'https://api-preview.wikiup.app/api/affiliates/reports' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "bookings": [
    {
      "id": "reservation_example",
      "propertyName": "Example Hotel",
      "bookedAt": "2027-01-10T09:00:00-08:00",
      "checkIn": "2027-02-09",
      "checkOut": "2027-02-12",
      "reservationStatus": "upcoming",
      "currency": "USD",
      "accommodationSubtotal": 600,
      "refunds": 0,
      "commissionBps": 75,
      "pendingCommission": 4.5,
      "earnedCommission": 0,
      "commissionStatus": "pending"
    }
  ],
  "meta": {
    "nextCursor": null,
    "totalsScope": "page",
    "payoutsTracked": false
  }
}
Response JSON schema

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

List affiliate accounts and their current terms.

Query parameters

cursorstringOptional

Opaque previous nextCursor, max 4096 characters. Fixed 25 accounts per page.

Response fields

accountsArray<object>Required

Up to 25 profiles with their current terms.

accounts[]objectRequired

Affiliate profile; this does not grant hosting access.

accounts[].idstringRequired

Affiliate account UID, derived from the authenticated account.

accounts[].namestringRequired

Affiliate display name.

accounts[].websitestringRequired

HTTPS affiliate website or social profile URL.

accounts[].activebooleanRequired

Whether the platform permits affiliate activity. Self-service cannot reactivate a suspended account.

accounts[].createdAtstringRequired

Account creation time. ISO 8601 instant; format displayed times in the relevant property timezone. format: date-time

accounts[].termsobject | nullRequired

Current platform terms, or null.

accounts[].terms.idstringRequired

Affiliate account UID.

accounts[].terms.commissionBps75Required

Fixed 75 basis points (0.75%) of accommodation after discounts only; excludes add-ons, fees and taxes.

accounts[].imageUrlstring | nullOptional

Affiliate card image path under /api/web-assets/affilate-profile-pics/{uid}/, separate from user profile photos. Null means no image.

accounts[].descriptionstring | nullOptional

Affiliate card description, plain text; null when absent. maxLength: 500

accounts[].regionstring | nullOptional

Affiliate card region, plain text; null when absent. maxLength: 120

nextCursorstring | nullRequired

Opaque cursor for the next page; null when finished.

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.
404
Affiliate account does not exist (PUT).

Behavior & constraints

  • Platform administration only. Changes account activity, never commission terms. Historical attribution stays stored; reporting uses the fixed 0.75% policy.
Request
cURL
curl 'https://api-preview.wikiup.app/api/affiliates/admin' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "accounts": [
    {
      "id": "affiliate_example",
      "name": "Example Travel Guide",
      "description": "Independent guides to remarkable stays.",
      "region": "San Diego County",
      "website": "https://example.com/",
      "imageUrl": "/api/web-assets/affilate-profile-pics/affiliate_example/card.jpg",
      "active": true,
      "createdAt": "2027-01-10T09:00:00-08:00",
      "terms": {
        "id": "affiliate_example",
        "commissionBps": 75
      }
    }
  ],
  "nextCursor": null
}
Response JSON schema

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Set platform-managed account activity; commission is fixed.

Body fields

uidstringRequired

Affiliate account UID, 1–128 characters.

commissionBpsintegerOptional

Optional compatibility field. Only 75 is accepted; it cannot configure the fixed 0.75% rate.

activebooleanRequired

Platform suspension/reactivation control.

Response fields

accountobjectRequired

Updated affiliate profile.

account.idstringRequired

Affiliate account UID, derived from the authenticated account.

account.namestringRequired

Affiliate display name.

account.websitestringRequired

HTTPS affiliate website or social profile URL.

account.activebooleanRequired

Whether the platform permits affiliate activity. Self-service cannot reactivate a suspended account.

account.createdAtstringRequired

Account creation time. ISO 8601 instant; format displayed times in the relevant property timezone. format: date-time

account.imageUrlstring | nullOptional

Affiliate card image path under /api/web-assets/affilate-profile-pics/{uid}/, separate from user profile photos. Null means no image.

account.descriptionstring | nullOptional

Affiliate card description, plain text; null when absent. maxLength: 500

account.regionstring | nullOptional

Affiliate card region, plain text; null when absent. maxLength: 120

termsobjectRequired

Updated commission terms.

terms.idstringRequired

Affiliate account UID.

terms.commissionBps75Required

Fixed 75 basis points (0.75%) of accommodation after discounts only; excludes add-ons, fees and taxes.

Error responses

401
Authentication is missing or invalid.
403
Wrong credential kind, unverified email, disabled account, or missing required role/scope.
422
Invalid parameters/body. Response contains error and details[] with field and message.
503
Provider failure. Retry without interpreting it as missing inventory or zero earnings.
404
Affiliate account does not exist (PUT).

Behavior & constraints

  • Platform administration only. Changes account activity, never commission terms. Historical attribution stays stored; reporting uses the fixed 0.75% policy.
Request
cURL
curl -X PUT 'https://api-preview.wikiup.app/api/affiliates/admin' \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Content-Type: application/json' --data '{"uid":"affiliate_example","active":true}'
Response · 200
JSON
{
  "account": {
    "id": "affiliate_example",
    "name": "Example Travel Guide",
    "description": "Independent guides to remarkable stays.",
    "region": "San Diego County",
    "website": "https://example.com/",
    "imageUrl": "/api/web-assets/affilate-profile-pics/affiliate_example/card.jpg",
    "active": true,
    "createdAt": "2027-01-10T09:00:00-08:00"
  },
  "terms": {
    "id": "affiliate_example",
    "commissionBps": 75
  }
}
Response JSON schema

Synthetic example, not live account data. Null, omitted fields and empty collections retain the meanings in the field reference.

Browse available listing partners.

Query parameters

pageintegerOptional

One-based page, 1–1000; default 1.

pageSizeintegerOptional

1–50 entries; default 12.

Response fields

partnersArray<object>Required

Current page of records; empty when no matches.

partners[]objectRequired

Active affiliate available for an owner request.

partners[].idstringRequired

Affiliate account ID; send as affiliateId when requesting.

partners[].namestringRequired

Partner display name.

partners[].websitestringRequired

Partner website or social profile HTTPS URL.

partners[].imageUrlstring | nullOptional

Affiliate card image under /api/web-assets/affilate-profile-pics/{uid}/, or null when absent.

partners[].descriptionstring | nullOptional

Affiliate card description, plain text; null when absent. maxLength: 500

partners[].regionstring | nullOptional

Affiliate card region, plain text; null when absent. maxLength: 120

metaobjectRequired

Paging metadata.

meta.pageintegerRequired

Current one-based page. minimum: 1

meta.pageSizeintegerRequired

Requested page size; defaults to 12, maximum 50. minimum: 1; maximum: 50

meta.nextPageinteger | nullRequired

Next page, or null when no further records remain.

Error responses

401
Missing or invalid sign-in.
403
API key, unverified session, inactive affiliate or non-owner.
404
Request does not exist or belongs to another affiliate.
409
Conflicting decision, concurrent modification or inactive inventory.
422
Invalid input; error and details[] describe rejected fields.
429
At most five new requests to the same partner per property in 24 hours.
503
Provider failure; retry, do not interpret as an empty directory.

Behavior & constraints

  • Private, no-store. Approval is required for every existing and new affiliate listing; suspension and active inventory checks still apply.
  • Request and decision are persisted before notification. Mail failures are queued; API success does not establish inbox delivery.
Request
cURL
curl --fail-with-body 'https://api-preview.wikiup.app/api/listing-partners' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "partners": [
    {
      "id": "affiliate_example",
      "name": "Example Travel Guide",
      "description": "Independent guides to remarkable stays.",
      "region": "San Diego County",
      "website": "https://partner.example.com",
      "imageUrl": "/api/web-assets/affilate-profile-pics/affiliate_example/card.jpg"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 12,
    "nextPage": null
  }
}
Response JSON schema

Synthetic example showing the field contract, not live property data.

Track this property’s listing requests and denial reasons.

Path parameters

idstringRequired

Raw property ID; current owner access required.

Query parameters

pageintegerOptional

One-based page, 1–1000; default 1.

pageSizeintegerOptional

1–50 entries; default 12.

Response fields

requestsArray<object>Required

Current page of records; empty when no matches.

requests[]objectRequired

A property request addressed to one affiliate. Private notification and ownership data are excluded.

requests[].idstringRequired

Stable request ID.

requests[].propertyIdstringRequired

Raw property ID.

requests[].propertyNamestringRequired

Current public property name.

requests[].affiliateIdstringRequired

Intended affiliate account ID.

requests[].affiliateNamestringRequired

Current affiliate display name.

requests[].affiliateWebsitestring | nullRequired

Affiliate website or null if unavailable.

requests[].status"pending" | "approved" | "denied" | "owner_suspended" | "affiliate_suspended" | "both_suspended" | "withdrawn" | "removed"Required

Single listing lifecycle state. Only approved can appear publicly; neither party can clear the other’s suspension.

requests[].reasonstring | nullRequired

Trimmed denial reason (1–2000 characters); null unless denied.

requests[].submittedAtstringRequired

Submission time in the property timezone, including numeric offset. format: date-time

requests[].decidedAtstring | nullRequired

Approval/denial time in the property timezone, or null if not decided. Suspension/removal preserves this value. format: date-time

requests[].timeZonestringRequired

Property IANA timezone, e.g. America/Los_Angeles.

metaobjectRequired

Paging metadata.

meta.pageintegerRequired

Current one-based page. minimum: 1

meta.pageSizeintegerRequired

Requested page size; defaults to 12, maximum 50. minimum: 1; maximum: 50

meta.nextPageinteger | nullRequired

Next page, or null when no further records remain.

Error responses

401
Missing or invalid sign-in.
403
API key, unverified session, inactive affiliate or non-owner.
404
Request does not exist or belongs to another affiliate.
409
Conflicting decision, concurrent modification or inactive inventory.
422
Invalid input; error and details[] describe rejected fields.
429
At most five new requests to the same partner per property in 24 hours.
503
Provider failure; retry, do not interpret as an empty directory.

Behavior & constraints

  • Private, no-store. Approval is required for every existing and new affiliate listing; suspension and active inventory checks still apply.
  • Request and decision are persisted before notification. Mail failures are queued; API success does not establish inbox delivery.
Request
cURL
curl --fail-with-body 'https://api-preview.wikiup.app/api/properties/property_example/listing-requests' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "requests": [
    {
      "id": "request_example",
      "propertyId": "property_example",
      "propertyName": "Example Hotel",
      "affiliateId": "affiliate_example",
      "affiliateName": "Example Travel Guide",
      "affiliateWebsite": "https://partner.example.com",
      "status": "pending",
      "reason": null,
      "submittedAt": "2027-01-10T09:00:00-08:00",
      "decidedAt": null,
      "timeZone": "America/Los_Angeles"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 12,
    "nextPage": null
  }
}
Response JSON schema

Synthetic example showing the field contract, not live property data.

Request a listing on a partner website.

Path parameters

idstringRequired

Raw property ID; current owner access required.

Body fields

affiliateIdstringRequired

Active partner ID from GET /api/listing-partners. No other body fields allowed.

Response fields

requestobjectRequired

Saved request.

request.idstringRequired

Stable request ID.

request.propertyIdstringRequired

Raw property ID.

request.propertyNamestringRequired

Current public property name.

request.affiliateIdstringRequired

Intended affiliate account ID.

request.affiliateNamestringRequired

Current affiliate display name.

request.affiliateWebsitestring | nullRequired

Affiliate website or null if unavailable.

request.status"pending" | "approved" | "denied" | "owner_suspended" | "affiliate_suspended" | "both_suspended" | "withdrawn" | "removed"Required

Single listing lifecycle state. Only approved can appear publicly; neither party can clear the other’s suspension.

request.reasonstring | nullRequired

Trimmed denial reason (1–2000 characters); null unless denied.

request.submittedAtstringRequired

Submission time in the property timezone, including numeric offset. format: date-time

request.decidedAtstring | nullRequired

Approval/denial time in the property timezone, or null if not decided. Suspension/removal preserves this value. format: date-time

request.timeZonestringRequired

Property IANA timezone, e.g. America/Los_Angeles.

Error responses

401
Missing or invalid sign-in.
403
API key, unverified session, inactive affiliate or non-owner.
404
Request does not exist or belongs to another affiliate.
409
Conflicting decision, concurrent modification or inactive inventory.
422
Invalid input; error and details[] describe rejected fields.
429
At most five new requests to the same partner per property in 24 hours.
503
Provider failure; retry, do not interpret as an empty directory.

Behavior & constraints

  • Returns 201 for a new request; 200 and the existing request for repeated pending/already approved submissions. After denial a new request is allowed; history is retained.
  • Submission queues an owner receipt and affiliate review email from no-reply@wikiup.app.
Request
cURL
curl --fail-with-body --request POST 'https://api-preview.wikiup.app/api/properties/property_example/listing-requests' \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Content-Type: application/json' --data '{"affiliateId":"affiliate_example"}'
Response · 201
JSON
{
  "request": {
    "id": "request_example",
    "propertyId": "property_example",
    "propertyName": "Example Hotel",
    "affiliateId": "affiliate_example",
    "affiliateName": "Example Travel Guide",
    "affiliateWebsite": "https://partner.example.com",
    "status": "pending",
    "reason": null,
    "submittedAt": "2027-01-10T09:00:00-08:00",
    "decidedAt": null,
    "timeZone": "America/Los_Angeles"
  }
}
Response JSON schema

Synthetic example showing the field contract, not live property data.

Suspend, resume, withdraw or remove this property's partner listing.

Path parameters

idstringRequired

Raw property ID; current owner access required.

requestIdstringRequired

Request ID returned by submission/list routes; intended affiliate only.

Body fields

statusstringRequired

Target status under the owner transitions in listing-partner-lifecycle.md. No boolean fields.

Response fields

requestobjectRequired

Saved request.

request.idstringRequired

Stable request ID.

request.propertyIdstringRequired

Raw property ID.

request.propertyNamestringRequired

Current public property name.

request.affiliateIdstringRequired

Intended affiliate account ID.

request.affiliateNamestringRequired

Current affiliate display name.

request.affiliateWebsitestring | nullRequired

Affiliate website or null if unavailable.

request.status"pending" | "approved" | "denied" | "owner_suspended" | "affiliate_suspended" | "both_suspended" | "withdrawn" | "removed"Required

Single listing lifecycle state. Only approved can appear publicly; neither party can clear the other’s suspension.

request.reasonstring | nullRequired

Trimmed denial reason (1–2000 characters); null unless denied.

request.submittedAtstringRequired

Submission time in the property timezone, including numeric offset. format: date-time

request.decidedAtstring | nullRequired

Approval/denial time in the property timezone, or null if not decided. Suspension/removal preserves this value. format: date-time

request.timeZonestringRequired

Property IANA timezone, e.g. America/Los_Angeles.

Error responses

401
Missing or invalid sign-in.
403
API key, unverified session, inactive affiliate or non-owner.
404
Request does not exist or belongs to another affiliate.
409
Conflicting decision, concurrent modification or inactive inventory.
422
Invalid input; error and details[] describe rejected fields.
429
At most five new requests to the same partner per property in 24 hours.
503
Provider failure; retry, do not interpret as an empty directory.

Behavior & constraints

  • Private, no-store. Approval is required for every existing and new affiliate listing; suspension and active inventory checks still apply.
  • Request and decision are persisted before notification. Mail failures are queued; API success does not establish inbox delivery.
Request
cURL
curl --fail-with-body --request PATCH 'https://api-preview.wikiup.app/api/properties/property_example/listing-requests/request_example' \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Content-Type: application/json' --data '{"status":"owner_suspended"}'
Response · 200
JSON
{
  "request": {
    "id": "request_example",
    "propertyId": "property_example",
    "propertyName": "Example Hotel",
    "affiliateId": "affiliate_example",
    "affiliateName": "Example Travel Guide",
    "affiliateWebsite": "https://partner.example.com",
    "status": "owner_suspended",
    "reason": null,
    "submittedAt": "2027-01-10T09:00:00-08:00",
    "decidedAt": "2027-01-10T10:15:00-08:00",
    "timeZone": "America/Los_Angeles"
  }
}
Response JSON schema

Synthetic example showing the field contract, not live property data.

Read requests addressed to your affiliate account.

Query parameters

pageintegerOptional

One-based page, 1–1000; default 1.

pageSizeintegerOptional

1–50 entries; default 12.

statusstringOptional

pending, approved, denied, owner_suspended, affiliate_suspended, both_suspended, withdrawn or removed; omit for all. Newest submissions first.

Response fields

requestsArray<object>Required

Current page of records; empty when no matches.

requests[]objectRequired

A property request addressed to one affiliate. Private notification and ownership data are excluded.

requests[].idstringRequired

Stable request ID.

requests[].propertyIdstringRequired

Raw property ID.

requests[].propertyNamestringRequired

Current public property name.

requests[].affiliateIdstringRequired

Intended affiliate account ID.

requests[].affiliateNamestringRequired

Current affiliate display name.

requests[].affiliateWebsitestring | nullRequired

Affiliate website or null if unavailable.

requests[].status"pending" | "approved" | "denied" | "owner_suspended" | "affiliate_suspended" | "both_suspended" | "withdrawn" | "removed"Required

Single listing lifecycle state. Only approved can appear publicly; neither party can clear the other’s suspension.

requests[].reasonstring | nullRequired

Trimmed denial reason (1–2000 characters); null unless denied.

requests[].submittedAtstringRequired

Submission time in the property timezone, including numeric offset. format: date-time

requests[].decidedAtstring | nullRequired

Approval/denial time in the property timezone, or null if not decided. Suspension/removal preserves this value. format: date-time

requests[].timeZonestringRequired

Property IANA timezone, e.g. America/Los_Angeles.

metaobjectRequired

Paging metadata.

meta.pageintegerRequired

Current one-based page. minimum: 1

meta.pageSizeintegerRequired

Requested page size; defaults to 12, maximum 50. minimum: 1; maximum: 50

meta.nextPageinteger | nullRequired

Next page, or null when no further records remain.

Error responses

401
Missing or invalid sign-in.
403
API key, unverified session, inactive affiliate or non-owner.
404
Request does not exist or belongs to another affiliate.
409
Conflicting decision, concurrent modification or inactive inventory.
422
Invalid input; error and details[] describe rejected fields.
429
At most five new requests to the same partner per property in 24 hours.
503
Provider failure; retry, do not interpret as an empty directory.

Behavior & constraints

  • Private, no-store. Approval is required for every existing and new affiliate listing; suspension and active inventory checks still apply.
  • Request and decision are persisted before notification. Mail failures are queued; API success does not establish inbox delivery.
Request
cURL
curl --fail-with-body 'https://api-preview.wikiup.app/api/affiliates/listing-requests' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "requests": [
    {
      "id": "request_example",
      "propertyId": "property_example",
      "propertyName": "Example Hotel",
      "affiliateId": "affiliate_example",
      "affiliateName": "Example Travel Guide",
      "affiliateWebsite": "https://partner.example.com",
      "status": "pending",
      "reason": null,
      "submittedAt": "2027-01-10T09:00:00-08:00",
      "decidedAt": null,
      "timeZone": "America/Los_Angeles"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 12,
    "nextPage": null
  }
}
Response JSON schema

Synthetic example showing the field contract, not live property data.

Review the requesting property’s public details.

Path parameters

requestIdstringRequired

Request ID returned by submission/list routes; intended affiliate only.

Response fields

requestobjectRequired

Request addressed to you.

request.idstringRequired

Stable request ID.

request.propertyIdstringRequired

Raw property ID.

request.propertyNamestringRequired

Current public property name.

request.affiliateIdstringRequired

Intended affiliate account ID.

request.affiliateNamestringRequired

Current affiliate display name.

request.affiliateWebsitestring | nullRequired

Affiliate website or null if unavailable.

request.status"pending" | "approved" | "denied" | "owner_suspended" | "affiliate_suspended" | "both_suspended" | "withdrawn" | "removed"Required

Single listing lifecycle state. Only approved can appear publicly; neither party can clear the other’s suspension.

request.reasonstring | nullRequired

Trimmed denial reason (1–2000 characters); null unless denied.

request.submittedAtstringRequired

Submission time in the property timezone, including numeric offset. format: date-time

request.decidedAtstring | nullRequired

Approval/denial time in the property timezone, or null if not decided. Suspension/removal preserves this value. format: date-time

request.timeZonestringRequired

Property IANA timezone, e.g. America/Los_Angeles.

propertyobjectRequired

Requesting property public details.

property.propertyIdstringRequired

Raw Wikiup property identifier.

property.namestringRequired

Public display name.

property.descriptionstring | nullRequired

Full saved description for the exact listing; may contain HTML. Null when unknown. The catalog uses a bounded plain-text excerpt instead.

property.stayType"hotel" | "inn" | "bed_and_breakfast" | "resort" | "vacation_rental" | nullRequired

Owner-supplied subtype compatible with the existing broad type; null when unknown or inconsistent. Does not select the booking flow.

property.tagLinestring | nullRequired

Explicit owner-provided hotel facts or beds/baths from the exact rental unit or room-type content. Not live available inventory. Unknown is null. Limited to 100 Unicode characters including an ellipsis when shortened. maxLength: 100

property.addressobject | nullRequired

Saved property address, not owner-account address. Null when all address fields are empty. Detail only.

property.address.line1string | nullRequired

Saved property street address.

property.address.line2string | nullRequired

Optional additional property address line; null when empty.

property.address.citystring | nullRequired

Saved property city.

property.address.statestring | nullRequired

Saved property state/province.

property.address.postalCodestring | nullRequired

Saved property postal/ZIP code; a string to preserve leading zeros.

property.address.countrystring | nullRequired

Saved country value; may be a country name or code. Do not assume ISO format.

property.contactobjectRequired

Property business contact details. No account records or credentials are included.

property.contact.phonestring | nullRequired

Property business phone text, not an owner-account phone; null when absent.

property.contact.emailstring | nullRequired

Property business email, not an owner-account email; null when absent.

property.contact.websiteUrlstring | nullRequired

Saved HTTP(S) property website, or null for absent/invalid/credential-bearing values. Not an affiliate-attributed checkout URL.

property.mapLocationobject | nullRequired

Exact approved public coordinate pair, or null. Never use town-center guesses.

property.mapLocation.latitudenumberRequired

Exact approved public latitude in decimal degrees. minimum: -90; maximum: 90

property.mapLocation.longitudenumberRequired

Exact approved public longitude in decimal degrees. minimum: -180; maximum: 180

property.timeZonestring | nullRequired

Validated property IANA time zone. Use for local timestamps; null means unknown.

property.coverImageobject | nullRequired

Public cover image metadata, or null when absent.

property.coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

property.coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

property.coverImage.altstringRequired

Image alternative text for accessible presentation.

property.coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

property.coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

property.coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

property.coverImage.variants[]objectRequired

Response structure: ImageVariant.

property.coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

property.coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

property.coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

property.coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

property.coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

property.coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

property.coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

property.galleryArray<object>Required

Ordered public listing photos, including thumbnails and group labels.

property.gallery[]objectRequired

Response structure: PublicImage.

property.gallery[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

property.gallery[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

property.gallery[].altstringRequired

Image alternative text for accessible presentation.

property.gallery[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

property.gallery[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

property.gallery[].variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

property.gallery[].variants[]objectRequired

Response structure: ImageVariant.

property.gallery[].variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

property.gallery[].variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

property.gallery[].variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

property.gallery[].variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

property.gallery[].groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

property.gallery[].group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

property.gallery[].group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

Error responses

401
Missing or invalid sign-in.
403
API key, unverified session, inactive affiliate or non-owner.
404
Request does not exist or belongs to another affiliate.
409
Conflicting decision, concurrent modification or inactive inventory.
422
Invalid input; error and details[] describe rejected fields.
429
At most five new requests to the same partner per property in 24 hours.
503
Provider failure; retry, do not interpret as an empty directory.

Behavior & constraints

  • Private, no-store. Approval is required for every existing and new affiliate listing; suspension and active inventory checks still apply.
  • Request and decision are persisted before notification. Mail failures are queued; API success does not establish inbox delivery.
Request
cURL
curl --fail-with-body 'https://api-preview.wikiup.app/api/affiliates/listing-requests/request_example' \
  -H 'Authorization: Bearer <session-token>'
Response · 200
JSON
{
  "request": {
    "id": "request_example",
    "propertyId": "property_example",
    "propertyName": "Example Hotel",
    "affiliateId": "affiliate_example",
    "affiliateName": "Example Travel Guide",
    "affiliateWebsite": "https://partner.example.com",
    "status": "pending",
    "reason": null,
    "submittedAt": "2027-01-10T09:00:00-08:00",
    "decidedAt": null,
    "timeZone": "America/Los_Angeles"
  },
  "property": {
    "propertyId": "property_example",
    "name": "Example Hotel",
    "description": "A small mountain hotel with a courtyard.",
    "stayType": "inn",
    "tagLine": "Mountain stays with a courtyard",
    "address": {
      "line1": "100 Example Lane",
      "line2": null,
      "city": "Julian",
      "state": "CA",
      "postalCode": "92036",
      "country": "United States"
    },
    "contact": {
      "phone": "+1 555 010 0100",
      "email": "host@example.com",
      "websiteUrl": "https://hotel.example.com/"
    },
    "mapLocation": null,
    "timeZone": "America/Los_Angeles",
    "coverImage": {
      "id": "photo_example",
      "url": "https://api-preview.wikiup.app/api/web-assets/properties/property_example/gallery/courtyard.jpg",
      "alt": "Example hotel courtyard",
      "width": 1600,
      "height": 900,
      "variants": [],
      "group": null
    },
    "gallery": [
      {
        "id": "photo_example",
        "url": "https://api-preview.wikiup.app/api/web-assets/properties/property_example/gallery/courtyard.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [],
        "group": null
      }
    ]
  }
}
Response JSON schema

Synthetic example showing the field contract, not live property data.

Approve, deny, suspend, resume or remove a property listing.

Path parameters

requestIdstringRequired

Request ID returned by submission/list routes; intended affiliate only.

Body fields

statusstringRequired

Target lifecycle status. See listing-partner-lifecycle.md for role-specific transitions.

reasonstringOptional

Required for denied, trimmed 1–2000 characters. Must be omitted for every other status.

Response fields

requestobjectRequired

Saved request.

request.idstringRequired

Stable request ID.

request.propertyIdstringRequired

Raw property ID.

request.propertyNamestringRequired

Current public property name.

request.affiliateIdstringRequired

Intended affiliate account ID.

request.affiliateNamestringRequired

Current affiliate display name.

request.affiliateWebsitestring | nullRequired

Affiliate website or null if unavailable.

request.status"pending" | "approved" | "denied" | "owner_suspended" | "affiliate_suspended" | "both_suspended" | "withdrawn" | "removed"Required

Single listing lifecycle state. Only approved can appear publicly; neither party can clear the other’s suspension.

request.reasonstring | nullRequired

Trimmed denial reason (1–2000 characters); null unless denied.

request.submittedAtstringRequired

Submission time in the property timezone, including numeric offset. format: date-time

request.decidedAtstring | nullRequired

Approval/denial time in the property timezone, or null if not decided. Suspension/removal preserves this value. format: date-time

request.timeZonestringRequired

Property IANA timezone, e.g. America/Los_Angeles.

Error responses

401
Missing or invalid sign-in.
403
API key, unverified session, inactive affiliate or non-owner.
404
Request does not exist or belongs to another affiliate.
409
Conflicting decision, concurrent modification or inactive inventory.
422
Invalid input; error and details[] describe rejected fields.
429
At most five new requests to the same partner per property in 24 hours.
503
Provider failure; retry, do not interpret as an empty directory.

Behavior & constraints

  • Approve with {"status":"approved"}. Deny with status and reason. Repeating the same decision/reason is safe; a different decision returns 409.
  • A decision queues the requesting owner’s email. Approved properties become eligible for this affiliate only. Suspension and removal use the same status field and suppress obsolete pending notices.
Request
cURL
curl --fail-with-body --request PATCH 'https://api-preview.wikiup.app/api/affiliates/listing-requests/request_example' \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Content-Type: application/json' --data '{"status":"denied","reason":"Outside our coverage area."}'
Response · 200
JSON
{
  "request": {
    "id": "request_example",
    "propertyId": "property_example",
    "propertyName": "Example Hotel",
    "affiliateId": "affiliate_example",
    "affiliateName": "Example Travel Guide",
    "affiliateWebsite": "https://partner.example.com",
    "status": "denied",
    "reason": "Outside our coverage area.",
    "submittedAt": "2027-01-10T09:00:00-08:00",
    "decidedAt": "2027-01-10T10:15:00-08:00",
    "timeZone": "America/Los_Angeles"
  }
}
Response JSON schema

Synthetic example showing the field contract, not live property data.

API Reference

Authentication & Users

Checks whether an email already belongs to a Wikiup account during registration. This checks account existence; it does not verify ownership of the inbox.

Console registration details and native iOS onboarding.

Body fields

emailstringRequired

Email address to look up.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/verify-email' \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com"}'
Example response
JSON
{
  "exists": false
}

Starts the console registration flow by emailing a verification code and returning a registrationId. Keep that ID with its matching code for the verification step.

Body fields

emailstringRequired

Valid recipient email.

Behavior & constraints

  • Codes contain 10 letters/digits and expire after 30 minutes. Send registrationId, email, and code to POST /api/verify-registration-code. Rate limits: one request per email per 60 seconds, 5 per email per hour, and 20 per IP per hour. A new request creates a separate challenge ID.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/send-registration-code' \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com"}'
Example response
JSON
{
  "message": "success",
  "registrationId": "b5f2a9f1-93c8-4a78-a96b-8dff15e92c14",
  "expiresAt": "2026-10-22T12:30:00.000Z"
}

Checks the emailed registration code and exchanges it for a one-time registrationToken. The console passes that proof to POST /api/register when creating the account.

Body fields

registrationIdstring · UUIDRequired

Challenge ID returned by POST /api/send-registration-code.

emailstringRequired

Address used to request the code.

codestringRequired

10-character emailed code; surrounding whitespace and letter case are ignored.

Behavior & constraints

  • Invalid or expired proof returns 400; a consumed or unavailable challenge returns 409. At most five incorrect code attempts are allowed; exhausted attempts return 429. Successful verification consumes the code and issues proof valid until the original challenge expiration. Keep this proof private.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/verify-registration-code' \
  -H 'Content-Type: application/json' \
  -d '{"registrationId":"b5f2a9f1-93c8-4a78-a96b-8dff15e92c14","email":"owner@example.com","code":"AB23CD45EF"}'
Example response
JSON
{
  "message": "success",
  "registrationToken": "<one-time-registration-proof>",
  "expiresAt": "2026-10-22T12:30:00.000Z"
}

Creates a Wikiup account using the one-time registrationToken from the console email-verification step, name, email, password, and optional photo. Returns a bootstrap credential for the Wikiup sign-in flow.

Body fields

registrationTokenstringRequired

One-time proof from POST /api/verify-registration-code, bound to this email and the challenge expiration.

emailstringRequired

Verified email not already registered; must match the registration proof.

givenNamestringRequired

First name, 1–100 characters after trimming, used in the profile display name.

familyNamestringRequired

Last name, 1–100 characters after trimming, used in the profile display name.

confirmedPasswordstringRequired

Chosen password, 12–256 characters. The wire field is confirmedPassword, not password.

profileImageUrlstringOptional

Absolute image URL or relative image path; relative paths resolve against the request origin.

Response fields

tokenstring

Bootstrap sign-in credential. Complete the Wikiup client sign-in flow to obtain an access token before calling protected endpoints.

Behavior & constraints

  • Invalid inputs or registration proof return 400; an existing account or consumed registration returns 409. The response keys are userId and token. If setup reports REGISTRATION_RECOVERY_REQUIRED, use console sign-in/password reset rather than replaying proof.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/register' \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com","givenName":"Alex","familyName":"Morgan","confirmedPassword":"<chosen-password>","registrationToken":"<one-time-registration-proof>"}'
Response · 201
JSON
{
  "userId": "user_123",
  "token": "<bootstrap-credential>"
}

Sends a password-reset link for an existing, active account. The link contains the reset code used by the password update screen.

Body fields

emailstringRequired

Registered email address.

Behavior & constraints

  • Reset codes expire after one hour. A missing or disabled account returns 400; email delivery failure returns 500.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/send-password-reset-email' \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com"}'
Example response
JSON
{
  "message": "success"
}

Changes a password using either a signed-in Wikiup access token or the resetCode from a password-reset email.

Request headers

AuthorizationstringOptional

Bearer <access-token> for a signed-in password change. A nonempty Bearer token takes precedence over resetCode.

Body fields

passwordstringRequired

New password.

resetCodestringOptional

Required when no Authorization header is supplied. Consumed after a successful reset.

Behavior & constraints

  • An invalid bearer token returns 401 rather than falling back to the reset code. Expired or invalid reset codes return 400.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/update-password' \
  -H 'Content-Type: application/json' \
  -d '{"password":"<new-password>","resetCode":"<code-from-email>"}'
Example response
JSON
{
  "message": "success"
}

Loads the signed-in user's current profile, including contact phone, profile photo, and email verification state. This endpoint does not list other users.

Console account settings and the iOS authenticated profile refresh.

Query parameters

mestringRequired

Required literal query value; omitting it returns 400.

Allowed valuestrue
Request
cURL
curl 'https://api.wikiup.app/api/users?me=true' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "uid": "user_123",
  "email": "owner@example.com",
  "emailVerified": true,
  "displayName": "Alex Morgan",
  "photoURL": "",
  "phoneNumber": "",
  "disabled": false
}

Updates the signed-in user's display name, profile photo, or contact phone and returns the saved profile. Omitted fields retain their current value.

Path parameters

uidstringRequired

The signed-in user's uid. Editing another user's profile is forbidden (403).

Body fields

displayNamestringOptional

Profile display name.

photoURLstringOptional

Image URL or /api/web-assets/ path. Send an empty string to clear the photo.

phoneNumberstringOptional

Supply a complete international phone number; stored in E.164 format. Empty string clears the contact number.

Behavior & constraints

  • Email, password, and disabled state are not updated by this endpoint. Use /api/update-password for password changes.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/users/user_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"Alex Morgan","phoneNumber":"+18585550123"}'
Example response
JSON
{
  "uid": "user_123",
  "email": "owner@example.com",
  "emailVerified": true,
  "displayName": "Alex Morgan",
  "photoURL": "",
  "phoneNumber": "+18585550123",
  "disabled": false
}

Checks whether property ownership allows the current user to delete their account. The account settings screen calls this before asking for deletion confirmation.

Behavior & constraints

  • Returns 409 with code OWNERSHIP_TRANSFER_REQUIRED if the account is the sole owner of a property. Add another owner or finish deleting that property first. This preflight does not delete data; the DELETE endpoint checks eligibility again.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/users/me/deletion-status' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "canDelete": true
}

Deletes the current account after ownership and recent-authentication checks. Removes the user's push registrations, contact profile, owned profile assets, and property memberships.

Path parameters

uidstringRequired

The signed-in user's uid. Editing another user's profile is forbidden (403).

Behavior & constraints

  • Requires authentication within the last five minutes. Sign in again on 401 REAUTHENTICATION_REQUIRED. Sole ownership blocks deletion with 409 OWNERSHIP_TRANSFER_REQUIRED; pending property deletion also blocks completion.
  • A 503 DELETION_RETRY_REQUIRED means deletion could not be confirmed. Retry using the authenticated deletion flow. No JSON body is required.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/users/user_123' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "status": "deleted"
}

Registers or refreshes an iOS device's push delivery token for the signed-in user. Called by the native app when notification authorization or the device token changes.

Body fields

fcmTokenstringRequired

Opaque push delivery token; nonblank, at most 4,096 characters. Use this exact wire field name.

platformstringRequired

Supported platform.

Allowed valuesios
apnsTokenstring | nullOptional

Optional Apple push token, at most 4,096 characters.

appBundleIdstring | nullOptional

Application bundle identifier, at most 255 characters.

appVersionstring | nullOptional

Client version, at most 100 characters.

Request
cURL
curl -X PUT 'https://api.wikiup.app/api/users/me/push-token' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"fcmToken":"<device-push-token>","platform":"ios","appVersion":"1.0"}'
Example response
JSON
{
  "id": "device_123",
  "uid": "user_123",
  "fcmToken": "<device-push-token>",
  "apnsToken": null,
  "platform": "ios",
  "updatedAt": "2026-10-22T12:00:00Z"
}

Unregisters a device's push token for the current user, such as during native app sign-out. Other registered devices are unaffected.

Body fields

fcmTokenstringRequired

Device token to remove; nonblank, at most 4,096 characters.

Behavior & constraints

  • This DELETE requires a JSON body. Success is 204 with no response body.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/users/me/push-token' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"fcmToken":"<device-push-token>"}'
Response · 204
HTTP
No response body.

Starts programmatic account registration by emailing a verification code to an address owned by the registering person. Returns a challenge ID and expiration, not an authenticated account.

First step for an external integration or AI-assisted setup without a pre-existing console session.

Body fields

emailstringRequired

Valid email, at most 254 characters. Surrounding whitespace is trimmed and the address is normalized to lowercase.

Response fields

registrationIdstring · UUID

Challenge ID to send with the emailed code to the confirmation endpoint.

expiresAtstring · date-time

Challenge expires 30 minutes after creation; ISO 8601 UTC.

Behavior & constraints

  • Registration is for a new account. A verified code does not sign in to, adopt, or issue credentials for an existing account; use the console's sign-in or password-reset flow to recover access.
  • Registration responses use Cache-Control: no-store. Errors use {error:{code,message}}; respect Retry-After when a 429 response includes it.
  • The code contains 10 letters/digits and is delivered only by email. An assistant must wait for the human to supply it; an email account password is never needed.
  • Requests have a 60-second per-email cooldown, a limit of 5 per email per hour, and 20 per client IP per hour. Each successful request returns a new registrationId; pair the code with its matching ID.
  • 202 means the verification email was submitted for delivery. No account, property, or API key exists yet.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/accounts/registration' \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com"}'
Response · 202
JSON
{
  "registrationId": "b5f2a9f1-93c8-4a78-a96b-8dff15e92c14",
  "expiresAt": "2026-10-22T12:30:00.000Z"
}

Verifies inbox ownership, creates a new Wikiup account, and returns its first API key. The code is consumed and the complete key is returned only in this response.

Completes programmatic onboarding. Use apiKey.key as the Bearer credential for GET /api/properties.

Body fields

registrationIdstring · UUIDRequired

ID returned by POST /api/accounts/registration.

codestringRequired

10-character emailed code; surrounding whitespace and letter case are ignored.

givenNamestringRequired

First name, 1–100 characters after trimming; control characters are rejected.

familyNamestringRequired

Last name, 1–100 characters after trimming; control characters are rejected.

passwordstringOptional

Optional console password, 12–256 characters. If omitted, set a password later through the console password-reset flow.

Response fields

userIdstring

New account identifier.

emailstring

Verified, normalized account email.

apiKeyobject

Issued key named Account setup, with access: read_write, propertyIds: null, and a 90-day expiration. Contains the same metadata as POST /api/api-keys plus key.

apiKey.keystring

Full Bearer credential: wk_<32 lowercase hex ID>.<64 lowercase hex secret>. Capture directly into a secret store; it cannot be retrieved again.

Behavior & constraints

  • Registration is for a new account. A verified code does not sign in to, adopt, or issue credentials for an existing account; use the console's sign-in or password-reset flow to recover access.
  • Registration responses use Cache-Control: no-store. Errors use {error:{code,message}}; respect Retry-After when a 429 response includes it.
  • At most five incorrect code attempts are permitted per challenge. Invalid/expired proof returns 400; exhausted attempts return 429. Already-used or processing registration and an existing account return 409.
  • If setup cannot finish after account creation has started, the API returns REGISTRATION_RECOVERY_REQUIRED (503). Do not replay the code to retrieve a key; recover through console sign-in/password reset, then issue a new key with that session.
  • This endpoint returns an API key, not an interactive session token. No property is created automatically. List properties, then create one when needed.
  • The example key is deliberately redacted. Capture a real response privately; never echo its apiKey.key into a chat or build log.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/accounts/registration/confirm' \
  -H 'Content-Type: application/json' \
  -d '{"registrationId":"b5f2a9f1-93c8-4a78-a96b-8dff15e92c14","code":"AB23CD45EF","givenName":"Alex","familyName":"Morgan"}' --output /path/to/private/registration.json
Response · 201
JSON
{
  "userId": "user_123",
  "email": "owner@example.com",
  "apiKey": {
    "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "name": "Account setup",
    "prefix": "wk_a1b2c3d4",
    "access": "read_write",
    "propertyIds": null,
    "createdAt": "2026-10-22T12:00:00.000Z",
    "expiresAt": "2027-01-20T12:00:00.000Z",
    "revokedAt": null,
    "key": "wk_<32-character-id>.<64-character-secret>"
  }
}

Lists API key metadata for the authenticated account, newest first. Includes expired and revoked keys so an integration can track its credential history.

Request headers

AuthorizationstringRequired

Bearer <session-access-token>. An interactive account session is required; API keys cannot list or issue keys.

Response fields

apiKeysobject[]

All account keys as metadata: id, name, prefix, access, propertyIds, createdAt, expiresAt, revokedAt. Raw keys and secret hashes are never included.

Behavior & constraints

  • Use an interactive account session. API keys cannot list, create, or manage other keys, regardless of their access level or property scope.
  • Read/write keys retain the owner’s current property permissions. Travel availability keys are restricted to public regional search and explicitly published inventory; they cannot access other property APIs. Disabling the verified account removes access.
  • Keep credentials in a server-side secret store. Never embed them in hosted-widget URLs, frontend JavaScript, screenshots, logs, or source control.
Request
cURL
curl 'https://api.wikiup.app/api/api-keys' \
  -H 'Authorization: Bearer <session-access-token>'
Example response
JSON
{
  "apiKeys": [
    {
      "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "name": "Account setup",
      "prefix": "wk_a1b2c3d4",
      "access": "read_write",
      "propertyIds": null,
      "createdAt": "2026-10-22T12:00:00.000Z",
      "expiresAt": "2027-01-20T12:00:00.000Z",
      "revokedAt": null
    }
  ]
}

Issues a named API key for a server-side integration, with an access level, optional property allowlist, and expiration. Returns the raw key once alongside its metadata.

Request headers

AuthorizationstringRequired

Bearer <session-access-token> from an interactive sign-in completed within the past five minutes. Refreshing a token alone does not renew the sign-in time.

Body fields

namestringRequired

Integration label, 1–80 characters after trimming.

accessstringOptional

Defaults to read_only. read_write permits supported mutations under current property permissions. travel_availability permits only GET /api/travel/availability over published listings. affiliate searches all active Wikiup inventory across owners without owner opt-in, applies the account blacklist and signed booking attribution; it requires affiliate enrollment and propertyIds:null.

Allowed valuesread_onlyread_writetravel_availabilityaffiliate
propertyIdsstring[] | nullOptional

Defaults to null (current memberships for read/write keys; all published listings for travel keys). Supply 1–100 property IDs to restrict access; each must be 1–128 trimmed characters and belong to the account. Empty arrays are invalid; duplicate IDs are removed.

expiresInDaysintegerOptional

1–365; defaults to 90. Expiration is measured from the issuance time.

Response fields

idstring

Key identifier: 32 lowercase hexadecimal characters. Use this ID, not the secret, when revoking.

namestring

Human-readable label for the integration.

prefixstring

Non-secret display prefix, wk_ followed by the first eight characters of the key ID.

accessstring

Read-only or read/write ceiling; the account's current property permissions still apply.

Allowed valuesread_onlyread_writetravel_availabilityaffiliate
propertyIdsstring[] | null

Allowed properties. For read_only/read_write, null permits current memberships only. For travel_availability, null permits all explicitly published travel listings; selected IDs narrow that scope.

createdAtstring · date-time

Issuance time in ISO 8601 UTC.

expiresAtstring · date-time

Expiration time in ISO 8601 UTC. Requests fail after this instant.

revokedAtstring · date-time | null

Revocation time, or null when not revoked. A non-revoked key may still be expired.

keystring

Full Bearer credential, returned only on issuance. Wikiup stores a hash, not a retrievable copy of the secret.

Behavior & constraints

  • Use an interactive account session. API keys cannot list, create, or manage other keys, regardless of their access level or property scope.
  • Read/write keys retain the owner’s current property permissions. Travel availability keys are restricted to public regional search and explicitly published inventory; they cannot access other property APIs. Disabling the verified account removes access.
  • Keep credentials in a server-side secret store. Never embed them in hosted-widget URLs, frontend JavaScript, screenshots, logs, or source control.
  • Issuance requires an interactive sign-in within the past five minutes. An older or missing sign-in time returns 401 with {error, code: REAUTHENTICATION_REQUIRED}. Reauthenticate through the sign-in method, then retry with the renewed session. Console’s API keys page presents the reauthentication dialog automatically.
  • This recent-sign-in requirement applies to POST only. Listing keys and session-authorized revocation require a valid account session, without the five-minute requirement.
  • At most 25 unexpired, non-revoked keys may be active per account; exceeding the limit returns 409. Invalid options or unknown body fields return 422 with field-specific details.
  • read_only keys cannot request guest-portal access, payment links, confirmation emails, or guest-portal reply email addresses through their reservation GET endpoints, because these operations create credentials or trigger delivery. Those operations require read_write.
  • API keys do not authorize account/profile/password operations, connected mailbox messages, Google email connect/disconnect, property deletion, membership departure, team/invitation management, or invitation acceptance. Those operations require an interactive session.
  • Rotate by creating a replacement, storing it securely, verifying access, and then revoking the previous key. The response is the issued object directly, not an apiKey wrapper.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/api-keys' \
  -H 'Authorization: Bearer <session-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Reporting integration","access":"read_only","propertyIds":["prop_123"],"expiresInDays":90}' --output /path/to/private/integration-key.json
Response · 201
JSON
{
  "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Reporting integration",
  "prefix": "wk_a1b2c3d4",
  "access": "read_only",
  "propertyIds": [
    "prop_123"
  ],
  "createdAt": "2026-10-22T12:00:00.000Z",
  "expiresAt": "2027-01-20T12:00:00.000Z",
  "revokedAt": null,
  "key": "wk_<32-character-id>.<64-character-secret>"
}

Revokes one API key belonging to the authenticated account. Future requests using it are rejected; the metadata remains available for the account's credential history.

Path parameters

idstringRequired

32-character key ID from its metadata. Unknown, malformed, or another account's ID returns 404.

Request headers

AuthorizationstringRequired

Bearer session token to revoke an account key. Any valid API key may revoke itself only, regardless of its access level or property scope.

Behavior & constraints

  • No request body. Success returns 204 with no JSON payload.
  • Revoking an already-revoked key succeeds when authorized with an interactive account session. A revoked key cannot authenticate a second request to revoke itself.
  • Any API key may only revoke its own ID; attempting to revoke another key returns 403.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/api-keys/a1b2c3d4e5f60718293a4b5c6d7e8f90' \
  -H 'Authorization: Bearer <session-access-token>'
Response · 204
Empty response
204 No Content

API Reference

Availability

Find rooms that fit the requested guest count and do not overlap an existing stay or blockout. Optional pricing includes a server-calculated stay snapshot, so staff can compare rooms for a booking or room change.

Staff reservation and guest management API.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

checkInstringRequired

Arrival date, YYYY-MM-DD.

checkOutstringRequired

Exclusive departure date, YYYY-MM-DD.

guestsintegerRequired

Required guest count.

includeUnavailablestringOptional

Include occupied rooms with isAvailable:false.

Allowed values1trueyeson
includePricingstringOptional

Include stayPricing totals and breakdown.

Allowed values1trueyeson
reservationIdstringOptional

Ignore this existing reservation when checking its proposed new dates.

Response fields

[].isAvailablebooleanOptional

Whether the room has no conflicting stay for these dates.

Behavior & constraints

  • This staff endpoint requires reservations.view. Hosted public availability widgets use the widget rendering flow, not anonymous access to this endpoint.
  • The current route filters capacity and overlap but does not filter room status; public consumers should only offer Active rooms.
Request
cURL
curl 'https://api.wikiup.app/api/availability?checkIn=2027-06-10&checkOut=2027-06-12&guests=2&includePricing=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
[
  {
    "id": "room_123",
    "name": "Garden room",
    "status": "Active",
    "isAvailable": true,
    "pricing": {
      "basePrice": 150
    }
  }
]

Check whether a single room can accommodate a change to an existing reservation's dates, excluding that reservation from overlap conflicts.

Staff reservation and guest management API.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

roomIdstringRequired

Target room.

reservationIdstringRequired

Reservation to exclude from collisions.

checkInstringRequired

Arrival date YYYY-MM-DD.

checkOutstringRequired

Departure date YYYY-MM-DD.

Behavior & constraints

  • Missing roomId, reservationId or either date returns 422. This route does not evaluate guest capacity or price.
Request
cURL
curl 'https://api.wikiup.app/api/availability/check-room?roomId=room_123&reservationId=reservation_123&checkIn=2027-06-10&checkOut=2027-06-12' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "isAvailable": true
}

API Reference

Booking Checkout

Start public booking checkout using server-calculated room rates, taxes, extras, discount and gift-card contributions. Availability is checked before creating the payment authorization; this call does not guarantee or create the final reservation.

Hosted booking/add-ons/payment widgets embedded on the public booking page and external sites.

Body fields

petsintegerOptional

Pet count, 0–100; defaults to zero. Must not exceed the room maxPets limit when configured (0–5); legacy pet-friendly rooms without a numeric limit retain their existing behavior. The saved room pet fee is calculated by the server and persisted as an add-on; do not send a pet-fee add-on ID or amount.

propertyIdstringRequired

Property accepting this booking.

roomIdstringOptional

Active physical room ID; send exactly one roomId or roomTypeId.

roomTypeIdstringOptional

Active pooled classification in this property, instead of roomId. Confirmation retries match the booked classification, not the provisional physical room.

checkInstringRequired

Arrival date, YYYY-MM-DD, in the property's time zone.

checkOutstringRequired

Exclusive departure date, YYYY-MM-DD.

guestsintegerOptional

Guest count; capacity and availability are checked again when confirming.

guestFirstNamestringOptional

Guest given name. Prefer separate first/last names.

guestLastNamestringOptional

Guest family name.

guestNamestringOptional

Full name alternative for older clients.

guestEmailstringRequired

Guest contact email; required by the booking contact check.

guestPhonestringRequired

Guest phone number; required by the booking contact check.

addOnsobject[]Optional

Selections as {id, qty}; prices are loaded on the server. Reserved arrival/departure IDs are wikiup:early-check-in and wikiup:late-check-out with quantity 1.

discountCodestringOptional

Optional lodging discount code.

giftCardsobject[]Optional

Gift cards as {number, amount}; maximum 10 cards. Amounts are major currency units.

giftCardNumberstringOptional

Legacy single-card alternative; omit when using giftCards.

giftCardAmountnumberOptional

Requested single gift-card application in major currency units.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Response fields

requiresPaymentbooleanOptional

false when discounts/gift cards cover the amount; still call confirm to book.

paymentSessionSecretstring | nullOptional

Stripe client secret for the payment UI. Keep private.

remainingDuenumberOptional

Amount in major currency units: 15 means $15.00 for USD.

Behavior & constraints

  • Returns 200 when no card payment is required, otherwise 201. Never submit a client-calculated price as authoritative.
  • Complete Stripe authorization, then send the identical selection plus paymentReferenceId to /api/widget-bookings/confirm. Availability and selection are checked again at confirmation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/widget-bookings/payment-intent' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","roomId":"room_123","checkIn":"2027-06-10","checkOut":"2027-06-12","guests":2,"guestFirstName":"Alex","guestLastName":"Morgan","guestEmail":"alex@example.com","guestPhone":"+15555550123","addOns":[{"id":"wikiup:early-check-in","qty":1}]}'
Response · 201
JSON
{
  "requiresPayment": true,
  "paymentSessionSecret": "pi_example_secret_example",
  "paymentIntentId": "pi_example",
  "totalDue": 315,
  "appliedDiscountAmount": 0,
  "appliedDiscountCode": null,
  "appliedGiftCardAmount": 0,
  "remainingDue": 315,
  "giftCardBalance": null,
  "giftCardRemainingBalance": null,
  "currency": "usd"
}

Finalize a public booking after payment authorization. Rechecks availability and payment selection, captures eligible payment, creates the reservation and ledger, redeems gift cards, sends booking emails and returns a guest portal access URL.

Hosted PaymentWidget completion and public host's payment-success redirect.

Body fields

petsintegerOptional

Pet count, 0–100; defaults to zero. Must not exceed the room maxPets limit when configured (0–5); legacy pet-friendly rooms without a numeric limit retain their existing behavior. The saved room pet fee is calculated by the server and persisted as an add-on; do not send a pet-fee add-on ID or amount.

propertyIdstringRequired

Property accepting this booking.

roomIdstringOptional

Active physical room ID; send exactly one roomId or roomTypeId.

roomTypeIdstringOptional

Active pooled classification in this property, instead of roomId. Confirmation retries match the booked classification, not the provisional physical room.

checkInstringRequired

Arrival date, YYYY-MM-DD, in the property's time zone.

checkOutstringRequired

Exclusive departure date, YYYY-MM-DD.

guestsintegerOptional

Guest count; capacity and availability are checked again when confirming.

guestFirstNamestringOptional

Guest given name. Prefer separate first/last names.

guestLastNamestringOptional

Guest family name.

guestNamestringOptional

Full name alternative for older clients.

guestEmailstringRequired

Guest contact email; required by the booking contact check.

guestPhonestringRequired

Guest phone number; required by the booking contact check.

addOnsobject[]Optional

Selections as {id, qty}; prices are loaded on the server. Reserved arrival/departure IDs are wikiup:early-check-in and wikiup:late-check-out with quantity 1.

discountCodestringOptional

Optional lodging discount code.

giftCardsobject[]Optional

Gift cards as {number, amount}; maximum 10 cards. Amounts are major currency units.

giftCardNumberstringOptional

Legacy single-card alternative; omit when using giftCards.

giftCardAmountnumberOptional

Requested single gift-card application in major currency units.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive
paymentReferenceIdstringOptional

PaymentIntent ID from payment-intent, after client-side authorization; required if a card amount remains.

notesstringOptional

Guest booking notes.

devicestringOptional

Source device, default browser_desktop.

Allowed valuesbrowser_desktopbrowser_ipadbrowser_mobilebrowser_console

Response fields

paymentStatusstringOptional

Payment completion state. processing represents an asynchronous bank payment, not settled funds.

Allowed valuessucceededprocessing
emailSentboolean | nullOptional

True only after recorded provider acceptance. Tracked pending/failed/uncertain delivery is false; historical-unverified or unreadable receipts are null. Acceptance does not prove inbox delivery. Replays resume only durable pending notices and never blindly resend an accepted/uncertain email.

guestPortalAccessUrlstring | nullOptional

Signed guest access URL; redirect here only after successful booking confirmation.

Behavior & constraints

  • Existing completed bookings can return 200 instead of 201. Preserve the original payment reference when retrying a completion; do not create a second payment intent merely because a response was delayed.
  • If the room becomes unavailable before completion, the flow attempts to cancel or refund the payment rather than silently booking an overlapping stay.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/widget-bookings/confirm' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","roomId":"room_123","checkIn":"2027-06-10","checkOut":"2027-06-12","guests":2,"guestFirstName":"Alex","guestLastName":"Morgan","guestEmail":"alex@example.com","guestPhone":"+15555550123","addOns":[{"id":"wikiup:early-check-in","qty":1}],"paymentReferenceId":"pi_example","device":"browser_mobile"}'
Response · 201
JSON
{
  "reservationId": "reservation_123",
  "confirmationNumber": "WUR-EXAMPLE",
  "paymentStatus": "succeeded",
  "emailSent": true,
  "guestPortalAccessUrl": "https://www.example-inn.com/guest?token=ACCESS_GRANT",
  "giftCardRedemption": null
}

Prepare payment of an existing reservation through its signed payment link. Recalculate balance, optional additional extras, lodging discount and gift-card contributions before presenting the payment UI.

Hosted payment widget in the reservation payment-link flow.

Body fields

paymentLinkTokenstringRequired

Signed token obtained from the reservation payment link; this authorizes the request.

addOnsobject[]Optional

Selections as {id, qty}; prices are loaded on the server. Reserved arrival/departure IDs are wikiup:early-check-in and wikiup:late-check-out with quantity 1.

discountCodestringOptional

Optional lodging discount code.

giftCardsobject[]Optional

Gift cards as {number, amount}; maximum 10 cards. Amounts are major currency units.

giftCardNumberstringOptional

Legacy single-card alternative; omit when using giftCards.

giftCardAmountnumberOptional

Requested single gift-card application in major currency units.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Behavior & constraints

  • No innkeeper bearer token is required; keep paymentLinkToken private. Send the same extras, discount and gift cards in both steps.
  • Money is in major currency units. Intent creation returns 200 with requiresPayment:false when fully covered; call confirm to complete the ledger update anyway.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservation-payments/payment-intent' \
  -H 'Content-Type: application/json' \
  -d '{"paymentLinkToken":"PAYMENT_LINK_TOKEN"}'
Response · 201
JSON
{
  "requiresPayment": true,
  "paymentSessionSecret": "pi_example_secret_example",
  "paymentIntentId": "pi_example",
  "balanceDue": 300,
  "remainingDue": 300,
  "currency": "usd"
}

Finalize a payment-link checkout after authorization, record payment and selected extras, apply discounts/gift cards, update arrival/departure preferences and send guest/inn payment receipts.

Hosted payment widget in the reservation payment-link flow.

Body fields

paymentLinkTokenstringRequired

Signed token obtained from the reservation payment link; this authorizes the request.

addOnsobject[]Optional

Selections as {id, qty}; prices are loaded on the server. Reserved arrival/departure IDs are wikiup:early-check-in and wikiup:late-check-out with quantity 1.

discountCodestringOptional

Optional lodging discount code.

giftCardsobject[]Optional

Gift cards as {number, amount}; maximum 10 cards. Amounts are major currency units.

giftCardNumberstringOptional

Legacy single-card alternative; omit when using giftCards.

giftCardAmountnumberOptional

Requested single gift-card application in major currency units.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive
paymentReferenceIdstringOptional

PaymentIntent ID from payment-intent; required when a card amount remains.

Behavior & constraints

  • No innkeeper bearer token is required; keep paymentLinkToken private. Send the same extras, discount and gift cards in both steps.
  • Money is in major currency units. Intent creation returns 200 with requiresPayment:false when fully covered; call confirm to complete the ledger update anyway.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservation-payments/confirm' \
  -H 'Content-Type: application/json' \
  -d '{"paymentLinkToken":"PAYMENT_LINK_TOKEN","paymentReferenceId":"pi_example"}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "confirmationNumber": "WUR-EXAMPLE",
  "paymentStatus": "succeeded",
  "giftCardRedemption": null,
  "balanceDue": 0,
  "remainingDue": 0,
  "totalPaid": 300,
  "guestPaymentEmailSent": true,
  "innPaymentEmailSent": true
}

API Reference

Channel management

Save all edited listing mappings, pricing and rule policies in one idempotent request.

Body fields

requestIdstringRequired

UUID retained across retries of the identical request.

connectionIdstringRequired

Wikiup connection ID.

reviewIdstringOptional

Previously verified price-publication review, when available.

changesarrayRequired

1–100 unique room/listing changes. Each contains exactly one roomId or roomTypeId, plus externalListingId, plus optional new-mapping settings, priceAdjustment, automaticPriceSync and replacement bookingRuleOverrides.

Behavior & constraints

  • Owner and property.manage required. Omitted settings are unchanged. All edits remain local until this PUT. No base-rate publication is performed by this endpoint.
  • Validate the complete local request before mutations. Durable per-step progress permits identical retries; provider APIs are not transactional, so partial/uncertain outcomes retain their journals.
  • Automatic price sync is saved as requested intent, then authorized only against verified channel prices. A pending price review does not cause a checkbox-click mutation or reject the saved request. Publication still requires explicit approval.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/properties/{id}/channel-management/mappings' \
  -H 'Authorization: Bearer <owner-api-key>' \
  -H 'Content-Type: application/json' --data '{"requestId":"11111111-1111-4111-8111-111111111111","connectionId":"connection-id","changes":[{"roomId":"room-id","externalListingId":"listing-id","automaticPriceSync":true,"priceAdjustment":{"type":"percentage","value":20}}]}'
Example response
JSON
{
  "status": "saved",
  "requestId": "11111111-1111-4111-8111-111111111111",
  "automaticPriceSync": [
    {
      "externalListingId": "listing-id",
      "status": "pending_review"
    }
  ]
}

Read the import channel catalog/prices or resume an owned property import.

Behavior & constraints

  • Preview only. Without sessionId returns catalog and plans. With sessionId returns owner-bound import state and reviewed source data. Provisional properties remain hidden until completion.
Request
cURL
curl 'https://api-preview.wikiup.app/api/channel-management/property-import' \
  -H 'Authorization: Bearer <owner-api-key>'
Example response
JSON
{
  "catalog": [],
  "plans": {
    "hotel": {
      "monthlyPriceUsd": 15
    },
    "rental": {
      "monthlyPriceUsd": 10
    }
  }
}

Import a new hotel or rental through start, save_details, import_room, finish and cancel commands.

Commands

startCreate/resume an owner-bound provisional property import.

Success response: HTTP 200

Requires owner-reviewed terms and an unrestricted creation-capable owner credential. Reuse requestId and the same plan/code to resume. Connect and preview listing content using the returned property ID.

start request body
JSON
{
  "action": "start",
  "requestId": "<new UUID>",
  "plan": "rental",
  "code": "<available catalog code>",
  "accepted": true,
  "termsVersion": "<current plans.rental.version>",
  "timeZone": "America/Los_Angeles"
}
start response
JSON
{
  "sessionId": "<session-id>",
  "propertyId": "<provisional-property-id>",
  "status": "draft"
}
save_detailsSave reviewed property identity and the complete selected room list.

Success response: HTTP 200

details requires name, description, email, phone, websiteUrl, timeZone and full address including line2. listingTitle is optional. country is a two-letter code.

Choose 1–20 rooms; rental scope supports one bookable listing. Each room needs the import receipt and source listing IDs, internal name, description, capacity and nightlyRate; listingTitle/rateId are optional.

save_details request body
JSON
{
  "action": "save_details",
  "sessionId": "<session-id>",
  "details": {
    "name": "Internal property",
    "listingTitle": "Guest-facing property",
    "description": "<reviewed description>",
    "email": "owner@example.invalid",
    "phone": "<owner contact phone>",
    "websiteUrl": "",
    "timeZone": "America/Los_Angeles",
    "address": {
      "line1": "<reviewed address>",
      "line2": "",
      "city": "<city>",
      "state": "<state>",
      "postalCode": "<postal code>",
      "country": "US"
    }
  },
  "rooms": [
    {
      "externalListingId": "<listing-id>",
      "importId": "<preview-import-id>",
      "name": "Internal unit",
      "listingTitle": "Guest-facing unit",
      "description": "<reviewed description>",
      "capacity": 2,
      "nightlyRate": 137,
      "rateId": "<selected rate ID if required>"
    }
  ]
}
save_details response
JSON
{
  "ok": true
}
import_roomImport/resume one reviewed room and its media.

Success response: HTTP 200

Use the receipt from preview_import for this exact connection/listing. Repeat the same scoped operation while copying_photos; ready is the completion state. No payments or guest emails are created.

import_room request body
JSON
{
  "action": "import_room",
  "sessionId": "<session-id>",
  "connectionId": "<connection-id>",
  "room": {
    "externalListingId": "<listing-id>",
    "importId": "<preview-import-id>",
    "name": "Internal unit",
    "listingTitle": "Guest-facing unit",
    "description": "<reviewed description>",
    "capacity": 2,
    "nightlyRate": 137,
    "rateId": "<selected rate ID if required>"
  }
}
import_room response
JSON
{
  "roomId": "<room-id>",
  "status": "ready",
  "photosCopied": 0,
  "totalPhotos": 0
}
finishFinish the provisional import and return the visible property membership.

Success response: HTTP 200

Activates in the closed-sales setup flow and reconciles reservations. This does not authorize publishing availability; explicit review/approval is separate. Response membership contains the normal access context; this example shows selected fields.

finish request body
JSON
{
  "action": "finish",
  "sessionId": "<session-id>",
  "connectionId": "<connection-id>"
}
finish response
JSON
{
  "propertyId": "<property-id>",
  "membership": {
    "propertyId": "<property-id>",
    "role": "Owner"
  }
}
cancelDiscard an unfinished owned import through guarded teardown.

Success response: HTTP 200

Confirm destructive intent. Uncertain connection removal or upstream operations require reconciliation. This is not a bulk reset or a live-property deletion substitute.

cancel request body
JSON
{
  "action": "cancel",
  "sessionId": "<session-id>"
}
cancel response
JSON
{
  "ok": true
}

Behavior & constraints

  • Requires an unrestricted owner read/write API key or owner session. Start requires accepted:true, current termsVersion and a client requestId UUID; retries reuse the same provisional property. Connect/listings/preview_import use the returned propertyId and existing channel endpoints. Save reviewed details and rooms, import each room until ready, then finish to activate with sales closed and reconcile reservations. Finish does not publish availability. Full JSON contracts and recovery steps: /channel-management-api.md.
Request
cURL
curl 'https://api-preview.wikiup.app/api/channel-management/property-import' \
  -H 'Authorization: Bearer <owner-api-key>' \
  -H 'Content-Type: application/json' --data-raw '{"action":"start","requestId":"<client UUID>","plan":"hotel","code":"BookingCom","accepted":true,"termsVersion":"channel-management-hotel-2026-11-08-v2","timeZone":"America/Los_Angeles"}'
Example response
JSON
{
  "sessionId": "import-id",
  "propertyId": "import-id",
  "status": "draft"
}

Read the property channel workspace and verified channel catalog.

Path parameters

idstringRequired

Wikiup property ID.

Behavior & constraints

  • Requires property.manage. Connections, mapping progress, import coverage, reservation issues and activity are persisted. Recovery issues include optional details with a plain-language title, explanation, recovery action, support reference, recorded stage/times/attempt count, connected channels, outstanding counts and receipt-backed affected dates. Older records may lack precise cause evidence; never infer a provider outage from a generic issue. Opening the console alert only opens the existing sync workflow; executing sync can apply updates. Disabled properties load without requesting a provider catalog; enabled properties retain workspace data and return catalogError when catalog loading fails. Production catalogs include only explicitly enabled channels; unknown and unvalidated channels are hidden. Distribution mutations remain preview-only; request_channel is available in both environments.
  • Preview entries and connections are marked simulated:true and use a sample account/listings, with normal owner-bound callback handling. Preview simulates all catalog channels with sample authorization and listings; production retains real authorization. Catalog entries marked verification_required cannot be connected. An active connection does not imply that sales are open or OTA delivery is confirmed.
  • plans.hotel and plans.rental return both current pricing choices before enablement. Select the plan, display its terms and submit that exact terms version after explicit owner acceptance. Responses are not cached. See /channel-management-api.md for the complete console-independent workflow.
Request
cURL
curl 'https://api-preview.wikiup.app/api/properties/<property-id>/channel-management' \
  -H 'Authorization: Bearer <owner-api-key>'
Example response
JSON
{
  "workspace": {
    "propertyId": "property-id",
    "enabled": false,
    "connections": [],
    "issues": []
  },
  "catalog": [],
  "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
    }
  }
}

Enable sandbox distribution, authorize channels, map rooms or review imports.

Path parameters

idstringRequired

Wikiup property ID.

Body fields

actionstringRequired

Operation to perform.

Allowed valuesprice_adjustmentverify_price_adjustmentinventory_reviewinventory_publishinventory_verifyinventory_evidenceenable_rate_syncdisable_rate_syncminimum_staybooking_rules_reviewbooking_rule_overridesverify_publicationenable_availability_syncenableconnectcompletecancel_authorizationlistingsmapactivatepauseresumeremovesyncreviewapprovepreview_importimportpublishrequest_channel
planstringOptional

enable: hotel or rental.

acceptedbooleanOptional

enable: true only after the owner accepts the displayed pricing.

termsVersionstringOptional

enable: current plans[plan].version from GET.

codestringOptional

connect: exact code from the returned catalog.

settingsobjectOptional

connect/map: descriptor-defined credential or mapping fields. Preview Vrbo requires its documented sample credentials and sign-in code.

redirectUrlstringOptional

connect: optional HTTPS callback belonging to your application. Preview also accepts HTTP loopback.

tokenstringOptional

complete/cancel_authorization: exact sensitive token returned by connect or your callback. Never log it.

channelIdstringOptional

complete: echoed authorization channel ID, not a Wikiup connectionId.

connectionIdstringOptional

listings, map, booking_rules_review, minimum_stay, activate, pause, remove and preview_import: Wikiup connection ID returned by connect or complete.

externalListingIdstringOptional

map/preview_import: listing ID from listings for this connection.

roomIdstringOptional

map: Wikiup room ID belonging to the property.

reviewIdstringOptional

Persisted publication review ID for approve/publish, verify_publication and enable_availability_sync. Return values from current review/verification must be used.

priceAdjustmentobject | nullOptional

Optional on map; required on price_adjustment. {type: percentage | fixed, value: number}. Percentage 0–1000; fixed 0–100000 in listing currency per night. At most two decimals. null explicitly removes the mapping rate increase; omitted on map preserves upstream behavior.

overridesobjectOptional

booking_rule_overrides: replacement per-listing policy. Omitted keys use room defaults. minimumStay, maximumStay, advanceNoticeHours, preparationDays, bookingWindowDays; same-day cutoff cannot be overridden per listing.

minimumStayinteger | nullOptional

minimum_stay: 1–365 nights, or null to use the room floor. Existing stricter channel rules are preserved.

importIdstringOptional

import: ID returned by preview_import.

capacitynumberOptional

import: whole-number maximum guests, 1–100.

nightlyRatenumberOptional

import: positive nightly price in USD, at most 100000.

reviewedbooleanOptional

activate/import/approve/publish: true after the applicable owner review.

testListingAcknowledgedbooleanOptional

activate: true for the controlled preview connection.

namestringOptional

request_channel: requested channel name.

notesstringOptional

request_channel: optional request context.

reservationsOnlybooleanOptional

sync: skip full restrictions/listing-settings synchronization, but still check/send automatic availability. Not a read-only flag. Use isolated sandbox verify for ingestion-only testing.

Commands

price_adjustmentConfigure one existing room/channel nightly-price adjustment.

Success response: HTTP 200

Owner read/write key or owner session, property.manage and exact saved mapping required. Fixed amount: {type:"fixed",value:30} adds 30 listing-currency units per night. null removes the rate adjustment.

Updates only the existing native mapping price modifier. No remapping, disconnection, source-price publication or booking-rule reset. Configuration readback does not prove downstream price delivery. Unknown outcomes require verification, not blind retries.

price_adjustment request body
JSON
{
  "action": "price_adjustment",
  "connectionId": "<connection-id>",
  "roomId": "<room-id>",
  "externalListingId": "<listing-id>",
  "priceAdjustment": {
    "type": "percentage",
    "value": 20
  }
}
price_adjustment response
JSON
{
  "status": "configured",
  "priceAdjustment": {
    "type": "percentage",
    "value": 20
  },
  "delivery": "pending"
}
verify_price_adjustmentVerify native adjustment and available downstream nightly prices.

Success response: HTTP 200

No provider writes. Can settle a lost configuration response locally. Uses actual source rates and channel calendar readback where supported; configured/unverified is returned when downstream readback is unavailable.

verify_price_adjustment request body
JSON
{
  "action": "verify_price_adjustment",
  "connectionId": "<connection-id>",
  "roomId": "<room-id>",
  "externalListingId": "<listing-id>"
}
verify_price_adjustment response
JSON
{
  "status": "verified",
  "priceAdjustment": {
    "type": "percentage",
    "value": 20
  },
  "mismatches": 0,
  "checkedAt": "<ISO timestamp>"
}
inventory_reviewReview full inventory for an isolated property.

Success response: HTTP 200

Preview only; checks local connections and upstream zero-channel scope. Saves an expiring proposal from normal room prices, rules and occupancy. No provider writes.

inventory_review request body
JSON
{
  "action": "inventory_review"
}
inventory_review response
JSON
{
  "id": "<review-id>",
  "days": 500,
  "rooms": 1,
  "availabilityCells": 500,
  "rateCells": 500
}
inventory_publishPublish the explicitly reviewed full inventory.

Success response: HTTP 200

Rechecks isolation, current state and review fingerprint. Sends one combined rates/restrictions request and one availability request. Task acceptance is pending until authoritative provider readback. Unknown outcomes are not blindly replayed.

inventory_publish request body
JSON
{
  "action": "inventory_publish",
  "reviewId": "<review-id>",
  "reviewed": true
}
inventory_publish response
JSON
{
  "status": "pending"
}
inventory_verifyVerify/recover authorized managed inventory.

Success response: HTTP 200

Pulls booking revisions before inventory recovery; can send definite rejected/retryable steps and subsequent saved deltas. Never a general read-only endpoint.

inventory_verify request body
JSON
{
  "action": "inventory_verify"
}
inventory_verify response
JSON
{
  "status": "verified"
}
inventory_evidenceRead sanitized latest delivery receipts.

Success response: HTTP 200

No credentials or guest records. Includes per-step status, receipts and UTC update time; provider verification is not a claim of downstream OTA enforcement.

inventory_evidence request body
JSON
{
  "action": "inventory_evidence"
}
inventory_evidence response
JSON
{
  "status": "pending",
  "taskIds": [
    "<task-id>"
  ],
  "steps": []
}
enable_rate_syncOpt a listing/channel mapping into price-only deltas after verified owner publication.

Success response: HTTP 200

Rechecks current Airbnb price state and requires an existing published, verified baseline. Does not send restrictions or availability. Existing live properties are never opted in by deployment. Specify roomId and externalListingId together to scope consent to one mapping. Omit both only for the legacy whole-channel command. Shared source rates are rejected; sibling listings remain unchanged.

enable_rate_sync request body
JSON
{
  "action": "enable_rate_sync",
  "connectionId": "<connection-id>",
  "roomId": "<room-id>",
  "externalListingId": "<listing-id>",
  "reviewId": "<verified-publication-review-id>",
  "reviewed": true
}
enable_rate_sync response
JSON
{
  "status": "enabled",
  "scope": "price-only"
}
enableAccept the currently reviewed terms and enable property channel management.

Success response: HTTP 200

Owner must review terms and the room-count estimate first. The API recomputes the estimate and stores it with consent; a mismatch is rejected. Creates/reuses provider property mapping and webhook. The latest term version comes from GET; do not hardcode it.

enable request body
JSON
{
  "action": "enable",
  "plan": "hotel",
  "termsVersion": "<plans.hotel.version from GET>",
  "accepted": true,
  "roomCount": 8,
  "estimatedMonthlyPriceUsd": 18
}
enable response
JSON
{
  "enabled": true,
  "billing": "accepted"
}
connectStart channel authorization using the current catalog entry.

Success response: HTTP 200

Required settings depend on the catalog. Treat returned token/URL as sensitive; expire/cancel abandoned authorizations. Real authorization can reach real listings even in preview.

connect request body
JSON
{
  "action": "connect",
  "code": "<catalog code>",
  "redirectUrl": "https://your-app.example/channel-return"
}
connect response
JSON
{
  "status": "authorization_required",
  "url": "<owner-bound-authorization-url>"
}
completeComplete an owner-bound channel authorization.

Success response: HTTP 200

Use values from the authorization flow, not a room or listing ID. POST /api/channel-management/authorization is the callback orchestration endpoint.

complete request body
JSON
{
  "action": "complete",
  "token": "<sensitive token>",
  "channelId": "<authorization channelId>"
}
complete response
JSON
{
  "connectionId": "<connection-id>"
}
cancel_authorizationCancel an uncompleted authorization without creating a connection.

Success response: HTTP 200

Only the initiating owner may cancel its current authorization session.

cancel_authorization request body
JSON
{
  "action": "cancel_authorization",
  "token": "<sensitive token>"
}
cancel_authorization response
JSON
{
  "ok": true
}
listingsRead authorized listings and their applicable mapping fields.

Success response: HTTP 200

Select listing/rate identifiers from this response. Do not invent or reuse IDs from another connection.

automaticPriceSync is the saved toggle intent. automaticPriceSyncStatus is enabled only when that mapping has active managed-price authorization; pending_review requires explicit publication review and needs_attention requires reconciliation. A checked toggle alone does not prove active delivery.

listings request body
JSON
{
  "action": "listings",
  "connectionId": "<connection-id>"
}
listings response
JSON
{
  "listings": [],
  "mappingFields": []
}
mapMap one channel listing/rate to exactly one Wikiup room or classification.

Success response: HTTP 200

Use exactly one roomId or roomTypeId. A pooled classification provisions one provider room type with its sellable member count. A physical member cannot be independently mapped to another inventory bucket. Pooled absolute availability requires authoritative readback; unsupported live channel calendars stay pending review.

Optional priceAdjustment applies per room/channel during setup. Omit it to preserve upstream defaults; null explicitly means no rate adjustment. Field names and options come from listings.mappingFields. Review ownership and source identity before saving. Returns ok:true after saving the mapping; reload the workspace for current mappings.

map request body
JSON
{
  "action": "map",
  "connectionId": "<connection-id>",
  "roomId": "<room-id>",
  "externalListingId": "<listing-id>",
  "settings": {
    "<required mapping field>": "<selected value>"
  },
  "priceAdjustment": {
    "type": "percentage",
    "value": 20
  }
}
map response
JSON
{
  "ok": true
}
booking_rules_reviewRead room/current/effective rules for saved mappings without publication.

Success response: HTTP 200

Each review includes room identity, property timezone, checkedAt, coverage, status and six rule rows, plus ruleSettings (room defaults, overrides, editability, stayOverridesSupported and synchronization status). Optional settings rows provide read-only Wikiup/channel values for capacity, pet policy/fees, availability, pricing coverage and local-only metadata. Each has setting, wikiup, channel and status (verified means observed match; enabled means configured sync, not verified delivery; disabled, review_required, unavailable and wikiup_only remain distinct). Opening a review never publishes these settings. Unavailable/unsupported values must remain visible, not be represented as defaults.

booking_rules_review request body
JSON
{
  "action": "booking_rules_review",
  "connectionId": "<connection-id>"
}
booking_rules_review response
JSON
{
  "reviews": []
}
booking_rule_overridesSave per-listing/channel booking rules; omitted keys follow future room defaults.

Success response: HTTP 200

Replacement object, not a patch: send overrides:{} to return all supported rules to room defaults. Supported keys: minimumStay (1–365), maximumStay (1–1125), advanceNoticeHours (0–24,48,72,168), preparationDays (0–2), bookingWindowDays (30–365 in 30-day increments, plus 365).

Owner/property.manage required. Minimum cannot be below room floor; maximum must be at least effective minimum. Airbnb only; per-listing same-day cutoff is rejected because its provider scope is property-wide. Shared-source stay-limit overrides are rejected.

Save is explicit consent to replace supported base values for this mapping; initial setup still preserves preexisting restrictions. Pending/uncertain previous sends must settle before a different policy. Queued is saved for activation; pending is not verification.

booking_rule_overrides request body
JSON
{
  "action": "booking_rule_overrides",
  "connectionId": "<connection-id>",
  "roomId": "<room-id>",
  "externalListingId": "<listing-id>",
  "overrides": {
    "minimumStay": 3,
    "advanceNoticeHours": 48
  }
}
booking_rule_overrides response
JSON
{
  "status": "pending"
}
minimum_staySet a channel minimum without weakening the room floor.

Success response: HTTP 200

Integer 1–365, or null to use the room rule. Existing stricter channel baselines remain protected. Active channels may return pending/verified/needs_attention; queued is not delivery proof.

minimum_stay request body
JSON
{
  "action": "minimum_stay",
  "connectionId": "<connection-id>",
  "minimumStay": 3
}
minimum_stay response
JSON
{
  "status": "queued"
}
activateActivate a reviewed connection and reconcile its cutover state.

Success response: HTTP 200

Requires saved mappings and reviewed rules. This can change upstream state; it is not a read or a certification prerequisite for Booking CRS.

activate request body
JSON
{
  "action": "activate",
  "connectionId": "<connection-id>",
  "reviewed": true,
  "testListingAcknowledged": true
}
activate response
JSON
{
  "ok": true
}
pauseClose this property’s Airbnb availability without pausing the shared account.

Success response: HTTP 200

Airbnb creates an open-ended property/channel close-out. Pending calendar verification is not paused. Retry Pause to verify; never deactivate the shared host. Other channels retain exclusive-account deactivation. Do not test against live listings.

pause request body
JSON
{
  "action": "pause",
  "connectionId": "<connection-id>"
}
pause response
JSON
{
  "ok": true
}
resumeRemove only Wikiup’s own property-specific Airbnb close-out.

Success response: HTTP 200

Explicit owner confirmation required. Does not write availability values, prices or booking rules. Configuration removal is verified; downstream calendar availability is not claimed as verified.

resume request body
JSON
{
  "action": "resume",
  "connectionId": "<connection-id>",
  "reviewed": true
}
resume response
JSON
{
  "ok": true
}
removeRemove a channel connection through guarded teardown.

Success response: HTTP 200

Destructive upstream operation. Confirm scope and intent; uncertain teardown requires reconciliation rather than repeating blindly.

remove request body
JSON
{
  "action": "remove",
  "connectionId": "<connection-id>"
}
remove response
JSON
{
  "ok": true
}
syncRun property channel synchronization with current admission guards.

Success response: HTTP 200

The current reservationsOnly branch also checks automatic availability; it is not a guaranteed provider-read-only operation.

For isolated Booking CRS ingestion-only verification use sandbox-reservations action=verify instead. Default sync may process restrictions, listing settings and availability.

sync request body
JSON
{
  "action": "sync",
  "reservationsOnly": true
}
sync response
JSON
{
  "applied": 0,
  "blocked": 0,
  "complete": true
}
reviewRead the property-wide activation/publication review.

Success response: HTTP 200

Inspect actual blockers, issues, reservation coverage and proposedChanges. canApprove is not permission to auto-approve.

review request body
JSON
{
  "action": "review"
}
review response
JSON
{
  "status": "blocked",
  "canApprove": false,
  "blockers": [],
  "nextActions": []
}
approvePublish only the explicitly owner-approved review.

Success response: HTTP 200

Property-wide scope: all participating active connections, not just the card last selected. Requires fresh reservation review and matching persisted review.

approve request body
JSON
{
  "action": "approve",
  "reviewed": true,
  "reviewId": "<publication-review-id>"
}
approve response
JSON
{
  "status": "<publication-result>"
}
publishCompatibility alias for explicit reviewed publication.

Success response: HTTP 200

Same owner review requirements and upstream effects as approve. Never use as an automatic retry after an unknown send.

publish request body
JSON
{
  "action": "publish",
  "reviewed": true,
  "reviewId": "<publication-review-id>"
}
publish response
JSON
{
  "status": "<publication-result>"
}
verify_publicationCheck the published review against provider readback.

Success response: HTTP 200

Possible results include not_verified/unavailable. This checks already reviewed publication but can reconcile booking restrictions; it is not a general read-only provider audit endpoint.

verify_publication request body
JSON
{
  "action": "verify_publication",
  "reviewId": "<publication-review-id>"
}
verify_publication response
JSON
{
  "status": "verified",
  "reviewId": "<publication-review-id>",
  "checkedAt": "<ISO timestamp>",
  "mismatches": 0
}
enable_availability_syncExplicitly enable ongoing availability synchronization after verified setup.

Success response: HTTP 200

Requires current mappings and a verified published review. Enabling can pull bookings and send availability; do not enable it on a live listing for certification exercises.

enable_availability_sync request body
JSON
{
  "action": "enable_availability_sync",
  "reviewId": "<verified publication-review-id>"
}
enable_availability_sync response
JSON
{
  "enabled": true
}
disable_rate_syncStop automatic price sends for the selected listing/channel mapping.

Success response: HTTP 200

Does not disconnect, change restrictions or erase pending receipts. In-flight/accepted writes cannot be recalled; any unsent stale batch is held.

disable_rate_sync request body
JSON
{
  "action": "disable_rate_sync",
  "connectionId": "<connection-id>",
  "roomId": "<room-id>",
  "externalListingId": "<listing-id>"
}
disable_rate_sync response
JSON
{
  "status": "disabled",
  "connectionId": "<connection-id>"
}
preview_importRead content/coverage available for an authorized listing.

Success response: HTTP 200

Source history/content may be incomplete. This does not create an OTA listing or prove coverage.

preview_import request body
JSON
{
  "action": "preview_import",
  "connectionId": "<connection-id>",
  "externalListingId": "<listing-id>"
}
preview_import response
JSON
{
  "importId": "<import-id>",
  "status": "<import-status>"
}
importImport reviewed listing content as a Draft Wikiup room.

Success response: HTTP 200

capacity is an integer 1–100; nightlyRate is positive USD ≤100000. Room.name is internal; listingTitle is guest-facing. Resume copying until ready; do not assume complete history.

import request body
JSON
{
  "action": "import",
  "importId": "<import-id>",
  "capacity": 2,
  "nightlyRate": 137,
  "name": "Internal unit",
  "listingTitle": "Guest-facing listing title",
  "reviewed": true
}
import response
JSON
{
  "roomId": "<room-id>",
  "status": "<import-status>"
}
request_channelSubmit an authenticated request for channel availability.

Success response: HTTP 200

This submits a product request; it does not activate or authorize an external channel.

request_channel request body
JSON
{
  "action": "request_channel",
  "name": "<requested channel name>",
  "notes": "<optional context>"
}
request_channel response
JSON
{
  "recorded": true,
  "emailConfirmed": true,
  "alreadyRequested": false
}

Behavior & constraints

  • Owner-only. Distribution actions are preview-only. request_channel is available in preview and production. Send an action from the documented command list.
  • enable requires plan (hotel or rental), accepted:true, and termsVersion. The current terms version is returned by GET. Pricing: USD 15/property/month for the first 5 hotel rooms, plus USD 1/month per additional physical room; USD 10/property/month for one independent rental. Sandbox consent creates no charge.
  • request_channel requires name and optional notes. Sends a channel activation request from noreply@wikiup.app to chris@wikiupbnb.com with the authenticated requester and property. Requests are deduplicated per owner/property/channel and limited to five per owner per day. recorded:true means it is saved; emailConfirmed:true means the email service accepted it. An unconfirmed email is not automatically resent.
  • connect requires code and settings for credential channels; returns authorization_required with url, settings_required with fields, or mapping_required with connectionId. Use returned fields; do not infer required OTA settings.
  • An owner-bound read/write API key can perform every property workflow command without a console session. Read-only keys cannot POST. Property grants and current ownership are checked on every request. Production release administration is a separate operator-only capability.
  • cancel_authorization takes the exact token and revokes a pending authorization session without contacting the channel. Repeating cancellation is safe. Completed authorizations cannot be canceled this way; use remove with the saved connectionId. Callback completion rejects revoked sessions.
  • connect optionally accepts redirectUrl for your application's browser callback. Use absolute HTTPS, no credentials, fragment or reserved success/token/channel_id query parameters; preview permits HTTP loopback URLs. The native iOS client may use the exact allowlisted callback app.wikiup.innkeeper.channel-import://callback (no path, query or fragment). Omission retains the Wikiup callback. authorization_required also returns sessionId, token, expiresAt and redirectUrl. Tokens expire after 30 minutes and remain bound to the initiating owner and property. In preview, simulated OAuth also returns channelId, so your UI can collect sample-account consent then submit complete directly without visiting Wikiup Console. Real channels still require their own authorization.
  • listings requires connectionId and returns listings plus mappingFields; each listing includes mappedRoomId when already mapped on this connection. Map multiple listings by submitting map once per listing, sequentially, retaining successful results when another listing fails. map requires connectionId, roomId, externalListingId, and optional descriptor-defined settings. Existing room pricing must be positive.
  • preview_import requires connectionId and externalListingId; returns normalized listing details and an import ID. import requires importId, capacity, nightlyRate (USD), reviewed:true; optional name and description override source content for a new room. Resumed preview_import returns the existing room details. It creates one Draft room and copies photos in resumable batches. Repeat import until status is ready.
  • activate requires connectionId, reviewed:true and testListingAcknowledged:true. Only controlled test connections should be activated; staging can still affect a live OTA listing. Readiness is checked, inventory is closed, and existing reservation import is requested. pause requires connectionId and keeps the connection. remove requires connectionId: deactivates and deletes the provider connection, retires its mappings, and revokes outstanding authorization sessions for that channel. Existing Wikiup reservations and shared room inventory are retained. Removal is owner-only and preview-only; failures remain retryable. Shared provider connections spanning several properties cannot be removed here.
  • sync durably applies sanitized booking revisions before acknowledging them. Conflicts remain unacknowledged and create issues. No guest mail or payment is created by imported bookings. reservationsOnly:true skips the full restriction/listing-settings stage but still invokes the automatic availability path; do not treat it as read-only. For isolated staging ingestion only, use sandbox-reservations action=verify.
  • review prepares a persisted publication-review snapshot without publishing rates/availability and returns the property-wide activation summary, cumulative imported reservation/update counts, mapped rooms and prices, active connection states, issues, stable blocker codes and canApprove. It does not run a reservation check. Call sync then review. approve with reviewed:true rechecks reservations and submits inventory/rates using the same service as publish (retained for compatibility). Approval covers all active channels and mapped rooms at this property. A new activation clears previous approval; sync alone cannot open that new setup.
  • review.availability.status distinguishes not_sent, pending, failed and accepted. Retry a failed availability send with approve; Check again/sync only refreshes reservations. Rate limits return 429, Retry-After and retryAfterSeconds. review.availability.retryAt supplies the cooldown deadline. Respect it before retrying. Full property snapshots are batched, not sent in small per-date requests.
  • publish requires reviewed:true and a recent reservation check; it sends a 365-day absolute sandbox inventory and standard nightly-rate snapshot. Draft/Inactive rooms and occupied nights stay closed. Provider acceptance is not OTA delivery confirmation. Recurring recovery must process captured changes; it does not authorize repeating a full snapshot.
  • All reservations available from the source may not include complete history, guest details or fees. Owners must review source calendar coverage and prior integrations before opening sales.
  • Uncertain creates require reconciliation; retries never silently create another external property or room.
Request
cURL
curl -X POST 'https://api-preview.wikiup.app/api/properties/<property-id>/channel-management' \
  -H 'Authorization: Bearer <owner-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"action":"enable","plan":"rental","termsVersion":"<plans.rental.version-from-GET>","accepted":true}'
Example response
JSON
{
  "enabled": true,
  "billing": "accepted"
}

Complete an owner-bound, expiring booking-channel authorization session.

Body fields

tokenstringRequired

Echoed single-use authorization token.

channelIdstringRequired

Echoed channel connection identifier.

Behavior & constraints

  • The authenticated owner, property membership, token digest, expiration, channel and provider property association must match before the connection is stored. Remove callback query parameters from browser history immediately.
  • Supports an owner-bound read/write API key or owner session. Alternatively POST action:complete to the property channel-management endpoint with the same token and channelId. Replay with the identical token/channelId returns the existing Wikiup connection; it does not create another connection. Read-only or cross-property keys are rejected. Responses use Cache-Control: no-store.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/channel-management/authorization' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"token":"<echoed-token>","channelId":"<echoed-channel-id>"}'
Example response
JSON
{
  "connectionId": "wikiup-connection-id",
  "propertyId": "wikiup-property-id"
}

Accept authenticated booking-change signals and reconcile the revision feed.

Request headers

x-wikiup-channel-tokenstringRequired

Server-generated per-property webhook credential.

Query parameters

propertyIdstringRequired

Wikiup property ID configured by the server.

Behavior & constraints

  • Internal delivery endpoint. Customers do not configure webhook secrets. Event metadata is persisted before the sanitized reservation feed is read. A successful callback does not acknowledge an unsaved booking revision. Backup polling remains necessary.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/channel-management/webhook?propertyId=<property-id>' \
  -H 'x-wikiup-channel-token: <configured-token>' \
  -H 'Content-Type: application/json' \
  -d '{"event":"booking_new","property_id":"<external-property-id>","timestamp":"2026-10-28T12:00:00Z"}'
Example response
JSON
{
  "received": true
}

API Reference

Chat

Read the current property's shared staff AI processing and knowledge settings.

Behavior & constraints

  • Requires reservations.view. Returns version, processing, knowledge, and revision. Missing configuration disables AI processing.
Request
cURL
curl 'https://api.wikiup.app/api/chat/ai-settings' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "version": "2026-11-03-property-v1",
  "processing": false,
  "knowledge": false,
  "revision": ""
}

Update shared staff AI settings or exclude an individual conversation from knowledge learning.

Body fields

versionstringRequired

Current disclosure version returned by GET.

revisionstringRequired

Current settings revision for optimistic concurrency.

processingbooleanOptional

Required for property settings; enables staff AI assistance.

knowledgebooleanRequired

Whether staff replies may contribute to private knowledge review.

conversationIdstringOptional

Optional conversation whose learning preference is being changed.

Behavior & constraints

  • Requires reservations.manage. Supply the current version and revision; stale revisions return 409. Conversation overrides are property-scoped.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/chat/ai-settings' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: <property-id>' \
  -H 'Content-Type: application/json' --data '{"version":"2026-11-03-property-v1","revision":"","processing":true,"knowledge":true}'
Example response
JSON
{
  "version": "2026-11-03-property-v1",
  "processing": true,
  "knowledge": true,
  "revision": "<revision>"
}

API Reference

Email & Integrations

Read messages from the property's connected Gmail mailbox. With email, returns conversation threads involving that address (including sent/archived mail); with pageSize/pageToken, pages the primary inbox. Without either, returns a compact unread-first inbox feed.

Used by console guest messaging and native innkeeper reservation email threads.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

emailstringOptional

Participant email to search across threads; ignored in recent=true mode.

pageSizeintegerOptional

Requested Gmail page size. Explicitly supplying it selects paginated inbox mode when email is absent.

pageTokenstringOptional

Opaque Gmail nextPageToken from a prior response.

recentbooleanOptional

Only the literal true selects recent-feed mode; that mode returns messages without nextPageToken.

Allowed valuestruefalse
formatstringOptional

Defaults to metadata; full retrieves message bodies. Participant thread searches hydrate complete threads.

Allowed valuesmetadatafull

Response fields

messagesArray<object>Required

Messages returned by the requested provider mode.

messages[]objectRequired

Email message projected by the messaging service.

messages[].idstringRequired

Provider message identifier.

messages[].textstringRequired

Plain-text content, or a snippet when format=metadata.

messages[].htmlstringOptional

Rendered-source HTML when available with format=full. Sanitize/isolate before rendering; absent for metadata.

messages[].sender"me" | "guest"Required

me is the property mailbox; guest is the other participant.

messages[].datestringRequired

Original email Date header; includes an offset and may be RFC 2822 rather than ISO 8601. Display in the property time zone.

messages[].fromstringRequired

From header; may contain display name and email.

messages[].tostringOptional

To header.

messages[].replyTostringOptional

Reply-To header; may be empty.

messages[].unreadbooleanRequired

Whether the provider marks the message unread.

messages[].subjectstringRequired

Email subject.

messages[].threadIdstringOptional

Provider thread ID when included.

messages[].isDraftbooleanOptional

Whether this provider record is a draft.

messages[].draftIdstringOptional

Draft identifier when resolved.

nextPageTokenstringOptional

Opaque provider page token. Omitted when unavailable, including recent=true.

Behavior & constraints

  • Requires an interactive account session. API keys cannot access connected mailbox contents or drafts.
  • Requires reservations.view for GET or reservations.manage for mutations, plus a connected Google mailbox. These endpoints operate on Gmail message/draft IDs, not website chat IDs.
  • Pass nextPageToken as pageToken for subsequent pages; it may be absent when there is no next page.
  • This hosted API route supports GET only. It does not expose a general POST /api/messages send contract.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/messages?pageSize=20&format=full' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "messages": [
    {
      "id": "message_example",
      "text": "Your room is ready.",
      "html": "<p>Your room is ready.</p>",
      "sender": "me",
      "date": "Tue, 9 Feb 2027 16:00:00 -0800",
      "from": "Example Hotel <hotel@example.com>",
      "to": "guest@example.com",
      "replyTo": "hotel@example.com",
      "unread": false,
      "subject": "Your room is ready",
      "threadId": "thread_example",
      "isDraft": false
    }
  ]
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

Replace the contents of an existing Gmail draft, including recipients, subject, body, threading headers, and attachments, without sending it.

Used by console guest messaging and native innkeeper reservation email threads.

Path parameters

draftIdstringRequired

Existing Gmail draft ID returned with a draft message; this endpoint does not create a new draft ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

tostringRequired

Recipient email/header value; must be nonempty.

subjectstringRequired

Email subject; must be nonempty.

bodystringRequired

Email content; must be nonempty. The email builder supports rich HTML content.

inReplyTostringOptional

Original RFC Message-ID header when composing a reply.

threadIdstringOptional

Gmail thread ID to retain conversation grouping.

attachmentsobject[]Optional

Optional file attachments.

attachments[].filenamestringOptional

Attachment filename. Entries without a filename or contentBase64 are ignored.

attachments[].mimeTypestringOptional

MIME type; defaults to application/octet-stream.

attachments[].contentBase64stringOptional

Base64-encoded file bytes; required for an attachment to be retained.

Behavior & constraints

  • Requires an interactive account session. API keys cannot access connected mailbox contents or drafts.
  • Requires reservations.view for GET or reservations.manage for mutations, plus a connected Google mailbox. These endpoints operate on Gmail message/draft IDs, not website chat IDs.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/messages/drafts/draftId_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"to":"guest@example.com","subject":"Your upcoming stay","body":"We look forward to welcoming you."}'
Response · 200
JSON
{
  "message": "Draft saved successfully"
}

Save the supplied draft contents and then send that Gmail draft. This sends a real email from the connected property mailbox and returns the sent message/thread identifiers.

Used by console guest messaging and native innkeeper reservation email threads.

Path parameters

draftIdstringRequired

Existing Gmail draft ID returned with a draft message; this endpoint does not create a new draft ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

tostringRequired

Recipient email/header value; must be nonempty.

subjectstringRequired

Email subject; must be nonempty.

bodystringRequired

Email content; must be nonempty. The email builder supports rich HTML content.

inReplyTostringOptional

Original RFC Message-ID header when composing a reply.

threadIdstringOptional

Gmail thread ID to retain conversation grouping.

attachmentsobject[]Optional

Optional file attachments.

attachments[].filenamestringOptional

Attachment filename. Entries without a filename or contentBase64 are ignored.

attachments[].mimeTypestringOptional

MIME type; defaults to application/octet-stream.

attachments[].contentBase64stringOptional

Base64-encoded file bytes; required for an attachment to be retained.

Behavior & constraints

  • Requires an interactive account session. API keys cannot access connected mailbox contents or drafts.
  • Requires reservations.view for GET or reservations.manage for mutations, plus a connected Google mailbox. These endpoints operate on Gmail message/draft IDs, not website chat IDs.
  • A successful response consumes the draft. Check the message/thread state before retrying after an uncertain network result.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/messages/drafts/draftId_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"to":"guest@example.com","subject":"Your upcoming stay","body":"We look forward to welcoming you."}'
Response · 200
JSON
{
  "message": "Draft sent successfully",
  "messageId": "gmail_message_example",
  "threadId": "gmail_thread_example"
}

Discard an existing draft in the property's connected Gmail mailbox. No email is sent.

Used by console guest messaging and native innkeeper reservation email threads.

Path parameters

draftIdstringRequired

Existing Gmail draft ID returned with a draft message; this endpoint does not create a new draft ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires an interactive account session. API keys cannot access connected mailbox contents or drafts.
  • Requires reservations.view for GET or reservations.manage for mutations, plus a connected Google mailbox. These endpoints operate on Gmail message/draft IDs, not website chat IDs.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/messages/drafts/draftId_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

Mark a Gmail message as read by removing its UNREAD label. This does not change the website-chat inbox attention state.

Used by console guest messaging and native innkeeper reservation email threads.

Path parameters

idstringRequired

Gmail message ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires an interactive account session. API keys cannot access connected mailbox contents or drafts.
  • Requires reservations.view for GET or reservations.manage for mutations, plus a connected Google mailbox. These endpoints operate on Gmail message/draft IDs, not website chat IDs.
  • No request body required.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/messages/id_example/read' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "status": "ok"
}

Archive a Gmail message by removing it from the inbox. The message remains in the mailbox and can still appear in participant-thread searches.

Used by console guest messaging and native innkeeper reservation email threads.

Path parameters

idstringRequired

Gmail message ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires an interactive account session. API keys cannot access connected mailbox contents or drafts.
  • Requires reservations.view for GET or reservations.manage for mutations, plus a connected Google mailbox. These endpoints operate on Gmail message/draft IDs, not website chat IDs.
  • No request body required.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/messages/id_example/archive' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "status": "ok"
}

Check whether a property has a usable Google email connection and return its sender email when connected. The selected property is a query parameter rather than an x-property-id header.

Used by Property email settings to display the connected mailbox.

Query parameters

propertyIdstringRequired

Property ID for which the signed-in user holds membership.

Response fields

connectedbooleanOptional

Whether mailbox credentials can currently resolve a sender address.

emailstringOptional

Connected sender address; only present when connected=true.

Behavior & constraints

  • The current implementation returns connected=false for missing/invalid connection credentials and caught authentication failures; membership lookup failure may return 404.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/email/connections?propertyId=property_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN"
Response · 200
JSON
{
  "connected": true,
  "email": "stay@example.com"
}

Start the Google mailbox connection flow by redirecting the browser to Google's consent screen. This integration enables property email reading, sending, and read/archive operations; it is separate from Wikiup account sign-in.

Browser navigation from the property email integration settings.

Query parameters

propertyIdstringRequired

Property to associate with the email connection.

Behavior & constraints

  • Navigate the browser to this endpoint; it returns a redirect rather than JSON.
  • Requests the gmail.modify scope and offline access so the mailbox can be used after the interactive session ends.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/oauth/google?propertyId=property_example'
Response · 307
redirect
HTTP/1.1 307 Temporary Redirect
Location: https://accounts.google.com/o/oauth2/v2/auth?...

Finish the Google email integration by exchanging Google's authorization code, resolving the mailbox address, saving the connection, and redirecting to the property page.

Invoked by Google after consent; not an application data-fetching endpoint.

Query parameters

codestringRequired

One-time authorization code supplied by Google.

statestringRequired

State issued by the start flow; pass through unchanged.

Behavior & constraints

  • Success redirects to /properties/{propertyId}. Error responses from this callback can be plain text rather than the normal JSON API error shape.
  • Do not manufacture authorization codes or reuse a completed callback URL.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/oauth/google/callback?code=google_authorization_code&state=oauth_state'
Response · 307
redirect
HTTP/1.1 307 Temporary Redirect
Location: /properties/property_example

Remove the property's saved Google email connection. Subsequent Gmail-dependent operations require reconnecting the mailbox.

Used by property email settings to disconnect a mailbox.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

propertyIdstringRequired

Must equal the x-property-id header.

Behavior & constraints

  • Requires property.manage. No request body. This removes Wikiup's saved credentials; it does not delete mailbox contents.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/oauth/google/disconnect?propertyId=property_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "success": true
}

API Reference

Email Campaigns

Previews a unique, deliverable email audience from this property's guests and waitlist, with reservation-history and spending filters, complete counts and a snapshot fingerprint.

The console campaign wizard uses this operation to refine recipients and review ten contacts at a time before creating a campaign. Opening a guest or its messages is a separate guest/mailbox operation.

Request headers

AuthorizationstringRequired

Bearer account-session token or API key. A read_write key is required for POST/PATCH, including preview requests.

x-property-idstringRequired

Property whose contacts, reservations, branding and campaigns are being accessed.

Body fields

filtersobjectRequired

Validated audience definition. Unknown filter keys are rejected. Reuse this exact definition when enqueueing.

filters.sourcestringOptional

Contact source; defaults to guests. both forms a union, deduplicated by trimmed, lowercase email.

Allowed valuesguestswaitlistboth
filters.searchstringOptional

Optional literal, case-insensitive name/email/phone substring; at most 200 characters. Searches all duplicate contact records.

filters.stayFromstring · dateOptional

Inclusive earliest completed-stay check-in date, YYYY-MM-DD, interpreted in the property's time zone.

filters.stayTostring · dateOptional

Inclusive latest completed-stay check-in date; must be on or after stayFrom.

filters.monthsinteger[]Optional

Check-in months of completed stays, across all years; 1 is January and 12 December. Empty/omitted means any month.

Allowed values123456789101112
filters.minStaysintegerOptional

Minimum lifetime completed-stay count, 1–100000. Date/month criteria must also match at least one completed stay.

filters.minSpendnumberOptional

Minimum lifetime net successful reservation payments in major units of the configured billing currency; nonnegative.

filters.maxSpendnumberOptional

Maximum lifetime net successful reservation payments; nonnegative and at least minSpend when both are supplied.

filters.weekdaysinteger[]Optional

Selected stay nights: 0 Sunday through 6 Saturday. Omit to use the complement of the property's configured weekend nights; an explicit array overrides that default.

Allowed values0123456
filters.minWeekdayPercentagenumberOptional

Minimum 0–100 percentage of completed-stay nights on the selected weekdays. Uses the stays matching date/month filters and excludes checkout day. Requires recorded stay history.

filters.topSpendersCountintegerOptional

Select the highest net-spend recipients after other filters, from 1 to 20000; results are then displayed by latest reservation date.

pageintegerOptional

One-based page number; defaults 1. Page size is fixed at 10. Out-of-range pages clamp to the last available page.

Response fields

filtersobject

Validated filters with normalized arrays and source default applied.

defaultWeekdaysinteger[]

Complement of Property.settings.weekendDays. Absent/empty weekend configuration uses Friday/Saturday as weekends. An explicit filter weekdays array does not change this property default.

baselineCountinteger

Unique valid, unsuppressed emails in the chosen source before contact/history/spend filters.

totalCountinteger

Complete deliverable recipient count after every filter, including topSpendersCount.

fingerprintstring

SHA-256 commitment to the full selected contact/history set, not just the current page. Financial values are excluded; monetary filters still determine audience membership.

pageinteger

Returned one-based page number.

pageSizeinteger

Always 10.

Allowed values10
pageCountinteger

Total result pages; zero for an empty audience.

items[].emailstring

Unique trimmed, lowercase deliverable email address.

items[].namestring

Contact display name, falling back to email.

items[].guestIdstring | null

Representative same-property guest ID for opening guest details; null for waitlist-only contacts without a guest record.

items[].guestIdsstring[]

All same-property guest IDs sharing this email; stay/spend totals combine these records.

items[].reservationIdstring | null

Latest noncanceled real reservation associated with this recipient.

items[].waitlistEntryIdsstring[]

Retained same-property waitlist entries sharing this email.

items[].latestReservationDatestring · date | null

Latest reservation check-in date in the property's time zone; null sorts last.

items[].completedStaysinteger

Lifetime number of recorded completed stays.

items[].netSpendnumber | null

Lifetime net paid amount in major currency units. Null for mixed currencies or when the caller cannot view financials.

items[].currencystring | null

Uppercase currency for a single-currency payment history; null for no payments, mixed currencies or hidden financials.

items[].matchingStayNightPercentagenumber | null

Percentage of matching completed-stay nights on selected weekdays; null when there are no usable nights.

items[].sourcesstring[]

Sources actually associated with the email, even if the selected filter uses only one source.

Allowed valuesguestswaitlist

Behavior & constraints

  • Requires both reservations.view and reservations.manage for the selected property. Monetary audience filters additionally require financials.view, invoice.view or invoice.manage. Discount invitations require rates.manage.
  • The service reads the complete property-scoped inventory; counts are not limited to the first database page. Invalid/missing emails and this property's promotional-email suppressions are excluded before baselineCount. Duplicate guest and waitlist records share one recipient.
  • Completed visits are real reservations with checkedout status, or checkedin reservations whose checkout date has passed in the property time zone. Upcoming, canceled and blockout records do not count as completed stays. Stay criteria exclude contacts without matching completed history.
  • Net spend adds succeeded reservation-linked payments and subtracts refunds. Redeemed gift cards count as paid stay value; discount credits, standalone gift-card purchases, pending and failed payments do not. Canceled reservations may retain net cancellation charges. Mixed-currency totals are null; monetary filters/rankings exclude totals outside the configured billing currency.
  • Results sort by latest noncanceled reservation check-in date, including upcoming reservations, then normalized email. A recipient's completedStays and netSpend are lifetime aggregates; the weekday percentage uses the date/month-matching completed stays. Historical waitlist entries already removed by the waitlist lifecycle cannot be included.
  • Copy fingerprint and totalCount into the send request as audienceFingerprint and expectedRecipientCount. The server rebuilds the full audience on enqueue and returns 409 CAMPAIGN_AUDIENCE_CHANGED if it no longer matches; preview and approve the updated audience before trying again.
  • No message, campaign or promotion is created. Without financial visibility, netSpend/currency are null; supplying monetary filters without that permission returns 403.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/campaigns/audience' \
  \
  -H 'Authorization: Bearer <access-token>' \
  \
  -H 'x-property-id: <property-id>' \
  \
  -H 'Content-Type: application/json' \
  --data '{
  "filters": {
    "source": "guests",
    "minStays": 2,
    "minWeekdayPercentage": 60
  },
  "page": 1
}'
Example response
JSON
{
  "filters": {
    "source": "guests",
    "minStays": 2,
    "minWeekdayPercentage": 60
  },
  "defaultWeekdays": [
    0,
    1,
    2,
    3,
    4
  ],
  "baselineCount": 120,
  "totalCount": 1,
  "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "page": 1,
  "pageSize": 10,
  "pageCount": 1,
  "items": [
    {
      "email": "alex@example.com",
      "name": "Alex Guest",
      "guestId": "guest-example",
      "guestIds": [
        "guest-example"
      ],
      "reservationId": "reservation-example",
      "waitlistEntryIds": [],
      "latestReservationDate": "2026-09-22",
      "completedStays": 3,
      "netSpend": 820,
      "currency": "USD",
      "matchingStayNightPercentage": 80,
      "sources": [
        "guests"
      ]
    }
  ]
}

Renders the branded campaign subject and sanitized email HTML for a sample guest without sending mail, creating a campaign or reserving a discount code.

The message editor's preview uses this response to show the same template rendering used during campaign delivery.

Request headers

AuthorizationstringRequired

Bearer account-session token or API key. A read_write key is required for POST/PATCH, including preview requests.

x-property-idstringRequired

Property whose contacts, reservations, branding and campaigns are being accessed.

Body fields

subjectstringRequired

Email subject, trimmed 1–200 characters and a single line. Supports the template variables listed below.

bodyHtmlstringRequired

Message HTML, trimmed 1–200000 characters. Server sanitization removes active content, unsafe attributes and unsupported styles; message text or an image is required.

ctaobjectRequired

Optional-button behavior expressed as an explicit object; use kind:none to omit the button.

cta.kindstringRequired

website links to the property's websiteUrl; discount links to this campaign's booking invitation; none omits the button.

Allowed valueswebsitediscountnone
cta.labelstringOptional

Button label, at most 80 characters; defaults to Learn more. Must be nonempty unless kind is none.

invitationobjectOptional

Required when cta.kind is discount; omit for other kinds. Creates a new campaign-owned promotion, not a reference to an existing code.

invitation.namestringOptional

Promotion name, trimmed 1–160 characters; required for a discount invitation.

invitation.discountTypestringOptional

Required discount calculation mode.

Allowed valuespercentfixedAmount
invitation.discountValuenumberOptional

Required positive value, rounded to two decimals; percent cannot exceed 100. fixedAmount uses major currency units.

invitation.codestringOptional

Optional eight-character alphanumeric code containing both letters and digits; normalized uppercase. Omit for a generated campaign code.

invitation.startsAtstring · date | nullOptional

First redemption date, YYYY-MM-DD; empty strings normalize to null.

invitation.validUntilstring · date | nullOptional

Last redemption date; cannot precede startsAt.

invitation.validCheckInFromstring · date | nullOptional

Earliest eligible check-in date.

invitation.validCheckInUntilstring · date | nullOptional

Latest eligible check-in date; cannot precede validCheckInFrom.

invitation.validCheckOutUntilstring · date | nullOptional

Latest eligible check-out date; must follow validCheckInFrom when both are supplied.

invitation.minNightsinteger | nullOptional

Optional nonnegative minimum stay length.

invitation.minSubtotalnumber | nullOptional

Optional nonnegative minimum lodging subtotal, rounded to two decimals.

invitation.allowedRoomIdsstring[]Optional

Up to 500 unique property-owned room IDs; defaults to an unrestricted empty list.

invitation.excludedPriceRuleIdsstring[]Optional

Up to 500 unique property-owned price-rule IDs excluded from combining with the promotion.

invitation.blackoutDatesstring[] · dateOptional

Up to 3660 YYYY-MM-DD blackout dates, deduplicated and sorted; defaults to [].

invitation.weekdaysOnlybooleanOptional

Defaults false. When true, stay nights must avoid the property's configured weekend nights.

invitation.combinablebooleanOptional

Whether the promotion can combine with other eligible pricing adjustments; defaults false.

invitation.internalNotestring | nullOptional

Optional private promotion note, at most 2000 characters.

sampleobjectOptional

Optional sample guest. Only name and email are read; no guest record is created or looked up.

sample.namestringOptional

Sample name; truncated to 200 characters and defaults to Alex Guest.

sample.emailstringOptional

Sample email; truncated to 254 characters and defaults to an empty string.

Response fields

subjectstring

Rendered single-line subject, limited to 200 characters.

htmlstring

Complete branded HTML document. Preview has no live unsubscribe credential.

Behavior & constraints

  • Requires both reservations.view and reservations.manage for the selected property. Monetary audience filters additionally require financials.view, invoice.view or invoice.manage. Discount invitations require rates.manage.
  • Variables use single braces: {guestName}, {guestFirstName}, {guestLastName}, {guestEmail}, {propertyListingTitle}, {propertyWebsiteUrl}, {propertyContactEmail}, {propertyContactPhone}, {propertyAddress}, {currentYear}. Unknown named variables return 400. Guest values are escaped in HTML.
  • The generated message uses property branding and contact details. website and discount buttons require a valid property websiteUrl. The server controls the destination; a caller-supplied arbitrary button URL is not part of this contract.
  • For a discount invitation, preview validates its fields but uses the property's website as a placeholder destination. The actual campaign invitation URL is generated only during job preparation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/campaigns/preview' \
  \
  -H 'Authorization: Bearer <access-token>' \
  \
  -H 'x-property-id: <property-id>' \
  \
  -H 'Content-Type: application/json' \
  --data '{
  "subject": "A little time away, {guestFirstName}",
  "bodyHtml": "<p>Hi {guestFirstName}, we would love to welcome you back to {propertyListingTitle}.</p>",
  "cta": {
    "kind": "website",
    "label": "Plan your visit"
  },
  "sample": {
    "name": "Alex Guest",
    "email": "alex@example.com"
  }
}'
Example response
JSON
{
  "subject": "A little time away, Alex",
  "html": "<!doctype html><html>…branded, sanitized email document…</html>"
}

Lists the twenty most recently created campaigns for the selected property, including durable processing state and recipient outcome totals.

The console resumes campaign monitoring from this list without relying on the tab that originally started the send.

Request headers

AuthorizationstringRequired

Bearer account-session token or API key. A read_write key is required for POST/PATCH, including preview requests.

x-property-idstringRequired

Property whose contacts, reservations, branding and campaigns are being accessed.

Response fields

campaignsCampaignSummary[]

Up to 20 summaries. Each element has the same fields as campaign in the create/detail responses.

Behavior & constraints

  • Requires both reservations.view and reservations.manage for the selected property. Monetary audience filters additionally require financials.view, invoice.view or invoice.manage. Discount invitations require rates.manage.
  • Newest creation time first; this collection currently has no pagination parameter. Use GET /api/campaigns/{id} to inspect a campaign's recipient outcomes.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/campaigns' \
  \
  -H 'Authorization: Bearer <access-token>' \
  \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "campaigns": [
    {
      "id": "campaign-example",
      "name": "A quiet-season invitation",
      "subject": "A little time away, {guestFirstName}",
      "status": "queued",
      "total": 1,
      "counts": {
        "pending": 1,
        "preparing": 0,
        "sending": 0,
        "accepted": 0,
        "failed": 0,
        "unknown": 0,
        "suppressed": 0,
        "canceled": 0
      },
      "createdAt": "2026-10-23T18:00:00.000Z",
      "updatedAt": "2026-10-23T18:00:00.000Z",
      "startedAt": null,
      "completedAt": null,
      "invitationUrl": null,
      "lastError": null
    }
  ]
}

Creates a durable campaign from an explicitly reviewed audience snapshot and starts bounded background processing. A 202 response confirms queuing, not delivery.

After reviewing recipients and message preview, the console supplies a UUID requestId plus the latest audience fingerprint/count, then polls the returned campaign ID for progress.

Request headers

AuthorizationstringRequired

Bearer account-session token or API key. A read_write key is required for POST/PATCH, including preview requests.

x-property-idstringRequired

Property whose contacts, reservations, branding and campaigns are being accessed.

Body fields

requestIdstring · UUIDRequired

Client-generated idempotency identifier. Reuse only for retries of this exact request.

namestringRequired

Internal campaign name, trimmed 1–120 characters.

subjectstringRequired

Email subject, trimmed 1–200 characters and a single line. Supports the template variables listed below.

bodyHtmlstringRequired

Message HTML, trimmed 1–200000 characters. Server sanitization removes active content, unsafe attributes and unsupported styles; message text or an image is required.

ctaobjectRequired

Optional-button behavior expressed as an explicit object; use kind:none to omit the button.

cta.kindstringRequired

website links to the property's websiteUrl; discount links to this campaign's booking invitation; none omits the button.

Allowed valueswebsitediscountnone
cta.labelstringOptional

Button label, at most 80 characters; defaults to Learn more. Must be nonempty unless kind is none.

invitationobjectOptional

Required when cta.kind is discount; omit for other kinds. Creates a new campaign-owned promotion, not a reference to an existing code.

invitation.namestringOptional

Promotion name, trimmed 1–160 characters; required for a discount invitation.

invitation.discountTypestringOptional

Required discount calculation mode.

Allowed valuespercentfixedAmount
invitation.discountValuenumberOptional

Required positive value, rounded to two decimals; percent cannot exceed 100. fixedAmount uses major currency units.

invitation.codestringOptional

Optional eight-character alphanumeric code containing both letters and digits; normalized uppercase. Omit for a generated campaign code.

invitation.startsAtstring · date | nullOptional

First redemption date, YYYY-MM-DD; empty strings normalize to null.

invitation.validUntilstring · date | nullOptional

Last redemption date; cannot precede startsAt.

invitation.validCheckInFromstring · date | nullOptional

Earliest eligible check-in date.

invitation.validCheckInUntilstring · date | nullOptional

Latest eligible check-in date; cannot precede validCheckInFrom.

invitation.validCheckOutUntilstring · date | nullOptional

Latest eligible check-out date; must follow validCheckInFrom when both are supplied.

invitation.minNightsinteger | nullOptional

Optional nonnegative minimum stay length.

invitation.minSubtotalnumber | nullOptional

Optional nonnegative minimum lodging subtotal, rounded to two decimals.

invitation.allowedRoomIdsstring[]Optional

Up to 500 unique property-owned room IDs; defaults to an unrestricted empty list.

invitation.excludedPriceRuleIdsstring[]Optional

Up to 500 unique property-owned price-rule IDs excluded from combining with the promotion.

invitation.blackoutDatesstring[] · dateOptional

Up to 3660 YYYY-MM-DD blackout dates, deduplicated and sorted; defaults to [].

invitation.weekdaysOnlybooleanOptional

Defaults false. When true, stay nights must avoid the property's configured weekend nights.

invitation.combinablebooleanOptional

Whether the promotion can combine with other eligible pricing adjustments; defaults false.

invitation.internalNotestring | nullOptional

Optional private promotion note, at most 2000 characters.

filtersobjectRequired

Validated audience definition. Unknown filter keys are rejected. Reuse this exact definition when enqueueing.

filters.sourcestringOptional

Contact source; defaults to guests. both forms a union, deduplicated by trimmed, lowercase email.

Allowed valuesguestswaitlistboth
filters.searchstringOptional

Optional literal, case-insensitive name/email/phone substring; at most 200 characters. Searches all duplicate contact records.

filters.stayFromstring · dateOptional

Inclusive earliest completed-stay check-in date, YYYY-MM-DD, interpreted in the property's time zone.

filters.stayTostring · dateOptional

Inclusive latest completed-stay check-in date; must be on or after stayFrom.

filters.monthsinteger[]Optional

Check-in months of completed stays, across all years; 1 is January and 12 December. Empty/omitted means any month.

Allowed values123456789101112
filters.minStaysintegerOptional

Minimum lifetime completed-stay count, 1–100000. Date/month criteria must also match at least one completed stay.

filters.minSpendnumberOptional

Minimum lifetime net successful reservation payments in major units of the configured billing currency; nonnegative.

filters.maxSpendnumberOptional

Maximum lifetime net successful reservation payments; nonnegative and at least minSpend when both are supplied.

filters.weekdaysinteger[]Optional

Selected stay nights: 0 Sunday through 6 Saturday. Omit to use the complement of the property's configured weekend nights; an explicit array overrides that default.

Allowed values0123456
filters.minWeekdayPercentagenumberOptional

Minimum 0–100 percentage of completed-stay nights on the selected weekdays. Uses the stays matching date/month filters and excludes checkout day. Requires recorded stay history.

filters.topSpendersCountintegerOptional

Select the highest net-spend recipients after other filters, from 1 to 20000; results are then displayed by latest reservation date.

audienceFingerprintstringRequired

The exact 64-character lowercase SHA-256 fingerprint from the latest audience preview.

expectedRecipientCountintegerRequired

The exact totalCount reviewed in the audience preview, from 1 to 20000.

Response fields

campaign.idstring

Server-generated campaign identifier.

campaign.namestring

Internal campaign name.

campaign.subjectstring

Saved subject template; individual messages resolve guest variables.

campaign.statusstring

Durable job state. completed means processing finished, not confirmed inbox delivery; needs_attention requires operator review.

Allowed valuespreparingqueuedsendingcompletedneeds_attentioncanceled
campaign.totalinteger

Immutable selected-recipient count.

campaign.countsobject

Cached recipient totals refreshed by the background processor, including recipients still waiting to be materialized. They can briefly lag in-flight work. accepted records provider acceptance, not delivery/open tracking.

campaign.counts.*integer

All status counters are present.

Allowed valuespendingpreparingsendingacceptedfailedunknownsuppressedcanceled
campaign.createdAtstring · date-time

Creation time in ISO 8601 UTC.

campaign.updatedAtstring · date-time

Most recent job-state update in ISO 8601 UTC.

campaign.startedAtstring · date-time | null

Processing start time, or null before processing.

campaign.completedAtstring · date-time | null

Completion time, or null while unfinished.

campaign.invitationUrlstring | null

Booking invitation URL after promotion preparation; null when absent or not yet prepared.

campaign.lastErrorstring | null

Sanitized operational error, if present.

Behavior & constraints

  • Requires both reservations.view and reservations.manage for the selected property. Monetary audience filters additionally require financials.view, invoice.view or invoice.manage. Discount invitations require rates.manage.
  • Variables use single braces: {guestName}, {guestFirstName}, {guestLastName}, {guestEmail}, {propertyListingTitle}, {propertyWebsiteUrl}, {propertyContactEmail}, {propertyContactPhone}, {propertyAddress}, {currentYear}. Unknown named variables return 400. Guest values are escaped in HTML.
  • The generated message uses property branding and contact details. website and discount buttons require a valid property websiteUrl. The server controls the destination; a caller-supplied arbitrary button URL is not part of this contract.
  • The server rebuilds the audience and compares the full fingerprint and count. A mismatch returns 409 with code CAMPAIGN_AUDIENCE_CHANGED. No campaign is queued until the reviewed audience matches.
  • Reuse the same requestId and identical body after an uncertain response to retrieve the same campaign. Reusing it with different content returns 409. A new requestId represents a new send; do not generate one merely to retry a timeout.
  • The audience must contain 1–20000 recipients and its serialized snapshot must fit the service limit (8 MB). Queued work continues independently of the browser. Poll GET /api/campaigns/{id}; Location also identifies that resource.
  • For discount invitations the server creates one active promotion for this campaign, applies it to lodging subtotal only, sets maxRedemptions to the reviewed recipient count and maxRedemptionsPerGuest to 1. Caller-supplied IDs, property scope and counters are ignored. These are configured promotion limits, not a claim of atomic redemption enforcement.
  • Promotional suppressions are checked again before provider submission. Rate limits pause sending; uncertain provider acceptance is recorded as unknown and is not automatically resent. accepted is provider acceptance, not verified inbox delivery.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/campaigns' \
  \
  -H 'Authorization: Bearer <access-token>' \
  \
  -H 'x-property-id: <property-id>' \
  \
  -H 'Content-Type: application/json' \
  --data '{
  "requestId": "a99b43f0-179e-49d1-9eea-52a76454a1af",
  "name": "A quiet-season invitation",
  "subject": "A little time away, {guestFirstName}",
  "bodyHtml": "<p>Hi {guestFirstName}, we would love to welcome you back to {propertyListingTitle}.</p>",
  "cta": {
    "kind": "website",
    "label": "Plan your visit"
  },
  "filters": {
    "source": "guests",
    "minStays": 2,
    "minWeekdayPercentage": 60
  },
  "audienceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "expectedRecipientCount": 1
}'
Response · 202
JSON
{
  "campaign": {
    "id": "campaign-example",
    "name": "A quiet-season invitation",
    "subject": "A little time away, {guestFirstName}",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "preparing": 0,
      "sending": 0,
      "accepted": 0,
      "failed": 0,
      "unknown": 0,
      "suppressed": 0,
      "canceled": 0
    },
    "createdAt": "2026-10-23T18:00:00.000Z",
    "updatedAt": "2026-10-23T18:00:00.000Z",
    "startedAt": null,
    "completedAt": null,
    "invitationUrl": null,
    "lastError": null
  }
}

Fetches a property's campaign summary and a cursor-paginated page of recipient outcomes so a client can monitor sending and investigate failures.

The console polls the summary during processing and can inspect recipient outcomes without exposing internal claim tokens or unsubscribe credentials.

Path parameters

idstringRequired

Campaign ID returned by the create or list operation; must belong to x-property-id.

Request headers

AuthorizationstringRequired

Bearer account-session token or API key. A read_write key is required for POST/PATCH, including preview requests.

x-property-idstringRequired

Property whose contacts, reservations, branding and campaigns are being accessed.

Query parameters

nextPagestringOptional

Opaque cursor returned by the previous response; maximum 4000 characters. Omit for the first page.

Response fields

campaign.idstring

Server-generated campaign identifier.

campaign.namestring

Internal campaign name.

campaign.subjectstring

Saved subject template; individual messages resolve guest variables.

campaign.statusstring

Durable job state. completed means processing finished, not confirmed inbox delivery; needs_attention requires operator review.

Allowed valuespreparingqueuedsendingcompletedneeds_attentioncanceled
campaign.totalinteger

Immutable selected-recipient count.

campaign.countsobject

Cached recipient totals refreshed by the background processor, including recipients still waiting to be materialized. They can briefly lag in-flight work. accepted records provider acceptance, not delivery/open tracking.

campaign.counts.*integer

All status counters are present.

Allowed valuespendingpreparingsendingacceptedfailedunknownsuppressedcanceled
campaign.createdAtstring · date-time

Creation time in ISO 8601 UTC.

campaign.updatedAtstring · date-time

Most recent job-state update in ISO 8601 UTC.

campaign.startedAtstring · date-time | null

Processing start time, or null before processing.

campaign.completedAtstring · date-time | null

Completion time, or null while unfinished.

campaign.invitationUrlstring | null

Booking invitation URL after promotion preparation; null when absent or not yet prepared.

campaign.lastErrorstring | null

Sanitized operational error, if present.

recipients[].idstring

Campaign-recipient record ID.

recipients[].emailstring

Normalized destination email.

recipients[].namestring

Snapshotted contact display name.

recipients[].statusstring

Recipient processing outcome.

Allowed valuespendingpreparingsendingacceptedfailedunknownsuppressedcanceled
recipients[].providerstring | null

Submitting mail provider, or null before a provider is selected.

Allowed valuesgmailmailjet
recipients[].acceptedAtstring · date-time | null

Provider acceptance time; does not establish delivery or opening.

recipients[].errorMessagestring | null

Sanitized failure or uncertainty explanation.

nextPagestring | null

Cursor for the next recipient page, or null when exhausted.

Behavior & constraints

  • Requires both reservations.view and reservations.manage for the selected property. Monetary audience filters additionally require financials.view, invoice.view or invoice.manage. Discount invitations require rates.manage.
  • Recipient pages contain at most 50 materialized records, ordered by creation time. The campaign total can exceed listed rows while the background processor prepares recipients. Follow nextPage for additional rows.
  • unknown means provider acceptance could not be confirmed; automatic resend is withheld to avoid duplicates. failed means a definite failure, suppressed means a promotional unsubscribe, and canceled means unsent work stopped by the operator.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/campaigns/campaign-example' \
  \
  -H 'Authorization: Bearer <access-token>' \
  \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "campaign": {
    "id": "campaign-example",
    "name": "A quiet-season invitation",
    "subject": "A little time away, {guestFirstName}",
    "status": "completed",
    "total": 1,
    "counts": {
      "pending": 0,
      "preparing": 0,
      "sending": 0,
      "accepted": 1,
      "failed": 0,
      "unknown": 0,
      "suppressed": 0,
      "canceled": 0
    },
    "createdAt": "2026-10-23T18:00:00.000Z",
    "updatedAt": "2026-10-23T18:00:00.000Z",
    "startedAt": null,
    "completedAt": "2026-10-23T18:00:10.000Z",
    "invitationUrl": null,
    "lastError": null
  },
  "recipients": [
    {
      "id": "recipient-example",
      "email": "alex@example.com",
      "name": "Alex Guest",
      "status": "accepted",
      "provider": "gmail",
      "acceptedAt": "2026-10-23T18:00:09.000Z",
      "errorMessage": null
    }
  ],
  "nextPage": null
}

Stops a campaign's remaining unsent work by persisting a cancellation state. Messages already accepted by the provider cannot be recalled.

The console's stop action uses this operation, then keeps displaying the final mixed outcomes of already sent and canceled recipients.

Path parameters

idstringRequired

Property-owned campaign ID.

Request headers

AuthorizationstringRequired

Bearer account-session token or API key. A read_write key is required for POST/PATCH, including preview requests.

x-property-idstringRequired

Property whose contacts, reservations, branding and campaigns are being accessed.

Body fields

actionstringRequired

The only supported campaign mutation.

Allowed valuescancel

Response fields

campaign.idstring

Server-generated campaign identifier.

campaign.namestring

Internal campaign name.

campaign.subjectstring

Saved subject template; individual messages resolve guest variables.

campaign.statusstring

Durable job state. completed means processing finished, not confirmed inbox delivery; needs_attention requires operator review.

Allowed valuespreparingqueuedsendingcompletedneeds_attentioncanceled
campaign.totalinteger

Immutable selected-recipient count.

campaign.countsobject

Cached recipient totals refreshed by the background processor, including recipients still waiting to be materialized. They can briefly lag in-flight work. accepted records provider acceptance, not delivery/open tracking.

campaign.counts.*integer

All status counters are present.

Allowed valuespendingpreparingsendingacceptedfailedunknownsuppressedcanceled
campaign.createdAtstring · date-time

Creation time in ISO 8601 UTC.

campaign.updatedAtstring · date-time

Most recent job-state update in ISO 8601 UTC.

campaign.startedAtstring · date-time | null

Processing start time, or null before processing.

campaign.completedAtstring · date-time | null

Completion time, or null while unfinished.

campaign.invitationUrlstring | null

Booking invitation URL after promotion preparation; null when absent or not yet prepared.

campaign.lastErrorstring | null

Sanitized operational error, if present.

Behavior & constraints

  • Requires both reservations.view and reservations.manage for the selected property. Monetary audience filters additionally require financials.view, invoice.view or invoice.manage. Discount invitations require rates.manage.
  • The processor rechecks cancellation before provider submission. Work already submitted or concurrently in flight may still complete. Already completed/canceled campaigns return their existing summary; a concurrent state update can return 409 and may be retried.
  • Cancellation does not delete the campaign, remove accepted outcomes or revoke an invitation promotion already created for it.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/campaigns/campaign-example' \
  \
  -H 'Authorization: Bearer <access-token>' \
  \
  -H 'x-property-id: <property-id>' \
  \
  -H 'Content-Type: application/json' \
  --data '{
  "action": "cancel"
}'
Example response
JSON
{
  "campaign": {
    "id": "campaign-example",
    "name": "A quiet-season invitation",
    "subject": "A little time away, {guestFirstName}",
    "status": "canceled",
    "total": 1,
    "counts": {
      "pending": 0,
      "preparing": 0,
      "sending": 0,
      "accepted": 0,
      "failed": 0,
      "unknown": 0,
      "suppressed": 0,
      "canceled": 1
    },
    "createdAt": "2026-10-23T18:00:00.000Z",
    "updatedAt": "2026-10-23T18:00:00.000Z",
    "startedAt": null,
    "completedAt": null,
    "invitationUrl": null,
    "lastError": null
  }
}

Displays a promotional-email unsubscribe confirmation page for a valid recipient link. Viewing the page does not itself unsubscribe the guest.

The footer of delivered campaign emails opens this page; a confirmation form submits POST to apply the unsubscribe.

Query parameters

tokenstringRequired

Opaque 43-character URL-safe token from the delivered email; do not construct it yourself.

Behavior & constraints

  • The opaque token in the recipient's email is the authority; no account token or x-property-id is needed. Treat the URL as private and do not log or publish its token.
  • Returns 400 HTML for an invalid or unknown link. Responses disable caching and referrer disclosure.
Request
cURL
curl 'https://api.wikiup.app/api/campaigns/unsubscribe?token=<email-link-token>'
Example response
text/html
<!doctype html><html>…Unsubscribe from promotional emails…confirmation form…</html>

Unsubscribes the email-link recipient from this property's promotional campaigns, including queued recipients not yet submitted to the provider.

Used by the unsubscribe confirmation form and mail clients' one-click unsubscribe requests. Reservation and other transactional messages are unaffected.

Query parameters

tokenstringRequired

Opaque token from the delivered campaign unsubscribe link.

Behavior & constraints

  • Uses the query token as authority and does not read a request body. Supports the standard one-click unsubscribe form POST. Repeated requests converge on the same property/email suppression.
  • Suppression applies only to this property and this normalized email. No guest or reservation is deleted. The response is an HTML confirmation, not JSON; invalid links return 400 HTML.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/campaigns/unsubscribe?token=<email-link-token>' \
  \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'List-Unsubscribe=One-Click'
Example response
text/html
<!doctype html><html>…You’re unsubscribed…Reservation messages are unaffected.…</html>

API Reference

Gift Cards

Create a card payment intent for purchasing a property gift card. Only the later confirm step issues the actual gift card after successful payment.

Hosted gift-card purchase widget.

Body fields

propertyIdstringRequired

Property issuing the gift card.

amountnumber | stringRequired

Gift card face value: $20–$1,000 in $20 increments.

senderNamestringOptional

Purchaser name.

senderEmailstringOptional

Purchaser email; required at confirmation.

recipientNamestringOptional

Recipient name.

recipientEmailstringOptional

Recipient email; required at confirmation.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Behavior & constraints

  • Amounts must be $20 increments from $20 through $1,000. Complete the card payment using the client secret, then call /api/gift-cards/confirm.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/gift-cards/intent' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","amount":100,"senderEmail":"alex@example.com","recipientEmail":"sam@example.com"}'
Response · 200
JSON
{
  "clientSecret": "pi_example_secret_example",
  "paymentIntentId": "pi_example",
  "currency": "usd",
  "stripeMode": "live"
}

Issue a gift card after checking the completed payment's property and face value, then attempt delivery to the recipient and a purchase notification to the inn.

Hosted gift-card purchase confirmation.

Body fields

propertyIdstringRequired

Property issuing the gift card.

amountnumber | stringRequired

Gift card face value: $20–$1,000 in $20 increments.

senderNamestringOptional

Purchaser name.

senderEmailstringRequired

Purchaser email; required at confirmation.

recipientNamestringOptional

Recipient name.

recipientEmailstringRequired

Recipient email; required at confirmation.

messagestringOptional

Personal gift message, used for preview and confirmation.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive
paymentIntentIdstringRequired

Succeeded PaymentIntent from /gift-cards/intent.

Response fields

giftCardNumberstring | nullOptional

Redeemable secret; show only to the purchaser/intended recipient.

emailSentboolean | nullOptional

Recipient delivery result; null on an already-issued replay.

Behavior & constraints

  • Returns 200 with the existing card for an already-issued PaymentIntent. A processing bank payment is not sufficient; gift-card purchases require succeeded.
  • The gift card remains issued if email delivery fails. Repeating this call does not resend the email.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/gift-cards/confirm' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","amount":100,"senderName":"Alex","senderEmail":"alex@example.com","recipientName":"Sam","recipientEmail":"sam@example.com","message":"Enjoy your stay!","paymentIntentId":"pi_example"}'
Response · 201
JSON
{
  "giftCardId": "giftcard_123",
  "giftCardNumber": "WIK-EXAMPLE-1234",
  "cardNumberLastFour": "1234",
  "amount": 100,
  "emailSent": true
}

Render a branded gift-card email preview without charging a card, issuing a redeemable gift card or sending email. Useful for the purchaser's review before checkout.

Hosted gift-card widget preview dialog.

Body fields

propertyIdstringRequired

Property issuing the gift card.

amountnumber | stringOptional

Gift card face value: $20–$1,000 in $20 increments. Defaults to 100 for previews.

senderNamestringOptional

Purchaser name.

senderEmailstringOptional

Purchaser email; required at confirmation.

recipientNamestringOptional

Recipient name.

recipientEmailstringOptional

Recipient email; required at confirmation.

messagestringOptional

Personal gift message, used for preview and confirmation.

Behavior & constraints

  • The preview uses a non-redeemable placeholder card number. Names are limited to 120 characters, email strings to 254 and the message to 2,000.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/gift-cards/preview' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","amount":100,"senderName":"Alex","recipientName":"Sam","recipientEmail":"sam@example.com","message":"Enjoy your stay!"}'
Response · 200
JSON
{
  "subject": "A gift for your next stay",
  "html": "<html>…</html>",
  "recipientEmail": "sam@example.com"
}

Look up a gift card by property and entered card number, returning its masked identifier, face value, remaining balance and status without redeeming it.

Gift-card balance lookup and checkout gift-card validation.

Body fields

propertyIdstringRequired

Issuing property.

giftCardNumberstringRequired

Full redeemable card number; keep private.

Response fields

statusstringOptional

Current gift-card state.

Allowed valuesActiveRedeemedVoidedExpired
balancenumberOptional

Amount in major currency units: 15 means $15.00 for USD.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/gift-cards/balance' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","giftCardNumber":"WIK-EXAMPLE-1234"}'
Response · 200
JSON
{
  "giftCardId": "giftcard_123",
  "cardNumberLastFour": "1234",
  "originalAmount": 100,
  "balance": 80,
  "currency": "usd",
  "status": "Active",
  "expiresAt": null
}

Debit a gift card and create its redemption record. For a reservation checkout, prefer the corresponding payment confirmation endpoint, which also coordinates the reservation payment ledger.

Standalone redemption API; reservation payment flows call the same redemption service as part of checkout.

Body fields

propertyIdstringRequired

Issuing property.

giftCardNumberstringRequired

Full card number authorizing redemption.

amountnumber | stringRequired

Positive requested redemption in major currency units.

reservationIdstringOptional

Optional associated reservation.

paymentReferenceIdstringOptional

Optional payment reference for reconciliation.

Behavior & constraints

  • This changes the stored gift-card balance. Do not use it as a pricing preview or repeatedly redeem after an uncertain response.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/gift-cards/redeem' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","giftCardNumber":"WIK-EXAMPLE-1234","amount":20}'
Response · 200
JSON
{
  "giftCardId": "giftcard_123",
  "redemptionId": "redemption_123",
  "amount": 20,
  "remainingBalance": 60,
  "cardNumberLastFour": "1234"
}

API Reference

Guest Chat

Start a website guest conversation and save its first message. Returns a private conversation token for subsequent reads, messages, and presence receipts. Innkeeper notification and eligible AI response processing happen after the initial message is saved.

Used by the public website chat entry point.

Body fields

propertyIdstringRequired

Publicly accessible property ID, up to 100 characters.

namestringRequired

Guest name, 1–120 characters.

emailstringRequired

Valid guest email, up to 254 characters; used for reply delivery.

messagestringRequired

First message, 1–4,000 characters.

aiConsentobjectOptional

Optional explicit AI preferences. Manual messaging works without AI consent.

aiConsent.versionstringOptional

Must match the current consent revision for permission to take effect.

Allowed values2026-10-16-v2
aiConsent.processingbooleanOptional

True permits AI processing under the current disclosure; false or omission does not grant permission.

aiConsent.knowledgebooleanOptional

True additionally permits eligible answers to be considered for reusable knowledge. Requires processing=true.

Response fields

conversation.statusstringOptional

Conversation state.

Allowed valuesopenclosed
messages[].senderstringOptional

Author of a persisted chat message.

Allowed valuesvisitorinnkeeperai
tokenstringOptional

Keep private and supply as x-chat-token on visitor conversation requests.

Behavior & constraints

  • New conversations are limited per property/email (3 per 24 hours) and, where available, per IP (10 per day); limits return 429. Continue an existing conversation instead of creating duplicates.
  • AI preferences are optional; present the current AI disclosure before requesting consent.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/chat/conversations' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"property_example","name":"Sam Taylor","email":"guest@example.com","message":"Is parking available?"}'
Response · 201
JSON
{
  "conversation": {
    "id": "conversation_example",
    "propertyId": "property_example",
    "visitorName": "Sam Taylor",
    "visitorEmail": "guest@example.com",
    "status": "open",
    "needsInnkeeper": true,
    "suggestedReply": null,
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "messages": [
    {
      "id": "message_example",
      "propertyId": "property_example",
      "conversationId": "conversation_example",
      "sender": "visitor",
      "body": "Is parking available?",
      "createdAt": "2026-10-22T17:00:00.000Z"
    }
  ],
  "token": "private_chat_token"
}

Read a guest conversation using its private chat token. Messages are ordered oldest first; the conversation includes the current reply/attention state.

Used by website chat polling and emailed guest chat links.

Path parameters

idstringRequired

Conversation ID.

Request headers

x-chat-tokenstringRequired

Private conversation token returned when starting chat, or supplied by the guest chat email link. This is not a Wikiup staff token.

Response fields

conversation.statusstringOptional

Conversation state.

Allowed valuesopenclosed
messages[].senderstringOptional

Author of a persisted chat message.

Allowed valuesvisitorinnkeeperai

Behavior & constraints

  • A staff Bearer token alone does not authorize this visitor endpoint. Use the inbox endpoints for staff access.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/chat/conversations/id_example' \
  -H "x-chat-token: $CHAT_TOKEN"
Response · 200
JSON
{
  "conversation": {
    "id": "conversation_example",
    "propertyId": "property_example",
    "visitorName": "Sam Taylor",
    "visitorEmail": "guest@example.com",
    "status": "open",
    "needsInnkeeper": true,
    "suggestedReply": null,
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "messages": [
    {
      "id": "message_example",
      "propertyId": "property_example",
      "conversationId": "conversation_example",
      "sender": "visitor",
      "body": "Is parking available?",
      "createdAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Send a guest message, update AI consent, or report a conversation. A normal message reopens the conversation, marks it for innkeeper attention, and clears a stale suggested reply.

Used by website chat messaging, AI preferences, and reporting.

Path parameters

idstringRequired

Conversation ID.

Request headers

x-chat-tokenstringRequired

Private conversation token returned when starting chat, or supplied by the guest chat email link. This is not a Wikiup staff token.

Body fields

actionstringOptional

Omit for a normal message; use consent or report for those actions.

Allowed valuesconsentreport
messagestringOptional

Required when sending a normal message, 1–4,000 characters.

reportstringOptional

Required for action=report, 1–1,000 characters.

aiConsentobjectOptional

Optional explicit AI preferences. Manual messaging works without AI consent.

aiConsent.versionstringOptional

Must match the current consent revision for permission to take effect.

Allowed values2026-10-16-v2
aiConsent.processingbooleanOptional

True permits AI processing under the current disclosure; false or omission does not grant permission.

aiConsent.knowledgebooleanOptional

True additionally permits eligible answers to be considered for reusable knowledge. Requires processing=true.

Response fields

conversation.statusstringOptional

Conversation state.

Allowed valuesopenclosed
messages[].senderstringOptional

Author of a persisted chat message.

Allowed valuesvisitorinnkeeperai

Behavior & constraints

  • Visitor messages are limited to 20 per conversation per 24 hours. Blocked senders cannot add messages.
  • Reports are shown in the property inbox; repeat reports within 24 hours return 429.
  • Withdrawing knowledge consent removes captured knowledge entries for the conversation; manual chat remains available.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/chat/conversations/id_example' \
  -H "x-chat-token: $CHAT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"message":"Thank you. Is there a parking fee?"}'
Response · 200
JSON
{
  "conversation": {
    "id": "conversation_example",
    "propertyId": "property_example",
    "visitorName": "Sam Taylor",
    "visitorEmail": "guest@example.com",
    "status": "open",
    "needsInnkeeper": true,
    "suggestedReply": null,
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "messages": [
    {
      "id": "message_example",
      "propertyId": "property_example",
      "conversationId": "conversation_example",
      "sender": "visitor",
      "body": "Is parking available?",
      "createdAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Record that the guest is online and optionally acknowledge staff/AI messages they have seen. Receipts help route replies to active chat or email without unnecessary duplicate delivery.

Used while the public chat window is active to acknowledge visible replies.

Path parameters

idstringRequired

Conversation ID.

Request headers

x-chat-tokenstringRequired

Private conversation token returned when starting chat, or supplied by the guest chat email link. This is not a Wikiup staff token.

Body fields

seenMessageIdsstring[]Optional

Up to 50 IDs, each at most 100 characters. Messages must belong to this conversation and cannot be visitor-authored; defaults to [].

Request
cURL
curl -X POST 'https://api.wikiup.app/api/chat/conversations/id_example/presence' \
  -H "x-chat-token: $CHAT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"seenMessageIds":[]}'
Response · 204
HTTP
No response body.

List all guest chat conversations for the selected property, newest update first. needsInnkeeper indicates attention is needed; suggestedReply contains any available draft suggestion.

Used by the console Guest chat inbox and native innkeeper GuestChatView.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Response fields

conversations[].statusstringOptional

Conversation state.

Allowed valuesopenclosed

Behavior & constraints

  • Requires reservations.view. This collection is not paginated.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/chat/inbox' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "conversations": [
    {
      "id": "conversation_example",
      "propertyId": "property_example",
      "visitorName": "Sam Taylor",
      "visitorEmail": "guest@example.com",
      "status": "open",
      "needsInnkeeper": true,
      "suggestedReply": null,
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Read a property guest conversation and its complete chronological message history. Reading this endpoint alone does not acknowledge the inbox item; submit action=read with its updatedAt to do that safely.

Used by the console Guest chat inbox and native innkeeper GuestChatView.

Path parameters

idstringRequired

Conversation ID belonging to the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Response fields

conversation.statusstringOptional

Conversation state.

Allowed valuesopenclosed
messages[].senderstringOptional

Author of a persisted chat message.

Allowed valuesvisitorinnkeeperai

Behavior & constraints

  • Requires reservations.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/chat/inbox/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "conversation": {
    "id": "conversation_example",
    "propertyId": "property_example",
    "visitorName": "Sam Taylor",
    "visitorEmail": "guest@example.com",
    "status": "open",
    "needsInnkeeper": true,
    "suggestedReply": null,
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "messages": [
    {
      "id": "message_example",
      "propertyId": "property_example",
      "conversationId": "conversation_example",
      "sender": "visitor",
      "body": "Is parking available?",
      "createdAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Act on a guest conversation: send a reply, acknowledge it, manage suggestions/learning, retry email, or block/report the sender. Sending persists the reply before attempting delivery and optional knowledge capture; inspect the delivery fields rather than assuming every side effect succeeded.

Used by the console Guest chat inbox and native innkeeper GuestChatView.

Path parameters

idstringRequired

Conversation ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

actionstringRequired

Operation to perform.

Allowed valuessendrejectreadlearnemailsuggestwithdrawAIblockunblockreport
messagestringOptional

Required for send; 1–4,000 characters.

expectedUpdatedAtdate-timeOptional

Required for read; use conversation.updatedAt so newly arrived messages are not accidentally marked read.

messageIdstringOptional

Required for learn or email; ID of the previously sent staff reply being retried.

oneTimeExceptionbooleanOptional

Defaults to true. Set false, with knowledge consent, to allow a sent answer to be considered for reusable knowledge.

reportstringOptional

Required for report; 1–1,000 characters.

aiConsentobjectOptional

Optional explicit AI preferences. Manual messaging works without AI consent.

aiConsent.versionstringOptional

Must match the current consent revision for permission to take effect.

Allowed values2026-10-16-v2
aiConsent.processingbooleanOptional

True permits AI processing under the current disclosure; false or omission does not grant permission.

aiConsent.knowledgebooleanOptional

True additionally permits eligible answers to be considered for reusable knowledge. Requires processing=true.

Response fields

deliverystring | nullOptional

Reply delivery outcome; null for actions that do not send.

Allowed valueschatemailemail_failed
knowledgeSavedbooleanOptional

False means optional knowledge capture failed; retry learn with learningMessageId.

emailDeliveredbooleanOptional

False means reply delivery failed; retry email with emailMessageId. True can also mean an active chat receipt avoided email.

conversation.statusstringOptional

Conversation state.

Allowed valuesopenclosed
messages[].senderstringOptional

Author of a persisted chat message.

Allowed valuesvisitorinnkeeperai

Behavior & constraints

  • Requires reservations.view, plus reservations.manage for every action except read.
  • reject clears a suggested reply; suggest requests a new one. withdrawAI prevents future staff-authorized AI use. block/unblock applies to the sender across this property's conversations.
  • For a partially successful send, use the returned retry IDs rather than sending the same message again.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/chat/inbox/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"action":"send","message":"Yes, complimentary parking is available.","oneTimeException":true}'
Response · 200
JSON
{
  "conversation": {
    "id": "conversation_example",
    "propertyId": "property_example",
    "visitorName": "Sam Taylor",
    "visitorEmail": "guest@example.com",
    "status": "open",
    "needsInnkeeper": false,
    "suggestedReply": null,
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "messages": [
    {
      "id": "message_example",
      "propertyId": "property_example",
      "conversationId": "conversation_example",
      "sender": "visitor",
      "body": "Is parking available?",
      "createdAt": "2026-10-22T17:00:00.000Z"
    },
    {
      "id": "reply_example",
      "propertyId": "property_example",
      "conversationId": "conversation_example",
      "sender": "innkeeper",
      "body": "Yes, complimentary parking is available.",
      "createdAt": "2026-10-22T17:00:00.000Z"
    }
  ],
  "knowledgeSaved": true,
  "emailDelivered": true,
  "delivery": "email",
  "learningMessageId": null,
  "emailMessageId": null
}

Delete a guest chat conversation and its associated chat history/knowledge records. This permanently removes the conversation rather than marking it read or hiding it.

Used by the console Guest chat inbox and native innkeeper GuestChatView.

Path parameters

idstringRequired

Conversation ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires reservations.view and reservations.manage.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/chat/inbox/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

Page through captured guest question/answer candidates for staff review, newest first. Search matches question or answer text case-insensitively.

Used by the console Guest Questions review grid.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

searchstringOptional

Optional text search, trimmed to 120 characters.

pagestringOptional

Opaque nextPage from the preceding response; omit for the first page.

Response fields

questionsArray<object>Required

Review records matching status filter.

questions[]objectRequired

Private property knowledge review record.

questions[].idstringRequired

Question identifier.

questions[].propertyIdstringRequired

Owning property identifier.

questions[].questionstringRequired

Question text.

questions[].answerstringRequired

Proposed or reviewed answer text.

questions[].status"pending" | "approved" | "rejected"Required

Review outcome.

questions[].sourceConversationIdstringRequired

Origin conversation identifier; staff-only.

questions[].sourceMessageIdstringRequired

Origin message identifier; staff-only.

questions[].createdAtstringRequired

Creation timestamp.

questions[].updatedAtstringRequired

Last change timestamp.

questions[].publicReviewVersionstring | nullOptional

Review disclosure version accepted by staff, or null/unset before review.

nextPagestring | nullRequired

Opaque Onyx page token; null at the end.

Behavior & constraints

  • Requires reservations.view. Pages contain at most 50 records; nextPage=null marks the end.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/chat/questions' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "questions": [
    {
      "id": "question_example",
      "propertyId": "property_example",
      "question": "What time is check-in?",
      "answer": "Check-in starts at 4 PM.",
      "status": "pending",
      "sourceConversationId": "conversation_example",
      "sourceMessageId": "message_example",
      "createdAt": "2027-02-09T16:00:00-08:00",
      "updatedAt": "2027-02-09T16:00:00-08:00",
      "publicReviewVersion": null
    }
  ],
  "nextPage": null
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

Edit and review a captured question/answer for future public reuse. Approval requires an explicit suitability confirmation and an eligible source conversation; duplicate normalized pairs are rejected.

Used by the console Guest Questions review dialog.

Path parameters

idstringRequired

Guest question ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

questionstringOptional

Nonempty question, up to 1,000 characters; omitted preserves current text.

answerstringOptional

Nonempty answer, up to 4,000 characters; omitted preserves current text.

statusstringOptional

Review result; defaults to pending when omitted, including text-only edits.

Allowed valuespendingapprovedrejected
publicUseConfirmedbooleanOptional

Must be true for approved; confirms the answer is suitable for public reuse.

Behavior & constraints

  • Requires reservations.manage. Approval also runs public-content and conversation-consent checks. A duplicate question/answer returns 409.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/chat/questions/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"status":"approved","publicUseConfirmed":true}'
Response · 200
JSON
{
  "question": {
    "id": "question_example",
    "propertyId": "property_example",
    "question": "Is parking available?",
    "answer": "Complimentary parking is available.",
    "status": "approved"
  }
}

Remove a captured knowledge pair and any duplicate entries with the same normalized question/answer in this property. The source chat conversation is retained.

Used by the console Guest Questions review grid.

Path parameters

idstringRequired

Guest question ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires reservations.manage.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/chat/questions/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

API Reference

Guest Notifications

Prepare a selectable audience of reservation guests for a bulk announcement or room-ready message. Dates and audience are evaluated in the property's time zone.

Console timeline guest notification composer.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

audiencestringOptional

Arrival/stay audience.

Allowed valuestodayupcomingrecent
fromstringOptional

Range start YYYY-MM-DD.

tostringOptional

Range end YYYY-MM-DD; maximum span 366 days.

Request
cURL
curl 'https://api.wikiup.app/api/reservations/guest-notifications?audience=today' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "audience": "today",
  "date": "2027-06-10",
  "timeZone": "America/Los_Angeles",
  "subject": "Room is Ready",
  "message": "<p>Your room is ready.</p>",
  "items": []
}

Send a branded announcement or room-ready email to the selected reservations. Validates each recipient and returns per-reservation successes/failures, so partial delivery is not mistaken for total success.

Console timeline guest notification composer.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

audiencestringRequired

Audience used to select guests.

Allowed valuestodayupcomingrecent
fromstringOptional

Range start YYYY-MM-DD when using a range.

tostringOptional

Range end YYYY-MM-DD.

reservationIdsstring[]Required

Selected reservation IDs; maximum 100.

modestringRequired

roomReady is only valid for today's arrivals.

Allowed valuescustomroomReady
subjectstringOptional

Required for custom; maximum 200 characters.

messagestringOptional

Required custom email content; maximum 200,000 characters.

includeReservationDetailsbooleanOptional

Include the stay summary in a custom announcement.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/guest-notifications' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"audience":"today","reservationIds":["reservation_123"],"mode":"roomReady"}'
Response · 200
JSON
{
  "sent": [],
  "failed": []
}

Send the property's room-ready email for an upcoming reservation arriving today in the property timezone. Persist the sent timestamp on the reservation and return the existing receipt without resending when already sent.

Reservation timeline Notify: Room is Ready action.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Response fields

roomReadyEmailSentAtstringOptional

Successful delivery timestamp, also included in normal reservation reads.

alreadySentbooleanOptional

True when the existing delivery receipt was returned without sending again.

Behavior & constraints

  • Requires reservations.manage. This POST has no request body.
  • Returns 409 for arrivals on another property-local date or reservations that have already checked in. Missing guest email returns 400.
  • The duplicate-send guard is shared with guest and bulk room-ready sends. Template test emails do not record a reservation receipt.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/room-ready' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "roomReadyEmailSentAt": "2026-11-02T18:00:00.000Z",
  "alreadySent": false
}

API Reference

Guest Portal

Request a new guest portal sign-in email using the property's ID, reservation confirmation number and guest email. The response is deliberately identical whether or not a matching reservation is found.

Public guest portal recovery/sign-in form in lib/guest-portal.ts.

Body fields

propertyIdstringRequired

Property for the reservation.

confirmationNumberstringRequired

Guest-facing reservation confirmation number.

emailstringRequired

Guest email stored on the reservation.

Behavior & constraints

  • accepted:true acknowledges the request; it does not confirm account existence or email delivery.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/access/request' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"PROPERTY_ID","confirmationNumber":"WUR-EXAMPLE","email":"alex@example.com"}'
Response · 202
JSON
{
  "accepted": true
}

Exchange a signed guest portal access-link token for a reservation-scoped guest session. Use the returned sessionToken as the Bearer credential on other guest portal endpoints.

Public guest page exchanges the emailed link before loading the portal.

Body fields

tokenstringRequired

Access token from the guest portal link.

Response fields

sessionTokenstringOptional

Private credential scoped to this guest reservation.

expiresAtstringOptional

Session expiry in ISO timestamp format.

Behavior & constraints

  • An innkeeper session token is not interchangeable with a guest session. Do not expose these credentials in analytics or logs.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/access/exchange' \
  -H 'Content-Type: application/json' \
  -d '{"token":"ACCESS_GRANT"}'
Response · 200
JSON
{
  "sessionToken": "GUEST_SESSION_TOKEN",
  "expiresAt": "2027-06-12T18:00:00.000Z",
  "propertyId": "PROPERTY_ID",
  "reservationId": "reservation_123",
  "guestId": "guest_123"
}

Load the signed-in guest's property, reservation summary, guest contact, check-in-guide progress and allowed actions. Also records the portal visit and updates session activity.

Public guest page server-side context loader and hosted portal.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Response fields

reservation.statusstring | nullOptional

Persisted stay status.

Allowed valuesupcomingcheckedincheckedoutcanceled
allowedActionsobjectOptional

Server-derived controls for this stay; use them rather than inferring editability from dates alone.

Request
cURL
curl 'https://api.wikiup.app/api/guest-portal/context' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN'
Response · 200
JSON
{
  "property": {
    "id": "PROPERTY_ID",
    "name": "Example Inn",
    "timeZone": "America/Los_Angeles"
  },
  "reservation": {
    "id": "reservation_123",
    "confirmationNumber": "WUR-EXAMPLE",
    "status": "upcoming",
    "start": "2027-06-10T07:00:00.000Z",
    "end": "2027-06-12T07:00:00.000Z",
    "roomId": "room_123",
    "roomName": "Garden room",
    "eta": "16:00",
    "adultsCount": 2,
    "childrenCount": 0,
    "petsCount": 0,
    "totalGuests": 2
  },
  "guest": {
    "id": "guest_123",
    "firstName": "Alex",
    "lastName": "Morgan",
    "email": "alex@example.com",
    "phone": "+15555550123"
  },
  "checkinGuideProgress": null,
  "allowedActions": {
    "canUpdateEta": true,
    "canCancel": true,
    "canModify": true,
    "canMessageConcierge": true
  }
}

Save the guest's expected arrival time in the inn's local time zone. The guest may communicate a later arrival, but cannot use ETA editing to bypass an enabled paid early check-in policy.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

etastring | nullRequired

HH:mm preferred; 12-hour input is normalized. Must be at or after the purchased early time or normal policy time. null resets to the applicable default.

Behavior & constraints

  • Default is the purchased early check-in time, otherwise property check-in policy, otherwise 16:00. Treat HH:mm as property-local wall time, not UTC.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/guest-portal/reservation/eta' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"eta":"22:30"}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "eta": "22:30"
}

Return available early check-in and late check-out options, current selections, local times and whether each can still be added or removed. Also returns the effective check-in/check-out times and minimum ETA.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Response fields

options[].kindstringOptional

Arrival or departure option.

Allowed valuesearlylate
options[].selectedbooleanOptional

Whether this reservation already includes the option.

options[].canChangebooleanOptional

Whether the opposite selection is currently permitted.

options[].amountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

options[].timestring | nullOptional

Property-local HH:mm, not a UTC timestamp.

Behavior & constraints

  • Purchased selections remain visible even if the property later disables selling that option. Removals close at 11am property time on the corresponding arrival/departure day.
Request
cURL
curl 'https://api.wikiup.app/api/guest-portal/reservation/arrival-departure' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN'
Response · 200
JSON
{
  "checkinTime": "16:00",
  "checkoutTime": "11:00",
  "minimumEta": "16:00",
  "earlyCheckIn": false,
  "eta": "16:00",
  "estimatedCheckout": null,
  "options": [
    {
      "kind": "early",
      "label": "Early check-in",
      "selected": false,
      "canChange": true,
      "amount": 15,
      "time": "13:00"
    },
    {
      "kind": "late",
      "label": "Late check-out",
      "selected": false,
      "canChange": true,
      "amount": 15,
      "time": "12:00"
    }
  ]
}

Quote adding or removing one arrival/departure option, or prepare the quoted purchase payment form with action:payment and quoteId. Quotes include the invoice breakdown and saved-card display details; payment preparation returns a single reusable intent without charging it.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

kindstringOptional

Required when quoting an option change.

Allowed valuesearlylate
enabledbooleanOptional

Required with kind: true to add; false to remove.

actionstringOptional

Use payment to prepare checkout for an existing quote.

Allowed valuespayment
quoteIdstringOptional

Required when action is payment.

Response fields

clientSecretstringOptional

Payment intent client secret for the payment preparation variant.

paymentPublicKeystringOptional

Publishable key matching the payment environment.

savedPaymentMethodIdstring | nullOptional

Saved payment method available for this reservation, if any.

chargeAmountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

refundAmountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

Behavior & constraints

  • The quote expires after 10 minutes. Quote requests do not charge or refund. POST with action:payment and quoteId prepares a payment intent; the guest completes saved-card or new-card payment before PATCH verifies success and adds the extra.
  • Removal before 11am refunds only the paid portion of the removed option. Adding early check-in after check-in is forbidden; unavailable or unchanged selections return an error.
  • Unlike guest modification/cancellation quotes, arrival/departure amounts use major currency units.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/arrival-departure' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"early","enabled":true}'
Response · 200
JSON
{
  "quoteId": "quote_123",
  "chargeAmount": 15,
  "refundAmount": 0,
  "currency": "usd"
}

Confirm the arrival/departure quote. Prepared payments are verified as succeeded before adding an extra; legacy saved-card charges require explicit authorization. Removal refunds eligible paid funds. The reservation's times and invoice are updated, and a branded confirmation email is attempted.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

quoteIdstringRequired

Quote from the POST step for this session and reservation.

authorizeChargebooleanOptional

Must be true when the quote chargeAmount is positive.

Behavior & constraints

  • Expired/stale quotes return 409; request a new quote. Replaying a confirmed quote returns current options without repeating the charge/refund or email.
  • Successful payment is retained if email delivery fails; do not repeat the purchase to resend an email.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/guest-portal/reservation/arrival-departure' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_123","authorizeCharge":true}'
Response · 200
JSON
{
  "checkinTime": "13:00",
  "checkoutTime": "11:00",
  "minimumEta": "13:00",
  "earlyCheckIn": true,
  "eta": "13:00",
  "estimatedCheckout": null,
  "options": [
    {
      "kind": "early",
      "label": "Early check-in",
      "selected": true,
      "canChange": true,
      "amount": 15,
      "time": "13:00"
    }
  ]
}

Read the reservation-scoped guest conversation, including visible guest and staff replies. This uses the authenticated reservation context rather than a caller-supplied guest ID.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Response fields

propertyEmailstringRequired

Property mailbox address.

guestEmailstringRequired

Guest participant address.

messagesArray<object>Required

Participant-filtered messages sorted oldest first.

messages[]objectRequired

Email message projected by the messaging service.

messages[].idstringRequired

Provider message identifier.

messages[].textstringRequired

Plain-text content, or a snippet when format=metadata.

messages[].htmlstringOptional

Rendered-source HTML when available with format=full. Sanitize/isolate before rendering; absent for metadata.

messages[].sender"me" | "guest"Required

me is the property mailbox; guest is the other participant.

messages[].datestringRequired

Original email Date header; includes an offset and may be RFC 2822 rather than ISO 8601. Display in the property time zone.

messages[].fromstringRequired

From header; may contain display name and email.

messages[].tostringOptional

To header.

messages[].replyTostringOptional

Reply-To header; may be empty.

messages[].unreadbooleanRequired

Whether the provider marks the message unread.

messages[].subjectstringRequired

Email subject.

messages[].threadIdstringOptional

Provider thread ID when included.

messages[].isDraftbooleanOptional

Whether this provider record is a draft.

messages[].draftIdstringOptional

Draft identifier when resolved.

Request
cURL
curl 'https://api.wikiup.app/api/guest-portal/messages' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN'
Response · 200
JSON
{
  "propertyEmail": "hotel@example.com",
  "guestEmail": "guest@example.com",
  "messages": [
    {
      "id": "message_example",
      "text": "Your room is ready.",
      "html": "<p>Your room is ready.</p>",
      "sender": "me",
      "date": "Tue, 9 Feb 2027 16:00:00 -0800",
      "from": "Example Hotel <hotel@example.com>",
      "to": "guest@example.com",
      "replyTo": "hotel@example.com",
      "unread": false,
      "subject": "Your room is ready",
      "threadId": "thread_example",
      "isDraft": false
    }
  ]
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

Email the guest's reservation-scoped message to the property's concierge mailbox with the guest as reply-to, and record delivery in the guest portal audit history.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

bodyTextstringRequired

Non-empty message text, at most 4,000 characters.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/messages' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"bodyText":"We expect to arrive around 9pm."}'
Response · 200
JSON
{
  "accepted": true,
  "threadId": null,
  "messageId": "message_123"
}

Record the guest viewing or completing the self check-in guide, including how many steps they have read. Staff can see this progress on the reservation.

Hosted self check-in guide associated with the guest portal.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

eventTypestringRequired

Guide interaction.

Allowed valuesviewedprogresscompleted
stepsReadCountinteger | nullOptional

Number of steps read.

totalStepsCountinteger | nullOptional

Total guide steps presented.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/checkin-guide-progress' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"eventType":"completed","stepsReadCount":4,"totalStepsCount":4}'
Response · 204
HTTP
(empty response body)

Join the waitlist for alternative dates or a different room using the authenticated guest's existing contact and reservation. Does not change the current reservation.

Guest modification flow when the requested stay is unavailable.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

checkInstringRequired

Requested arrival YYYY-MM-DD.

checkOutstringRequired

Requested departure YYYY-MM-DD, later than checkIn.

roomIdstring | nullOptional

Preferred room, or null for no preference.

notesstring | nullOptional

Optional notes, at most 4,000 characters.

Behavior & constraints

  • Name, email, guest count and original reservation are taken from the authenticated context; do not submit these as extra fields.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/waitlist' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"checkIn":"2027-06-11","checkOut":"2027-06-13","roomId":"room_456"}'
Response · 201
JSON
{
  "joined": true
}

Quote a guest change of room or dates under the property's rescheduling policy, with availability, fees, refunds and alternative-room pricing. Does not modify the booking or collect money.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

startstringOptional

Check-in date, YYYY-MM-DD.

endstringOptional

Check-out date, YYYY-MM-DD; must follow start.

roomIdstring | nullOptional

New room, or omit to keep the existing room.

adultsCountinteger | nullOptional

Current adult count; guest count changes are not supported by this rescheduling flow.

childrenCountinteger | nullOptional

Current children count; unsupported changes are rejected.

petsCountinteger | nullOptional

Current pet count; unsupported changes are rejected.

addOnsobject[] | nullOptional

Omit or pass an empty array. Existing extras are retained; nonempty selections are rejected. Use arrival-departure to manage timing options.

Response fields

financialsobjectOptional

All monetary values in this quote are integer cents.

expiresAtstringOptional

ISO quote expiration.

Behavior & constraints

  • Display the quote for confirmation. If chargeAmount > 0, create a payment intent and complete payment before confirm. If no charge is due, call confirm directly.
  • Quotes are session/reservation-bound, expire and are revalidated. A quote is not an availability hold; honor allowed:false and explanatory messages.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/modify/quote' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"start":"2027-06-11","end":"2027-06-13","roomId":"room_123"}'
Response · 200
JSON
{
  "quoteId": "quote_123",
  "allowed": true,
  "expiresAt": "2027-06-01T12:10:00.000Z",
  "financials": {
    "feeAmount": 0,
    "chargeAmount": 0,
    "refundAmount": 1500,
    "netChange": -1500
  },
  "changeSummary": [
    "Stay dates changed"
  ],
  "alternativeRooms": []
}

Prepare payment of the positive amount due on a guest modification quote. Reuses an eligible existing intent or returns null intent/client secret when no payment is required.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

quoteIdstringRequired

Allowed, unexpired quote from this flow.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Response fields

amountintegerOptional

Integer minor units: 1500 means $15.00 for USD.

Behavior & constraints

  • Use the returned public key/environment to confirm payment client-side, then pass paymentIntentId to the flow's confirm endpoint.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/modify/payment-intent' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_123"}'
Response · 200
JSON
{
  "paymentIntentId": "pi_example",
  "clientSecret": "pi_example_secret_example",
  "amount": 1500,
  "stripeMode": "live",
  "paymentPublicKey": "pk_live_example"
}

Commit an approved guest rescheduling quote, verify any required payment, apply the new room/dates and settle refunds. Sends the reservation update notifications after the change.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

quoteIdstringRequired

Quote from this flow and guest session.

paymentIntentIdstring | nullOptional

Required when the quote needs an additional payment.

Response fields

financialsobjectOptional

chargeCollectedAmount and refundIssuedAmount are major currency units in this confirmation response (unlike the quote).

Behavior & constraints

  • Changed prices, availability, payment state or expired quotes can produce 409; obtain a fresh quote rather than retrying an obsolete decision.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/modify/confirm' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_123"}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "status": "upcoming",
  "financials": {
    "chargeCollectedAmount": 0,
    "refundIssuedAmount": 15
  },
  "updatedReservation": {
    "start": "2027-06-11",
    "end": "2027-06-13",
    "roomId": "room_123"
  }
}

Quote guest cancellation under the property's grace period and cutoff rules, separating lodging and add-on refunds and any unpaid cancellation fee. Does not cancel the stay yet.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

reasonstring | nullOptional

Optional cancellation reason.

Response fields

financialsobjectOptional

All monetary values in this quote are integer cents, including feeAmount, chargeAmount, refundAmount, stayRefundAmount and addOnRefundAmount.

Behavior & constraints

  • Display the quote for confirmation. If chargeAmount > 0, create a payment intent and complete payment before confirm. If no charge is due, call confirm directly.
  • Quotes are session/reservation-bound, expire and are revalidated. A quote is not an availability hold; honor allowed:false and explanatory messages.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/cancel/quote' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Travel plans changed"}'
Response · 200
JSON
{
  "quoteId": "quote_123",
  "allowed": true,
  "expiresAt": "2027-06-01T12:10:00.000Z",
  "financials": {
    "feeAmount": 0,
    "chargeAmount": 0,
    "refundAmount": 1500,
    "netChange": -1500
  },
  "messages": []
}

Prepare payment of the positive amount due on a guest cancellation quote. Reuses an eligible existing intent or returns null intent/client secret when no payment is required.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

quoteIdstringRequired

Allowed, unexpired quote from this flow.

paymentModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Response fields

amountintegerOptional

Integer minor units: 1500 means $15.00 for USD.

Behavior & constraints

  • Use the returned public key/environment to confirm payment client-side, then pass paymentIntentId to the flow's confirm endpoint.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/cancel/payment-intent' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_123"}'
Response · 200
JSON
{
  "paymentIntentId": "pi_example",
  "clientSecret": "pi_example_secret_example",
  "amount": 1500,
  "stripeMode": "live",
  "paymentPublicKey": "pk_live_example"
}

Commit guest cancellation, verify payment of any remaining fee, issue the quoted lodging/add-on refunds, cancel the stay and send cancellation notifications.

Used by the hosted guest portal embedded in the public site's guest page.

Request headers

AuthorizationstringRequired

Bearer followed by the guest sessionToken returned by /api/guest-portal/access/exchange. This is not an innkeeper access token.

Body fields

quoteIdstringRequired

Quote from this flow and guest session.

paymentIntentIdstring | nullOptional

Required when the quote needs an additional payment.

Response fields

refundIssuedAmountintegerOptional

Refund amount in cents. chargeCollectedAmount is also cents.

Behavior & constraints

  • Changed prices, availability, payment state or expired quotes can produce 409; obtain a fresh quote rather than retrying an obsolete decision.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guest-portal/reservation/cancel/confirm' \
  -H 'Authorization: Bearer YOUR_GUEST_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_123"}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "status": "canceled",
  "chargeCollectedAmount": 0,
  "refundIssuedAmount": 1500,
  "refundPaymentIds": [
    "payment_refund_123"
  ],
  "canceledAt": "2027-06-01T12:01:00.000Z"
}

API Reference

Guests

Search the property's guest directory by name, email or phone, with cursor pagination and optional exact/prefix filters. Use the returned nextToken unchanged to retrieve the next page.

Console guest directory and guest picker; native reservation guest search.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

searchstringOptional

Name/email text, or a phone-like string for normalized phone search.

filtersstringOptional

URL-encoded JSON map, e.g. {"email":[{"operator":"EQUAL","value":"alex@example.com"}]}. Supported operators: STARTS_WITH, EQUAL, eq, equals.

nextTokenstringOptional

Opaque cursor from the previous response.

pageSizeintegerOptional

Page size, default 50.

sortFieldstringOptional

Guest field to order by, such as firstName, lastName or email.

sortDirstringOptional

Sort direction.

Allowed valuesascdesc
Request
cURL
curl 'https://api.wikiup.app/api/guests?search=Alex&pageSize=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "data": [
    {
      "id": "guest_123",
      "propertyId": "PROPERTY_ID",
      "firstName": "Alex",
      "lastName": "Morgan",
      "email": "alex@example.com",
      "phone": "+15555550123",
      "blocked": false
    }
  ],
  "nextToken": null
}

Create a guest contact in the selected property for later reservation assignment. Does not create a reservation or send a booking email.

Staff reservation and guest management API.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

firstNamestringRequired

Guest's given name.

lastNamestring | nullOptional

Family name.

emailstring | nullOptional

Contact address; normalized to lowercase.

phonestring | nullOptional

Guest contact phone.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/guests' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Alex","lastName":"Morgan","email":"alex@example.com","phone":"+15555550123"}'
Response · 201
JSON
{
  "id": "guest_123",
  "propertyId": "PROPERTY_ID",
  "firstName": "Alex",
  "lastName": "Morgan",
  "email": "alex@example.com",
  "phone": "+15555550123",
  "blocked": false
}

Retrieve one property-owned guest and its related reservations for the guest detail page.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Request
cURL
curl 'https://api.wikiup.app/api/guests/guest_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "id": "guest_123",
  "propertyId": "PROPERTY_ID",
  "firstName": "Alex",
  "lastName": "Morgan",
  "email": "alex@example.com",
  "phone": "+15555550123",
  "blocked": false,
  "reservations": [
    {
      "id": "reservation_123",
      "propertyId": "PROPERTY_ID",
      "roomId": "room_123",
      "title": "Alex Morgan",
      "type": "reservation",
      "status": "upcoming",
      "start": "2027-06-10T07:00:00.000Z",
      "end": "2027-06-12T07:00:00.000Z",
      "confirmationNumber": "WUR-EXAMPLE"
    }
  ]
}

Update guest contact details or the booking block. Blocking prevents future online bookings matching this guest's identity; it does not cancel existing stays.

Staff reservation and guest management API.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

idstringRequired

Guest to update; prefer the /guests/{id} route.

Body fields

firstNamestringOptional

Guest's given name.

lastNamestring | nullOptional

Family name.

emailstring | nullOptional

Contact address; normalized to lowercase.

phonestring | nullOptional

Guest contact phone.

blockedbooleanOptional

Prevent this guest from booking; requires reservations.manage.

reasonstring | nullOptional

Reason for the booking block; required when blocking a guest.

Request
cURL
curl -X PUT 'https://api.wikiup.app/api/guests?id=guest_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Alex","phone":"+15555550124"}'
Response · 200
JSON
{
  "id": "guest_123",
  "propertyId": "PROPERTY_ID",
  "firstName": "Alex",
  "lastName": "Morgan",
  "email": "alex@example.com",
  "phone": "+15555550124",
  "blocked": false
}

Update guest contact details or the booking block. Blocking prevents future online bookings matching this guest's identity; it does not cancel existing stays.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

firstNamestringOptional

Guest's given name.

lastNamestring | nullOptional

Family name.

emailstring | nullOptional

Contact address; normalized to lowercase.

phonestring | nullOptional

Guest contact phone.

blockedbooleanOptional

Prevent this guest from booking; requires reservations.manage.

reasonstring | nullOptional

Reason for the booking block; required when blocking a guest.

Request
cURL
curl -X PUT 'https://api.wikiup.app/api/guests/guest_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Alex","phone":"+15555550124"}'
Response · 200
JSON
{
  "id": "guest_123",
  "propertyId": "PROPERTY_ID",
  "firstName": "Alex",
  "lastName": "Morgan",
  "email": "alex@example.com",
  "phone": "+15555550124",
  "blocked": false
}

List the selected guest's reservations in the active property for the guest's stay history.

Console guest detail/history view.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Request
cURL
curl 'https://api.wikiup.app/api/guests/guest_123/reservations' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "reservations": [
    {
      "id": "reservation_123",
      "propertyId": "PROPERTY_ID",
      "roomId": "room_123",
      "title": "Alex Morgan",
      "type": "reservation",
      "status": "upcoming",
      "start": "2027-06-10T07:00:00.000Z",
      "end": "2027-06-12T07:00:00.000Z",
      "confirmationNumber": "WUR-EXAMPLE"
    }
  ]
}

Load the guest's email conversation from the property's connected Gmail mailbox, optionally as full messages rather than metadata.

Console inbox/guest message composer and native iOS conversation view.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

pageSizeintegerOptional

Requested message page size.

pageTokenstringOptional

Gmail page token from the preceding response.

formatstringOptional

Response detail; defaults to metadata.

Allowed valuesmetadatafull
recentstringOptional

Use the recent-message lookup.

Allowed valuestruefalse
emailstringOptional

Override conversation address. If the guest ID is absent, this can create a guest contact.

guestNamestringOptional

Name for a contact created during lookup.

Response fields

messagesArray<object>Required

Messages returned by the requested provider mode.

messages[]objectRequired

Email message projected by the messaging service.

messages[].idstringRequired

Provider message identifier.

messages[].textstringRequired

Plain-text content, or a snippet when format=metadata.

messages[].htmlstringOptional

Rendered-source HTML when available with format=full. Sanitize/isolate before rendering; absent for metadata.

messages[].sender"me" | "guest"Required

me is the property mailbox; guest is the other participant.

messages[].datestringRequired

Original email Date header; includes an offset and may be RFC 2822 rather than ISO 8601. Display in the property time zone.

messages[].fromstringRequired

From header; may contain display name and email.

messages[].tostringOptional

To header.

messages[].replyTostringOptional

Reply-To header; may be empty.

messages[].unreadbooleanRequired

Whether the provider marks the message unread.

messages[].subjectstringRequired

Email subject.

messages[].threadIdstringOptional

Provider thread ID when included.

messages[].isDraftbooleanOptional

Whether this provider record is a draft.

messages[].draftIdstringOptional

Draft identifier when resolved.

nextPageTokenstringOptional

Opaque provider page token. Omitted when unavailable, including recent=true.

Behavior & constraints

  • Requires the property's email integration. The recent=true response wraps messages but does not expose the normal top-level nextPageToken.
Request
cURL
curl 'https://api.wikiup.app/api/guests/guest_123/messages?format=full&pageSize=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "messages": [
    {
      "id": "message_example",
      "text": "Your room is ready.",
      "html": "<p>Your room is ready.</p>",
      "sender": "me",
      "date": "Tue, 9 Feb 2027 16:00:00 -0800",
      "from": "Example Hotel <hotel@example.com>",
      "to": "guest@example.com",
      "replyTo": "hotel@example.com",
      "unread": false,
      "subject": "Your room is ready",
      "threadId": "thread_example",
      "isDraft": false
    }
  ]
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

Send an email to the guest using the property's mail integration. Optional reply/thread identifiers preserve the existing Gmail conversation, and base64 attachments are supported.

Console guest composer and native iOS reply composer.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

subjectstringRequired

Email subject.

bodystringRequired

Email content, including supported HTML.

inReplyTostringOptional

Message-ID of the message being replied to.

threadIdstringOptional

Gmail thread identifier.

attachmentsobject[]Optional

Attachments as {filename, mimeType, contentBase64}. Empty filename/content entries are ignored.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/guests/guest_123/messages' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"subject":"Your upcoming stay","body":"<p>We look forward to welcoming you.</p>"}'
Response · 200
JSON
{
  "message": "Email sent successfully"
}

Render the property's branded room-ready email for this guest's arriving reservation without sending it.

Console and native iOS room-ready preview/send actions.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

reservationIdstringOptional

Explicit reservation to use; omit to choose today's non-canceled arrival in property time.

Request
cURL
curl 'https://api.wikiup.app/api/guests/guest_123/room-is-ready-email?reservationId=reservation_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "subject": "Room is Ready",
  "body": "<html>…</html>"
}

Send the branded room-ready email to this guest for a selected reservation or today's arrival.

Console and native iOS room-ready preview/send actions.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

reservationIdstringOptional

Explicit reservation to use; omit to choose today's non-canceled arrival in property time.

Request
cURL
curl -X POST 'https://api.wikiup.app/api/guests/guest_123/room-is-ready-email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"reservationId":"reservation_123"}'
Response · 200
JSON
{
  "message": "Room is ready email sent."
}

API Reference

Imports

Preview or apply mapped reservation-import rows, resolving guest/room data and importing reservation details and payment history. Preview before applying to inspect the mapping result.

Console reservation-import mapping and preview workflow.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

previewstringOptional

true previews the mapped records without saving.

Allowed valuestruefalse

Body fields

dataobject[]Required

Rows parsed from the source CSV, keyed by column name.

mappingsobject[]Required

Each mapping has fieldName (e.g. Guest.firstName) and template (e.g. {{First Name}}).

Behavior & constraints

  • Requires reservations.manage and reservations.import_export. A non-preview request returns {message, results}.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/import?preview=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"data":[{"First Name":"Alex","Email":"alex@example.com"}],"mappings":[{"fieldName":"Guest.firstName","template":"{{First Name}}"},{"fieldName":"Guest.email","template":"{{Email}}"}]}'
Response · 200
JSON
{
  "preview": []
}

Preview or apply a mapped guest import, deduplicating contacts and supporting associated reservations, rooms and payments present in the mapped data.

Console guest-import mapping and preview workflow.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

previewstringOptional

true previews the mapped records without saving.

Allowed valuestruefalse

Body fields

dataobject[]Required

Rows parsed from the source CSV, keyed by column name.

mappingsobject[]Required

Each mapping has fieldName (e.g. Guest.firstName) and template (e.g. {{First Name}}).

Behavior & constraints

  • Requires reservations.manage. A non-preview request returns {message: 'Import completed successfully.'}.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/guests/import?preview=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"data":[{"First Name":"Alex","Email":"alex@example.com"}],"mappings":[{"fieldName":"Guest.firstName","template":"{{First Name}}"},{"fieldName":"Guest.email","template":"{{Email}}"}]}'
Response · 200
JSON
{
  "guests": [
    {
      "id": "guest_123",
      "propertyId": "PROPERTY_ID",
      "firstName": "Alex",
      "lastName": "Morgan",
      "email": "alex@example.com",
      "phone": "+15555550123",
      "blocked": false
    }
  ],
  "reservations": [],
  "reservationDetails": [],
  "rooms": [],
  "roomDetails": [],
  "payments": []
}

API Reference

Integrations

Legacy calendar bridge that filters a preconfigured external reservations feed to one of four mapped room names.

Retained compatibility route for the older calendar integration; no current console, public-site, or iOS caller was found in the audit.

Path parameters

accountIdstringRequired

Legacy required path value. The current implementation does not use it to select a tenant or a different source feed.

roomstringRequired

Mapped legacy room key, before the .ics suffix.

Allowed valuesdreamcatchershadyladywillowwarrenstargazer

Behavior & constraints

  • This is not a general export of the selected Wikiup property's reservations. New integrations should not infer tenant isolation or arbitrary room support from this path.
  • Returns text/calendar with date-only event start/end values. Availability depends on the configured external feed; no authenticated property context is used.
Request
cURL
curl 'https://api.wikiup.app/api/ical/legacy-account/dreamcatcher.ics' --output calendar.ics
Example response
text/calendar
BEGIN:VCALENDAR
VERSION:2.0
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTART;VALUE=DATE:20261023
DTEND;VALUE=DATE:20261025
SUMMARY:room: Dreamcatcher
DESCRIPTION:redacted
UID:external-event-id
END:VEVENT
END:VCALENDAR

API Reference

Media & check-in guides

List active mapped channels available for importing room amenities.

Requires rooms.manage. Returns exact-room active non-simulated mappings when channel management is enabled. Single-source clients may skip channel selection; supported is the amenity-read capability (currently Airbnb).

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Request
cURL
curl 'https://api.wikiup.app/api/rooms/property_123/channel-amenities' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
{
  "sources": [
    {
      "id": "mapping-id",
      "name": "Airbnb",
      "code": "AirBNB",
      "supported": true
    }
  ]
}

Review channel amenities and prepare selected property catalog entries.

Requires rooms.manage. Preview fetches the exact mapped Airbnb listing through Channex and returns amenities explicitly marked present, with Wikiup icon mappings. Import re-reads the listing, validates selected codes, and reuses matching property catalog entries or creates deterministic entries. The returned amenities must be added to the room draft and saved through the existing room save workflow.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

actionstringRequired

preview or import

sourceIdstringRequired

Exact room mapping ID from GET.

codesstring[]Optional

Selected preview codes, required for import.

Behavior & constraints

  • This operation never replaces the room amenity list or writes to the channel. Import creates/reuses property catalog entries only; closing the room draft leaves room assignments unchanged.
  • Channel icons are not supplied by Airbnb listing_details. Known identifiers map to Wikiup icons; unknown present identifiers use a readable name and neutral check icon. False or unknown presence values are excluded. Retries reuse catalog entries.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/rooms/property_123/channel-amenities' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"action":"preview","sourceId":"mapping-id"}'
Example response
JSON
{
  "source": {
    "id": "mapping-id",
    "name": "Airbnb",
    "code": "AirBNB",
    "supported": true
  },
  "amenities": [
    {
      "code": "WIRELESS_INTERNET",
      "name": "Wi-Fi",
      "icon": "FaWifi"
    }
  ],
  "fetchedAt": "2026-11-07T20:00:00Z"
}

List active mapped channels available for room photo import.

Requires rooms.manage. Property channel management must be enabled. Only active, non-simulated connections with a ready mapping to this exact room are returned; unsupported photo providers are explicitly marked supported:false.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • This operation reads local mappings only. It does not contact or modify a channel. No schema publication is required.
Request
cURL
curl 'https://api.wikiup.app/api/rooms/property_123/channel-photos' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
{
  "sources": [
    {
      "id": "mapping-id",
      "name": "Airbnb",
      "code": "AirBNB",
      "supported": true
    }
  ]
}

Preview channel photos or append one selected photo to a room gallery.

Requires rooms.manage. action:preview requests fresh details and photos from Airbnb through Channex listing_details (not only cached Channex photos), preserves provider photo order, and returns fetchedAt, sourcePhotoCount and a two-hour actor/property/room/mapping-bound session with photo IDs, allowed preview URLs, captions, availability and already-imported flags. action:import copies one authorized photo without optimization and appends it to Wikiup's gallery.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

actionstringRequired

preview or import

sourceIdstringOptional

Mapping ID returned by GET; required for preview.

sessionIdstring (UUID)Optional

Session from preview; required for import.

photoIdstringOptional

Server-owned photo ID from preview; required for import.

descriptionstringOptional

Photo label, up to 2000 characters; required for import (may be empty).

Behavior & constraints

  • Import is append-only and follows sequential request order. Existing images/captions/order are preserved. Deterministic photo identities make retries return the saved image instead of adding a duplicate.
  • Clients cannot submit an arbitrary source URL. Mapping, actor and property are rechecked before copying. Unsupported hosts, expired sessions and changed mappings fail closed. Supported photo content is currently Airbnb via Channex; other channels report their capability explicitly.
  • No channel rates, inventory, reservations, settings or source photos are modified. Imported files use the ordinary /api/web-assets gallery contract; no optimization step is performed.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/rooms/property_123/channel-photos' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"action":"preview","sourceId":"mapping-id"}'
Example response
JSON
{
  "sessionId": "11111111-1111-4111-8111-111111111111",
  "source": {
    "id": "mapping-id",
    "name": "Airbnb",
    "code": "AirBNB",
    "supported": true
  },
  "listingName": "Garden Cottage",
  "expiresAt": "2026-11-07T22:00:00Z",
  "photos": [
    {
      "id": "photo-id",
      "url": "https://a0.muscache.com/example.jpg",
      "caption": "Bedroom",
      "available": true,
      "imported": false
    }
  ]
}

Add an already uploaded image to the main property gallery, creating the gallery if needed. Requires rooms.manage.

Widget Studio maintains the main property gallery; the hosted widget loader reads the property's gallery relation.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

idstringRequired

Client-generated unique image record ID, typically a UUID. Required by image validation.

urlstringRequired

Uploaded image URL, typically a stable /api/web-assets/... path.

webpUrlstring | nullOptional

Optional optimized WebP version.

descriptionstring | nullOptional

Caption/alternative description displayed by gallery consumers.

Behavior & constraints

  • This endpoint stores image metadata; it does not accept image bytes. Upload first, then register the resulting URL.
  • propertyId comes from the header and order is assigned to the current gallery length. Read images through GET /api/rooms or the property endpoint's relevant embed relation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/property-gallery' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"id":"image_123","propertyId":"property_123","url":"/api/web-assets/properties/property_123/photo.jpg","description":"Garden view","order":0}'
Example response
JSON
{
  "message": "Image added successfully.",
  "image": {
    "id": "image_123",
    "propertyId": "property_123",
    "url": "/api/web-assets/properties/property_123/photo.jpg",
    "description": "Garden view",
    "order": 0
  }
}

Add an already uploaded image to the property hero slideshow, creating the gallery if needed. Requires rooms.manage.

Widget Studio maintains the property hero slideshow; the hosted widget loader reads the property's heroGallery relation.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

idstringRequired

Client-generated unique image record ID, typically a UUID. Required by image validation.

urlstringRequired

Uploaded image URL, typically a stable /api/web-assets/... path.

webpUrlstring | nullOptional

Optional optimized WebP version.

descriptionstring | nullOptional

Caption/alternative description displayed by gallery consumers.

Behavior & constraints

  • This endpoint stores image metadata; it does not accept image bytes. Upload first, then register the resulting URL.
  • propertyId comes from the header and order is assigned to the current gallery length. Read images through GET /api/rooms or the property endpoint's relevant embed relation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/property-hero-gallery' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"id":"image_123","propertyId":"property_123","url":"/api/web-assets/properties/property_123/photo.jpg","description":"Garden view","order":0}'
Example response
JSON
{
  "message": "Hero slideshow image added successfully.",
  "image": {
    "id": "image_123",
    "propertyId": "property_123",
    "url": "/api/web-assets/properties/property_123/photo.jpg",
    "description": "Garden view",
    "order": 0
  }
}

Add an already uploaded image to the property's check-in/confirmation slideshow, creating the gallery if needed. Requires rooms.manage.

Widget Studio maintains the property's check-in/confirmation slideshow; the hosted widget loader reads the property's checkinGallery relation.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

idstringRequired

Client-generated unique image record ID, typically a UUID. Required by image validation.

urlstringRequired

Uploaded image URL, typically a stable /api/web-assets/... path.

webpUrlstring | nullOptional

Optional optimized WebP version.

descriptionstring | nullOptional

Caption/alternative description displayed by gallery consumers.

Behavior & constraints

  • This endpoint stores image metadata; it does not accept image bytes. Upload first, then register the resulting URL.
  • propertyId comes from the header and order is assigned to the current gallery length. Read images through GET /api/rooms or the property endpoint's relevant embed relation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/property-checkin-gallery' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"id":"image_123","propertyId":"property_123","url":"/api/web-assets/properties/property_123/photo.jpg","description":"Garden view","order":0}'
Example response
JSON
{
  "message": "Check-in slideshow image added successfully.",
  "image": {
    "id": "image_123",
    "propertyId": "property_123",
    "url": "/api/web-assets/properties/property_123/photo.jpg",
    "description": "Garden view",
    "order": 0
  }
}

Add an already uploaded image to the room photo gallery, creating the gallery if needed. Requires rooms.manage.

The console room editor maintains the room photo gallery; the hosted room and check-in widgets display the saved images.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

roomIdstringRequired

Room owning this image.

idstringRequired

Client-generated unique image record ID, typically a UUID. Required by image validation.

urlstringRequired

Uploaded image URL, typically a stable /api/web-assets/... path.

webpUrlstring | nullOptional

Optional optimized WebP version.

descriptionstring | nullOptional

Caption/alternative description displayed by gallery consumers.

Behavior & constraints

  • This endpoint stores image metadata; it does not accept image bytes. Upload first, then register the resulting URL.
  • propertyId comes from the header and order is assigned to the current gallery length. Read images through GET /api/rooms or the property endpoint's relevant embed relation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/room-gallery' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"id":"image_123","propertyId":"property_123","roomId":"room_123","url":"/api/web-assets/properties/property_123/photo.jpg","description":"Garden view","order":0}'
Example response
JSON
{
  "message": "Image added successfully.",
  "image": {
    "id": "image_123",
    "propertyId": "property_123",
    "roomId": "room_123",
    "url": "/api/web-assets/properties/property_123/photo.jpg",
    "description": "Garden view",
    "order": 0
  }
}

Add an already uploaded image to the room check-in slideshow, creating the gallery if needed. Requires rooms.manage.

The console room editor maintains the room check-in slideshow; the hosted room and check-in widgets display the saved images.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

roomIdstringRequired

Room owning this image.

idstringRequired

Client-generated unique image record ID, typically a UUID. Required by image validation.

urlstringRequired

Uploaded image URL, typically a stable /api/web-assets/... path.

webpUrlstring | nullOptional

Optional optimized WebP version.

descriptionstring | nullOptional

Caption/alternative description displayed by gallery consumers.

Behavior & constraints

  • This endpoint stores image metadata; it does not accept image bytes. Upload first, then register the resulting URL.
  • propertyId comes from the header and order is assigned to the current gallery length. Read images through GET /api/rooms or the property endpoint's relevant embed relation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/room-checkin-gallery' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"id":"image_123","propertyId":"property_123","roomId":"room_123","url":"/api/web-assets/properties/property_123/photo.jpg","description":"Garden view","order":0}'
Example response
JSON
{
  "message": "Check-in image added successfully.",
  "image": {
    "id": "image_123",
    "propertyId": "property_123",
    "roomId": "room_123",
    "url": "/api/web-assets/properties/property_123/photo.jpg",
    "description": "Garden view",
    "order": 0
  }
}

List property-wide check-in instruction steps in display order. Requires rooms.view.

Widget Studio maintains property-wide arrival instructions shared by guest check-in guides.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • Returns a bare array sorted by order, including [] when there are no steps.
Request
cURL
curl 'https://api.wikiup.app/api/property-checkin-steps' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
[
  {
    "id": "step_123",
    "propertyId": "property_123",
    "order": 0,
    "title": "Find your entrance",
    "body": "<p>Use the garden entrance.</p>",
    "imageUrl": null,
    "imageWebpUrl": null
  }
]

Replace the complete property-wide check-in instruction sequence. Requires rooms.manage.

Widget Studio maintains property-wide arrival instructions shared by guest check-in guides.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

stepsobject[]Required

Complete sequence, at most 20 entries; an empty array clears all saved steps.

steps[].idstringOptional

Existing step ID to retain, or omit for a new generated ID.

steps[].titlestring | nullOptional

Optional step heading.

steps[].bodystring | nullOptional

Optional rich HTML instructions.

steps[].imageUrlstring | nullOptional

Optional uploaded illustration/photo URL.

steps[].imageWebpUrlstring | nullOptional

Optional WebP version of the step image.

Behavior & constraints

  • Array order becomes the zero-based display order. Empty steps with no title, text, or image are discarded. IDs omitted from the new list are deleted, and old/replaced image assets are cleaned up.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/property-checkin-steps' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"steps":[{"id":"step_123","propertyId":"property_123","order":0,"title":"Find your entrance","body":"<p>Use the garden entrance.</p>","imageUrl":null,"imageWebpUrl":null}]}'
Example response
JSON
{
  "message": "Check-in steps updated successfully.",
  "steps": [
    {
      "id": "step_123",
      "propertyId": "property_123",
      "order": 0,
      "title": "Find your entrance",
      "body": "<p>Use the garden entrance.</p>",
      "imageUrl": null,
      "imageWebpUrl": null
    }
  ]
}

List room-specific check-in instruction steps in display order. Requires rooms.view.

The room Check-in Flow editor maintains these instructions; guest check-in guides insert them among the property steps.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Query parameters

roomIdstringRequired

Room ID.

Behavior & constraints

  • Returns a bare array sorted by order, including [] when there are no steps.
  • The room must belong to x-property-id; otherwise the endpoint returns 404.
Request
cURL
curl 'https://api.wikiup.app/api/room-checkin-steps?roomId=room_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
[
  {
    "id": "step_123",
    "propertyId": "property_123",
    "roomId": "room_123",
    "order": 0,
    "title": "Find your entrance",
    "body": "<p>Use the garden entrance.</p>",
    "imageUrl": null,
    "imageWebpUrl": null
  }
]

Replace the complete room-specific check-in instruction sequence. Requires rooms.manage.

The room Check-in Flow editor maintains these instructions; guest check-in guides insert them among the property steps.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

roomIdstringRequired

Room ID.

stepsobject[]Required

Complete sequence, at most 20 entries; an empty array clears all saved steps.

steps[].idstringOptional

Existing step ID to retain, or omit for a new generated ID.

steps[].titlestring | nullOptional

Optional step heading.

steps[].bodystring | nullOptional

Optional rich HTML instructions.

steps[].imageUrlstring | nullOptional

Optional uploaded illustration/photo URL.

steps[].imageWebpUrlstring | nullOptional

Optional WebP version of the step image.

Behavior & constraints

  • Array order becomes the zero-based display order. Empty steps with no title, text, or image are discarded. IDs omitted from the new list are deleted, and old/replaced image assets are cleaned up.
  • The room must belong to x-property-id; otherwise the endpoint returns 404.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/room-checkin-steps' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"roomId":"room_123","steps":[{"id":"step_123","propertyId":"property_123","roomId":"room_123","order":0,"title":"Find your entrance","body":"<p>Use the garden entrance.</p>","imageUrl":null,"imageWebpUrl":null}]}'
Example response
JSON
{
  "message": "Room check-in steps updated successfully.",
  "steps": [
    {
      "id": "step_123",
      "propertyId": "property_123",
      "roomId": "room_123",
      "order": 0,
      "title": "Find your entrance",
      "body": "<p>Use the garden entrance.</p>",
      "imageUrl": null,
      "imageWebpUrl": null
    }
  ]
}

Record that a guest opened, progressed through, or completed a check-in guide using property and confirmation identifiers.

Standalone hosted check-in guides report reading progress so the innkeeper can see it on reservation and Today views. The authenticated guest portal has its own progress endpoint.

Body fields

propertyIdstringRequired

Property ID.

confirmationNumberstringRequired

Reservation confirmation number.

roomIdstring | nullOptional

Optional room ID associated with this guide.

eventTypestringRequired

Guide activity type.

Allowed valuesviewedprogresscompleted
stepsReadCountinteger | nullOptional

Number of steps read so far.

totalStepsCountinteger | nullOptional

Number of steps in this guide.

Behavior & constraints

  • Missing propertyId, confirmationNumber, or supported eventType returns 400.
  • Tracking is best effort: after input validation, persistence errors are logged and the route still returns 204. A 204 is not a booking/status change or guaranteed progress persistence.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/checkin-guide-progress' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"property_123","confirmationNumber":"WUR-EXAMPLE","roomId":"room_123","eventType":"progress","stepsReadCount":2,"totalStepsCount":4}'
Response · 204
HTTP
(empty response body)

Request a temporary URL for uploading an image directly to asset storage.

The iOS account/profile-photo flow uses profile-pics grants and follows the returned upload headers. Gallery metadata is saved separately after an upload succeeds.

Query parameters

fileNamestringRequired

Original filename; required. The server generates a unique storage key and determines the extension from fileType.

fileTypestringRequired

Exact upload Content-Type.

Allowed valuesimage/jpegimage/pngimage/webpimage/gifimage/heic
namespacestringRequired

Storage namespace using alphanumeric, underscore, or hyphen path segments. Use exactly profile-pics for an account photo; the server adds the authenticated user scope.

Response fields

signedUrlstring

Short-lived upload destination. PUT the file bytes to this URL; do not publish or reuse it as an image source.

keystring

Permanent storage key generated for this upload.

headersobject

Profile uploads return required headers. Forward all of them unchanged when PUT-ing the file, including Content-Type.

Behavior & constraints

  • Requires an interactive session. API keys cannot request account/profile upload grants.
  • Upload grants expire after 900 seconds (15 minutes). Unsupported MIME types return 415; invalid namespace returns 400.
  • profile-pics/{someoneElse} is rejected. The profile-pics namespace is automatically scoped to the authenticated user, and account deletion can block new uploads.
  • For a non-profile grant, set Content-Type to the same fileType when uploading. Grant responses are not cacheable.
Request
cURL
curl 'https://api.wikiup.app/api/signed-url?fileName=portrait.jpg&fileType=image%2Fjpeg&namespace=profile-pics' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "signedUrl": "https://upload.example.com/temporary-signed-put-url",
  "key": "profile-pics/user_123/upload_123.jpg",
  "headers": {
    "content-type": "image/jpeg",
    "x-goog-meta-asset-purpose": "profile",
    "x-goog-meta-owner-uid": "user_123"
  }
}

Serve an uploaded asset from its stable public path with its original content type.

Console profiles, property/room galleries, hosted widgets, and the public site render these asset URLs directly.

Path parameters

pathstringRequired

Slash-separated storage key, for example properties/property_123/photo.jpg. Traversal segments and embedded slash/backslash escapes are rejected.

Behavior & constraints

  • Returns the file itself, not {url:...}. Missing files return 404; storage failures return 502.
  • General assets are publicly cached for one year and immutable; upload a new key when replacing an image. Profile photos use private, no-store caching.
  • This route only implements GET. It is not an upload or deletion endpoint.
Request
cURL
curl 'https://api.wikiup.app/api/web-assets/properties/property_123/photo.jpg' --output photo.jpg
Example response
image bytes
HTTP/1.1 200 OK
Content-Type: image/jpeg
Cache-Control: public, max-age=31536000, immutable

(binary image bytes)

API Reference

Operations

List property owners and team members available for task and shift assignment, sorted by display name. Each entry includes the user's role and access-group label.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires any of team.today.view, team.tasks.view, team.readings.view, team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/assignees' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "assignees": [
    {
      "uid": "user_example",
      "name": "Alex Morgan",
      "role": "Innkeeper",
      "groupId": "group_example",
      "groupName": "Front desk"
    }
  ]
}

List housekeeping and maintenance work for a property. Filters combine; due-date bounds are inclusive. Open maintenance backlog items appear before other work and preserve backlog order.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

kindstringOptional

Filter task category.

Allowed valueshousekeepingwork_orderpreventivedeep_cleaninginspection
statusstringOptional

Filter work status.

Allowed valuesopenin_progressdonecanceled
assigneeUidstringOptional

Matches any member of a task's assignee list.

roomIdstringOptional

Filter tasks linked to a room.

dueFromdate-timeOptional

Earliest dueAt, inclusive; excludes unscheduled tasks.

dueTodate-timeOptional

Latest dueAt, inclusive; excludes unscheduled tasks.

Behavior & constraints

  • Requires team.today.view or team.tasks.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/tasks' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "tasks": [
    {
      "id": "task_example",
      "propertyId": "property_example",
      "kind": "work_order",
      "title": "Repair bedside lamp",
      "status": "open",
      "priority": "normal",
      "assigneeUids": [],
      "costCurrency": "USD",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Create a housekeeping or maintenance task. Open non-housekeeping tasks join the maintenance backlog; housekeeping requires a scheduled dueAt. Costs are operational tracking amounts, not guest invoice charges.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

kindstringRequired

Operational work category; housekeeping is scheduled separately from the maintenance backlog.

Allowed valueshousekeepingwork_orderpreventivedeep_cleaninginspection
titlestringRequired

Task title, 1–255 characters.

descriptionstring | nullOptional

Work instructions; at most 10,000 characters.

roomIdstring | nullOptional

Room associated with the work; omit for property-wide work.

locationstring | nullOptional

Location description; at most 255 characters.

assigneeUidstring | nullOptional

Single-assignee compatibility field. Prefer assigneeUids for new clients.

assigneeUidsstring[]Optional

Up to 50 property team member IDs; takes precedence over assigneeUid. Empty array unassigns the task.

statusstringOptional

Defaults to open. in_progress requires an assignee. Completing records actor/time; reopening clears completion metadata.

Allowed valuesopenin_progressdonecanceled
prioritystringOptional

Defaults to normal.

Allowed valuesnormalurgent
dueAtdate-time | nullOptional

Scheduled time with offset. Required for housekeeping; optional for other kinds.

laborCostCentsinteger | nullOptional

Nonnegative labor cost in minor currency units.

materialCostCentsinteger | nullOptional

Nonnegative materials cost in minor currency units.

costCurrencystring | nullOptional

Three uppercase letters; defaults to USD on creation.

Behavior & constraints

  • Requires team.today.edit or team.tasks.edit.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/tasks' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"work_order","title":"Repair bedside lamp"}'
Response · 201
JSON
{
  "task": {
    "id": "task_example",
    "propertyId": "property_example",
    "kind": "work_order",
    "title": "Repair bedside lamp",
    "status": "open",
    "priority": "normal",
    "assigneeUids": [],
    "costCurrency": "USD",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Retrieve one task, including assignment, completion metadata, tracked costs, and the updatedAt value for a safe subsequent edit.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.today.view or team.tasks.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/tasks/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "task": {
    "id": "task_example",
    "propertyId": "property_example",
    "kind": "work_order",
    "title": "Repair bedside lamp",
    "status": "open",
    "priority": "normal",
    "assigneeUids": [],
    "costCurrency": "USD",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Edit task details, assignment, costs, or status. Send only changed fields. Setting done records completion; reopening the task clears completion and returns eligible work to the backlog.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

kindstringOptional

Operational work category; housekeeping is scheduled separately from the maintenance backlog.

Allowed valueshousekeepingwork_orderpreventivedeep_cleaninginspection
titlestringOptional

Task title, 1–255 characters.

descriptionstring | nullOptional

Work instructions; at most 10,000 characters.

roomIdstring | nullOptional

Room associated with the work; omit for property-wide work.

locationstring | nullOptional

Location description; at most 255 characters.

assigneeUidstring | nullOptional

Single-assignee compatibility field. Prefer assigneeUids for new clients.

assigneeUidsstring[]Optional

Up to 50 property team member IDs; takes precedence over assigneeUid. Empty array unassigns the task.

statusstringOptional

Defaults to open. in_progress requires an assignee. Completing records actor/time; reopening clears completion metadata.

Allowed valuesopenin_progressdonecanceled
prioritystringOptional

Defaults to normal.

Allowed valuesnormalurgent
dueAtdate-time | nullOptional

Scheduled time with offset. Required for housekeeping; optional for other kinds.

laborCostCentsinteger | nullOptional

Nonnegative labor cost in minor currency units.

materialCostCentsinteger | nullOptional

Nonnegative materials cost in minor currency units.

costCurrencystring | nullOptional

Three uppercase letters; defaults to USD on creation.

expectedUpdatedAtdate-timeOptional

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

Behavior & constraints

  • Requires team.today.edit or team.tasks.edit.
  • At least one task field is required. Include expectedUpdatedAt to reject overwriting a newer edit.
  • In-progress tasks need an assignee; changing a task to housekeeping requires dueAt.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/operations/tasks/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"status":"in_progress","assigneeUids":["user_example"],"expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "task": {
    "id": "task_example",
    "propertyId": "property_example",
    "kind": "work_order",
    "title": "Repair bedside lamp",
    "status": "in_progress",
    "priority": "normal",
    "assigneeUids": [
      "user_example"
    ],
    "costCurrency": "USD",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Permanently remove an operational task from the selected property. Use PATCH status=canceled when the task should remain in the work history.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.today.edit or team.tasks.edit.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/operations/tasks/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

Claim the first unassigned open maintenance-backlog task for the authenticated team member. Sets status to in_progress and removes the task from the open backlog; housekeeping is excluded.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.today.edit or team.tasks.edit.
  • No body is required. A 409 means no unassigned task is available or another person claimed the candidate concurrently.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/tasks/claim-next' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "task": {
    "id": "task_example",
    "propertyId": "property_example",
    "kind": "work_order",
    "title": "Repair bedside lamp",
    "status": "in_progress",
    "priority": "normal",
    "assigneeUids": [],
    "costCurrency": "USD",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z",
    "assigneeUid": "user_example",
    "backlogOrder": null
  }
}

Move one open maintenance task within the property-wide backlog. Supply the complete resulting order; every other task must preserve its relative position.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

taskIdsstring[]Required

Every open non-housekeeping task ID exactly once, in the desired order.

movedTaskIdstringRequired

The single task whose position changed.

Behavior & constraints

  • Requires team.tasks.edit.
  • Refresh the list after a 409 conflict. A filtered subset or changes to multiple task positions are rejected.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/tasks/reorder' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"taskIds":["task_b","task_a"],"movedTaskId":"task_b"}'
Response · 200
JSON
{
  "task": {
    "id": "task_b",
    "propertyId": "property_example",
    "kind": "work_order",
    "title": "Repair bedside lamp",
    "status": "open",
    "priority": "normal",
    "assigneeUids": [],
    "costCurrency": "USD",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z",
    "backlogOrder": 0
  }
}

Reconcile reservation checkout housekeeping against operational tasks using the property's local checkout policy. Creates missing tasks and updates or removes generated work where eligible, returning counts and any conflicts.

Called when the console Team workspace refreshes housekeeping.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.today.edit or team.tasks.edit.
  • No request body. This mutates tasks; it is not a read-only preview.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/housekeeping/sync' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "created": 2,
  "updated": 1,
  "deleted": 0,
  "unchanged": 8,
  "conflicts": 0
}

Retrieve the property's equipment and utility readings for the Team readings log. Filter by equipment category when displaying a specific log.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

kindstringOptional

Equipment category.

Allowed valuesboilerutility_meterpool_chemical

Response fields

readingsArray<object>Required

All matching readings sorted newest measurement first. No pagination token.

readings[]objectRequired

Recorded equipment measurement.

readings[].idstringOptional

Saved reading ID.

readings[].propertyIdstringRequired

Owning property ID.

readings[].kind"boiler" | "utility_meter" | "pool_chemical"Required

Equipment category.

readings[].metricstringRequired

Measurement name, e.g. pH.

readings[].valuenumberRequired

Measured numeric value; negative values are permitted when meaningful.

readings[].unitstringRequired

Unit label, e.g. pH or psi.

readings[].locationstring | nullOptional

Equipment location; null when unset.

readings[].notesstring | nullOptional

Staff notes; null when unset.

readings[].recordedAtstringRequired

Measurement timestamp, not necessarily insertion time.

readings[].recordedByUidstringRequired

Staff account that recorded the reading.

Behavior & constraints

  • Requires team.readings.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/readings' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "readings": [
    {
      "id": "reading_example",
      "propertyId": "property_example",
      "kind": "pool_chemical",
      "metric": "pH",
      "value": 7.4,
      "unit": "pH",
      "location": "Main pool",
      "notes": null,
      "recordedAt": "2027-02-09T16:00:00-08:00",
      "recordedByUid": "staff_example"
    }
  ]
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

Append a measured equipment or utility value. The server attributes it to the authenticated staff member; use recordedAt for the actual measurement time when entering a prior reading.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

kindstringRequired

Equipment category.

Allowed valuesboilerutility_meterpool_chemical
metricstringRequired

Name of the measurement, 1–120 characters; for example pH or pressure.

valuenumberRequired

Finite measured value; negative values are permitted where meaningful.

unitstringRequired

Unit label, 1–80 characters; for example pH or psi.

locationstring | nullOptional

Equipment location, up to 255 characters.

notesstring | nullOptional

Measurement notes, up to 10,000 characters.

recordedAtdate-timeOptional

Measurement timestamp with offset; defaults to current server time.

Response fields

readingobjectRequired

Saved measurement.

reading.idstringOptional

Saved reading ID.

reading.propertyIdstringRequired

Owning property ID.

reading.kind"boiler" | "utility_meter" | "pool_chemical"Required

Equipment category.

reading.metricstringRequired

Measurement name, e.g. pH.

reading.valuenumberRequired

Measured numeric value; negative values are permitted when meaningful.

reading.unitstringRequired

Unit label, e.g. pH or psi.

reading.locationstring | nullOptional

Equipment location; null when unset.

reading.notesstring | nullOptional

Staff notes; null when unset.

reading.recordedAtstringRequired

Measurement timestamp, not necessarily insertion time.

reading.recordedByUidstringRequired

Staff account that recorded the reading.

Behavior & constraints

  • Requires team.readings.edit.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/readings' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"pool_chemical","metric":"pH","value":7.4,"unit":"pH"}'
Response · 201
JSON
{
  "reading": {
    "id": "reading_example",
    "propertyId": "property_example",
    "kind": "pool_chemical",
    "metric": "pH",
    "value": 7.4,
    "unit": "pH",
    "location": "Main pool",
    "notes": null,
    "recordedAt": "2027-02-09T16:00:00-08:00",
    "recordedByUid": "staff_example"
  }
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

List recurring maintenance reminders with their next due dates and last completion details. Reminders remain reusable after completion.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.tasks.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/routines' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "routines": [
    {
      "title": "Inspect smoke alarms",
      "action": "inspect",
      "cadence": "monthly",
      "nextDueDate": "2026-11-01",
      "id": "routine_example",
      "propertyId": "property_example",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Create a recurring inspect, clean, or replace reminder. This creates the reminder definition; use its complete endpoint when the work is finished to advance the due date.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

titlestringRequired

Reminder title, 1–255 characters.

actionstringRequired

Type of recurring work.

Allowed valuesinspectcleanreplace
cadencestringRequired

How far to advance the due date after completion.

Allowed valuesdailyweeklymonthlyevery_2_monthsevery_3_monthsevery_4_monthsevery_5_monthsevery_6_monthsevery_7_monthsevery_8_monthsevery_9_monthsannually
nextDueDatedateRequired

Next due date in YYYY-MM-DD.

locationstring | nullOptional

Optional location, up to 255 characters.

notesstring | nullOptional

Optional instructions, up to 10,000 characters.

Behavior & constraints

  • Requires team.tasks.edit.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/routines' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Inspect smoke alarms","action":"inspect","cadence":"monthly","nextDueDate":"2026-11-01"}'
Response · 201
JSON
{
  "routine": {
    "title": "Inspect smoke alarms",
    "action": "inspect",
    "cadence": "monthly",
    "nextDueDate": "2026-11-01",
    "id": "routine_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Read one recurring reminder, including its cadence, next due date, completion metadata, and updatedAt version.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.tasks.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/routines/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "routine": {
    "title": "Inspect smoke alarms",
    "action": "inspect",
    "cadence": "monthly",
    "nextDueDate": "2026-11-01",
    "id": "routine_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Change a recurring reminder's instructions, action, cadence, or due date. Requires the last-read updatedAt so simultaneous staff edits do not overwrite one another.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

titlestringOptional

Reminder title, 1–255 characters.

actionstringOptional

Type of recurring work.

Allowed valuesinspectcleanreplace
cadencestringOptional

How far to advance the due date after completion.

Allowed valuesdailyweeklymonthlyevery_2_monthsevery_3_monthsevery_4_monthsevery_5_monthsevery_6_monthsevery_7_monthsevery_8_monthsevery_9_monthsannually
nextDueDatedateOptional

Next due date in YYYY-MM-DD.

locationstring | nullOptional

Optional location, up to 255 characters.

notesstring | nullOptional

Optional instructions, up to 10,000 characters.

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

Behavior & constraints

  • Requires team.tasks.edit.
  • At least one reminder field is required in addition to expectedUpdatedAt.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/operations/routines/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"nextDueDate":"2026-11-15","expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "routine": {
    "title": "Inspect smoke alarms",
    "action": "inspect",
    "cadence": "monthly",
    "nextDueDate": "2026-11-15",
    "id": "routine_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Remove a recurring reminder so it no longer appears as future maintenance work.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.tasks.edit.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/operations/routines/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

Record completion of a recurring reminder and advance nextDueDate by its cadence until it falls after today in the property's time zone. This avoids leaving overdue reminders in the past after a late completion.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

Behavior & constraints

  • Requires team.tasks.edit.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/routines/id_example/complete' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "routine": {
    "title": "Inspect smoke alarms",
    "action": "inspect",
    "cadence": "monthly",
    "nextDueDate": "2026-12-01",
    "id": "routine_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z",
    "lastCompletedByUid": "user_example",
    "lastCompletedAt": "2026-10-22T17:00:00.000Z"
  }
}

List the property's duty definitions, with active duties first. Duties describe the responsibility assigned to a shift, such as front desk or housekeeping.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/duties' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "duties": [
    {
      "id": "duty_example",
      "propertyId": "property_example",
      "name": "Front desk",
      "status": "active",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Create a duty definition for the scheduling calendar. Combine an active duty with shift hours to form a reusable shift.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

namestringRequired

Duty name, 1–255 characters.

statusstringRequired

Inactive duties remain available for historical display but cannot be selected for new shifts.

Allowed valuesactiveinactive

Behavior & constraints

  • Requires team.calendar.edit.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/duties' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Front desk","status":"active"}'
Response · 201
JSON
{
  "duty": {
    "id": "duty_example",
    "propertyId": "property_example",
    "name": "Front desk",
    "status": "active",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Rename or deactivate a duty using optimistic concurrency. Deactivation prevents new assignments while retaining the definition for existing schedule history.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

namestringOptional

Duty name, 1–255 characters.

statusstringOptional

Inactive duties remain available for historical display but cannot be selected for new shifts.

Allowed valuesactiveinactive
expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

Behavior & constraints

  • Requires team.calendar.edit.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/operations/duties/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"status":"inactive","expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "duty": {
    "id": "duty_example",
    "propertyId": "property_example",
    "name": "Front desk",
    "status": "inactive",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

List reusable local start/end time definitions for shifts. Check supersededById before using an older definition for a new assignment.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/shift-hours' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "shiftHours": [
    {
      "id": "hours_example",
      "propertyId": "property_example",
      "startTime": "08:00",
      "endTime": "16:00",
      "supersededById": null,
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Create a reusable shift-hours definition, or return the current definition with the same start and end times. Overnight shifts are supported; equal start/end times are invalid.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

startTimetimeRequired

Property-local HH:mm, on a 15-minute boundary (00, 15, 30, 45).

endTimetimeRequired

Property-local HH:mm on a 15-minute boundary. Must differ from startTime; an earlier end represents an overnight shift.

Behavior & constraints

  • Requires team.calendar.edit.
  • Returns 201 for a new definition or 200 when an equivalent current definition already exists.
  • Dates use YYYY-MM-DD; shift times use HH:mm in the property's local time zone. Timestamps such as updatedAt include a time-zone offset.
  • IDs for rooms, assignees, duties, and shifts must belong to the selected property.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/shift-hours' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"startTime":"08:00","endTime":"16:00"}'
Response · 201
JSON
{
  "shiftHours": {
    "id": "hours_example",
    "propertyId": "property_example",
    "startTime": "08:00",
    "endTime": "16:00",
    "supersededById": null,
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Replace shift hours and update affected future scheduling references while preserving historical dates. The response identifies replacement/superseded definitions and affected scheduled shifts, recurring schedules, and exceptions.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

startTimetimeOptional

Property-local HH:mm, on a 15-minute boundary (00, 15, 30, 45).

endTimetimeOptional

Property-local HH:mm on a 15-minute boundary. Must differ from startTime; an earlier end represents an overnight shift.

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

Behavior & constraints

  • Requires team.calendar.edit.
  • Reload calendar definitions and schedules after saving; the replacement shiftHours may have a different ID.
  • A stale version returns 409. At least one time field is required.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/operations/shift-hours/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"endTime":"16:30","expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "shiftHours": {
    "id": "hours_replacement",
    "propertyId": "property_example",
    "startTime": "08:00",
    "endTime": "16:30",
    "supersededById": null,
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "supersededShiftHours": {
    "id": "hours_example",
    "propertyId": "property_example",
    "startTime": "08:00",
    "endTime": "16:00",
    "supersededById": "hours_replacement",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "supersededEquivalentShiftHours": [],
  "shifts": [],
  "scheduledShifts": [],
  "scheduledShiftUpdates": [],
  "staffSchedules": [],
  "staffScheduleUpdates": [],
  "staffScheduleOverrides": [],
  "staffScheduleOverrideUpdates": []
}

List reusable combinations of a duty and shift-hours definition. Resolve dutyId and shiftHoursId against the corresponding collections for display.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/shifts' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "shifts": [
    {
      "id": "shift_example",
      "propertyId": "property_example",
      "dutyId": "duty_example",
      "shiftHoursId": "hours_example",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Resolve or create a reusable duty/hours combination before assigning a dated shift. The duty must be active and the hours definition current.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

dutyIdstringRequired

Active duty from GET /api/operations/duties.

shiftHoursIdstringRequired

Current hours definition from GET /api/operations/shift-hours.

Behavior & constraints

  • Requires team.calendar.edit.
  • Returns 201 when created or 200 when the combination already exists.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/shifts' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"dutyId":"duty_example","shiftHoursId":"hours_example"}'
Response · 201
JSON
{
  "shift": {
    "id": "shift_example",
    "propertyId": "property_example",
    "dutyId": "duty_example",
    "shiftHoursId": "hours_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z"
  }
}

List dated shift assignments, including pending coverage requests. These are explicit date ranges, separate from weekly recurring staff schedules.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

assigneeUidstringOptional

Optional team-member filter.

Behavior & constraints

  • Requires team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/scheduled-shifts' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "scheduledShifts": [
    {
      "shiftId": "shift_example",
      "assigneeUid": "user_example",
      "startDate": "2026-11-02",
      "endDate": "2026-11-04",
      "id": "scheduled_example",
      "propertyId": "property_example",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Assign a reusable shift to a team member for an inclusive range of dates. Each date uses the shift definition's property-local hours.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

shiftIdstringRequired

Duty/hours combination from GET or POST /api/operations/shifts.

assigneeUidstringRequired

Assigned property team member.

startDatedateRequired

First scheduled day, inclusive (YYYY-MM-DD).

endDatedateRequired

Last scheduled day, inclusive; cannot precede startDate.

requestCoveragebooleanOptional

Request another person to cover this scheduled assignment. All dates must be between today and 14 days ahead in the property time zone.

Behavior & constraints

  • Requires team.calendar.edit.
  • Dates use YYYY-MM-DD; shift times use HH:mm in the property's local time zone. Timestamps such as updatedAt include a time-zone offset.
  • IDs for rooms, assignees, duties, and shifts must belong to the selected property.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/scheduled-shifts' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"shiftId":"shift_example","assigneeUid":"user_example","startDate":"2026-11-02","endDate":"2026-11-04"}'
Response · 201
JSON
{
  "scheduledShift": {
    "shiftId": "shift_example",
    "assigneeUid": "user_example",
    "startDate": "2026-11-02",
    "endDate": "2026-11-04",
    "id": "scheduled_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Change an entire dated assignment or only an inclusive segment. A segment edit may split the original record, so reconcile the returned scheduledShifts instead of assuming one unchanged ID.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

shiftIdstringOptional

Duty/hours combination from GET or POST /api/operations/shifts.

assigneeUidstringOptional

Assigned property team member.

startDatedateOptional

First scheduled day, inclusive (YYYY-MM-DD).

endDatedateOptional

Last scheduled day, inclusive; cannot precede startDate.

requestCoveragebooleanOptional

Request another person to cover this scheduled assignment. All dates must be between today and 14 days ahead in the property time zone.

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

segmentStartDatedateOptional

First date of an inclusive selected segment (YYYY-MM-DD); provide both segment dates or neither.

segmentEndDatedateOptional

Last date of the selected segment; cannot precede segmentStartDate.

Behavior & constraints

  • Requires team.calendar.edit.
  • When moving/resizing a selected segment, supply both target startDate and endDate. At least one assignment field must change.
  • Response scheduledShifts contains the resulting pieces affected by this mutation, not the full property calendar.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/operations/scheduled-shifts/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"requestCoverage":true,"expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "scheduledShift": {
    "shiftId": "shift_example",
    "assigneeUid": "user_example",
    "startDate": "2026-11-02",
    "endDate": "2026-11-04",
    "id": "scheduled_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "scheduledShifts": [
    {
      "shiftId": "shift_example",
      "assigneeUid": "user_example",
      "startDate": "2026-11-02",
      "endDate": "2026-11-04",
      "id": "scheduled_example",
      "propertyId": "property_example",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Remove an entire dated assignment or selected inclusive segment. Returns retained pieces after a partial removal; a whole-record removal returns an empty scheduledShifts array.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

segmentStartDatedateOptional

First date of an inclusive selected segment (YYYY-MM-DD); provide both segment dates or neither.

segmentEndDatedateOptional

Last date of the selected segment; cannot precede segmentStartDate.

Behavior & constraints

  • Requires team.calendar.edit.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/operations/scheduled-shifts/id_example?expectedUpdatedAt=2026-10-22T17%3A00%3A00.000Z' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "scheduledShifts": []
}

List weekly recurring schedules and their effective date ranges. Combine these patterns with dated shifts and overrides to render the staff calendar.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

assigneeUidstringOptional

Optional team-member filter.

Behavior & constraints

  • Requires team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/staff-schedules' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "schedules": [
    {
      "assigneeUid": "user_example",
      "dutyId": "duty_example",
      "shiftHoursId": "hours_example",
      "weekdays": [
        1,
        2,
        3,
        4,
        5
      ],
      "startTime": "08:00",
      "endTime": "16:00",
      "effectiveFrom": "2026-11-02",
      "id": "schedule_example",
      "propertyId": "property_example",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Create a recurring weekly schedule for one team member. New schedules require both an active duty and current shift hours, with times matching that hours definition.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

assigneeUidstringRequired

Property team member assigned to the weekly schedule.

dutyIdstringRequired

Active duty from GET /api/operations/duties.

shiftHoursIdstringRequired

Current hours definition from GET /api/operations/shift-hours.

weekdaysinteger[]Required

One to seven unique weekday numbers: Sunday=0, Monday=1, … Saturday=6.

Allowed values0123456
startTimetimeRequired

Property-local HH:mm; must match the chosen shift-hours definition.

endTimetimeRequired

Property-local HH:mm; must match the chosen shift-hours definition and differ from startTime.

effectiveFromdateRequired

First date the weekly pattern applies, inclusive.

effectiveUntildate | nullOptional

Last date, inclusive; null means no end. Cannot precede effectiveFrom.

Behavior & constraints

  • Requires team.calendar.edit.
  • Dates use YYYY-MM-DD; shift times use HH:mm in the property's local time zone. Timestamps such as updatedAt include a time-zone offset.
  • IDs for rooms, assignees, duties, and shifts must belong to the selected property.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/staff-schedules' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"assigneeUid":"user_example","dutyId":"duty_example","shiftHoursId":"hours_example","weekdays":[1,2,3,4,5],"startTime":"08:00","endTime":"16:00","effectiveFrom":"2026-11-02"}'
Response · 201
JSON
{
  "schedule": {
    "assigneeUid": "user_example",
    "dutyId": "duty_example",
    "shiftHoursId": "hours_example",
    "weekdays": [
      1,
      2,
      3,
      4,
      5
    ],
    "startTime": "08:00",
    "endTime": "16:00",
    "effectiveFrom": "2026-11-02",
    "id": "schedule_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Edit a future weekly schedule, apply changes from a new effective date, or stop future occurrences. For an already-started pattern use applyFrom or stopFrom to retain past schedule history.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

assigneeUidstringOptional

Property team member assigned to the weekly schedule.

dutyIdstringOptional

Active duty from GET /api/operations/duties.

shiftHoursIdstringOptional

Current hours definition from GET /api/operations/shift-hours.

weekdaysinteger[]Optional

One to seven unique weekday numbers: Sunday=0, Monday=1, … Saturday=6.

Allowed values0123456
startTimetimeOptional

Property-local HH:mm; must match the chosen shift-hours definition.

endTimetimeOptional

Property-local HH:mm; must match the chosen shift-hours definition and differ from startTime.

effectiveFromdateOptional

First date the weekly pattern applies, inclusive.

effectiveUntildate | nullOptional

Last date, inclusive; null means no end. Cannot precede effectiveFrom.

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

applyFromdateOptional

Apply changed fields from this date, splitting the schedule if needed. Do not combine with effectiveFrom or stopFrom.

stopFromdateOptional

Stop the recurrence starting on this date. Send only stopFrom and expectedUpdatedAt in this mode.

Behavior & constraints

  • Requires team.calendar.edit.
  • Direct and applyFrom edits require at least one changed schedule field. Do not combine the three edit modes.
  • Response schedules lists affected retained/replacement records; reload or reconcile these pieces after saving.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/operations/staff-schedules/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"stopFrom":"2026-12-01","expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "schedule": {
    "assigneeUid": "user_example",
    "dutyId": "duty_example",
    "shiftHoursId": "hours_example",
    "weekdays": [
      1,
      2,
      3,
      4,
      5
    ],
    "startTime": "08:00",
    "endTime": "16:00",
    "effectiveFrom": "2026-11-02",
    "id": "schedule_example",
    "propertyId": "property_example",
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z",
    "effectiveUntil": "2026-11-30"
  },
  "schedules": [
    {
      "assigneeUid": "user_example",
      "dutyId": "duty_example",
      "shiftHoursId": "hours_example",
      "weekdays": [
        1,
        2,
        3,
        4,
        5
      ],
      "startTime": "08:00",
      "endTime": "16:00",
      "effectiveFrom": "2026-11-02",
      "id": "schedule_example",
      "propertyId": "property_example",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z",
      "effectiveUntil": "2026-11-30"
    }
  ]
}

Delete a recurring schedule that has not started. If effectiveFrom is today or earlier in the property time zone, stop it with PATCH stopFrom instead to preserve history.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

Behavior & constraints

  • Requires team.calendar.edit.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/operations/staff-schedules/id_example?expectedUpdatedAt=2026-10-22T17%3A00%3A00.000Z' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "schedules": []
}

List calendar exceptions: additional shifts, unavailable dates, and suppressed recurring shifts. Use kind to distinguish each exception's effect.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

assigneeUidstringOptional

Optional team-member filter.

Behavior & constraints

  • Requires team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/staff-schedule-overrides' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "overrides": [
    {
      "assigneeUid": "user_example",
      "kind": "blocked",
      "startDate": "2026-11-05",
      "endDate": "2026-11-06",
      "notes": "Unavailable",
      "id": "override_example",
      "propertyId": "property_example",
      "startTime": null,
      "endTime": null,
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Create a dated exception to a team member's calendar. scheduled adds work, blocked marks unavailability, and unscheduled suppresses the recurring pattern for the selected dates or duty.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

assigneeUidstringRequired

Property team member affected by the exception.

kindstringRequired

scheduled adds a dated shift; blocked marks unavailable dates; unscheduled suppresses recurring work for the selected dates/duty.

Allowed valuesscheduledblockedunscheduled
dutyIdstring | nullOptional

Optional duty scope. For scheduled, pair with shiftHoursId. Forbidden for blocked.

shiftHoursIdstring | nullOptional

Optional current hours definition for scheduled, paired with dutyId. Forbidden for blocked and unscheduled.

startDatedateRequired

First affected date, inclusive.

endDatedateRequired

Last affected date, inclusive; cannot precede startDate.

startTimetime | nullOptional

Required for scheduled, property-local HH:mm; must match shiftHoursId when supplied.

endTimetime | nullOptional

Required for scheduled and must differ from startTime.

notesstring | nullOptional

Unavailable-date notes, up to 10,000 characters. Only accepted for kind=blocked.

requestCoveragebooleanOptional

Only valid for kind=scheduled, with all dates between today and 14 days ahead in the property time zone.

Behavior & constraints

  • Requires team.calendar.edit.
  • Dates use YYYY-MM-DD; shift times use HH:mm in the property's local time zone. Timestamps such as updatedAt include a time-zone offset.
  • IDs for rooms, assignees, duties, and shifts must belong to the selected property.
  • Only blocked exceptions accept notes. Scheduled exceptions require startTime/endTime; if a duty/hours pair is supplied, the times must match it.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/staff-schedule-overrides' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"assigneeUid":"user_example","kind":"blocked","startDate":"2026-11-05","endDate":"2026-11-06","notes":"Unavailable"}'
Response · 201
JSON
{
  "override": {
    "assigneeUid": "user_example",
    "kind": "blocked",
    "startDate": "2026-11-05",
    "endDate": "2026-11-06",
    "notes": "Unavailable",
    "id": "override_example",
    "propertyId": "property_example",
    "startTime": null,
    "endTime": null,
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  }
}

Edit a whole calendar exception or a selected inclusive segment. Segment edits may split the original range; use the returned overrides array to update the affected calendar records.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

assigneeUidstringOptional

Property team member affected by the exception.

kindstringOptional

scheduled adds a dated shift; blocked marks unavailable dates; unscheduled suppresses recurring work for the selected dates/duty.

Allowed valuesscheduledblockedunscheduled
dutyIdstring | nullOptional

Optional duty scope. For scheduled, pair with shiftHoursId. Forbidden for blocked.

shiftHoursIdstring | nullOptional

Optional current hours definition for scheduled, paired with dutyId. Forbidden for blocked and unscheduled.

startDatedateOptional

First affected date, inclusive.

endDatedateOptional

Last affected date, inclusive; cannot precede startDate.

startTimetime | nullOptional

Required for scheduled, property-local HH:mm; must match shiftHoursId when supplied.

endTimetime | nullOptional

Required for scheduled and must differ from startTime.

notesstring | nullOptional

Unavailable-date notes, up to 10,000 characters. Only accepted for kind=blocked.

requestCoveragebooleanOptional

Only valid for kind=scheduled, with all dates between today and 14 days ahead in the property time zone.

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

segmentStartDatedateOptional

First date of an inclusive selected segment (YYYY-MM-DD); provide both segment dates or neither.

segmentEndDatedateOptional

Last date of the selected segment; cannot precede segmentStartDate.

Behavior & constraints

  • Requires team.calendar.edit.
  • Provide both segment dates or neither. Moving/resizing a selected segment requires both target startDate and endDate. At least one exception field is required.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/operations/staff-schedule-overrides/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"notes":"Updated unavailable dates","expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "override": {
    "assigneeUid": "user_example",
    "kind": "blocked",
    "startDate": "2026-11-05",
    "endDate": "2026-11-06",
    "notes": "Unavailable",
    "id": "override_example",
    "propertyId": "property_example",
    "startTime": null,
    "endTime": null,
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "overrides": [
    {
      "assigneeUid": "user_example",
      "kind": "blocked",
      "startDate": "2026-11-05",
      "endDate": "2026-11-06",
      "notes": "Unavailable",
      "id": "override_example",
      "propertyId": "property_example",
      "startTime": null,
      "endTime": null,
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ]
}

Remove all or part of a calendar exception. Removing a suppression can make the underlying weekly schedule visible again. Returns retained pieces after segment removal.

Used by the console Team workspace and native innkeeper operations/calendar views.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

segmentStartDatedateOptional

First date of an inclusive selected segment (YYYY-MM-DD); provide both segment dates or neither.

segmentEndDatedateOptional

Last date of the selected segment; cannot precede segmentStartDate.

Behavior & constraints

  • Requires team.calendar.edit.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/operations/staff-schedule-overrides/id_example?expectedUpdatedAt=2026-10-22T17%3A00%3A00.000Z' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "overrides": []
}

Accept an open coverage request for a dated shift or scheduled override. Reassigns the selected range and records the original assignee's suppression/unavailability so the same work is not offered twice.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

sourceTypestringRequired

Collection containing the assignment being covered.

Allowed valuesscheduledoverride
sourceIdstringRequired

ID of the scheduled shift or scheduled-kind override with a coverage request.

assigneeUidstringRequired

Replacement team member; must differ from the current assignee.

segmentStartDatedateRequired

First date of an inclusive selected segment (YYYY-MM-DD); provide both segment dates or neither.

segmentEndDatedateRequired

Last date of the selected segment; cannot precede segmentStartDate.

expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

Behavior & constraints

  • Requires team.calendar.view; team.calendar.edit is additionally required to assign coverage to someone other than yourself.
  • The request must still be open and the supplied version current. Conflicts return 409; refresh before trying again.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/shift-coverage' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"sourceType":"scheduled","sourceId":"scheduled_example","assigneeUid":"replacement_user","segmentStartDate":"2026-11-02","segmentEndDate":"2026-11-04","expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "sourceType": "scheduled",
  "scheduledShifts": [
    {
      "shiftId": "shift_example",
      "assigneeUid": "replacement_user",
      "startDate": "2026-11-02",
      "endDate": "2026-11-04",
      "id": "scheduled_example",
      "propertyId": "property_example",
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ],
  "staffScheduleOverrides": []
}

List open unassigned duty coverage ranges for this property, with versions for claiming or canceling them.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires team.calendar.view.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/operations/duty-coverage' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "requests": []
}

Request coverage for an unassigned duty and inclusive date range. Sends one push event for the saved range to active members assigned to that duty.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

requestIdUUIDRequired

Reuse this client request ID when retrying an uncertain response.

dutyIdstringRequired

Active duty in this property.

shiftHoursIdstringRequired

Current shift hours in this property.

startDatedateRequired

First requested date, inclusive.

endDatedateRequired

Last requested date, inclusive.

Behavior & constraints

  • Requires team.calendar.edit.
  • Idempotent retries return the original request without broadcasting another push. MemberAssignments eligibility and personal delivery settings control recipients.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/duty-coverage' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"requestId":"104d168f-111c-45aa-8980-a4cfd8fba048","dutyId":"duty_example","shiftHoursId":"hours_example","startDate":"2026-11-10","endDate":"2026-11-12"}'
Response · 201
JSON
{
  "created": true,
  "request": {
    "id": "request_example",
    "status": "open"
  }
}

Claim or cancel an open duty coverage range. Partial ranges preserve the remaining requested dates; claims create a real scheduled assignment.

Used by the console Team workspace and native innkeeper operations/calendar views.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

actionstringRequired

Claim or cancel the selected range.

Allowed valuesclaimcancel
expectedUpdatedAtdate-timeRequired

Copy updatedAt from the latest read. A stale value returns 409; refresh before retrying.

startDatedateOptional

Optional first date within the open range.

endDatedateOptional

Optional last date within the open range.

assigneeUidstringOptional

Defaults to the authenticated user when claiming.

Behavior & constraints

  • Requires team.calendar.view to claim for yourself; team.calendar.edit to cancel or assign someone else.
  • No push notification is sent when claiming or canceling. Stale versions or competing claims return 409.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/operations/duty-coverage/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"action":"claim","expectedUpdatedAt":"2026-10-22T17:00:00.000Z"}'
Response · 200
JSON
{
  "requests": [],
  "scheduledShift": {
    "id": "scheduled_example"
  }
}

API Reference

Payments

Email the reservation payment link or a payment reminder, optionally overriding the recipient; stores the last recipient for subsequent follow-up.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

recipientEmailstring | nullOptional

Override the saved guest email for this delivery.

reminderbooleanOptional

Use payment reminder copy; false by default.

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
  • Treat paymentLinkToken and url as secrets. The guest-facing /api/reservation-payments endpoints authorize through this token, not an innkeeper session.
  • API keys require read_write access, including GET, because the response exposes a payment capability.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/payment-link' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"reminder":false}'
Response · 200
JSON
{
  "paymentLinkToken": "PAYMENT_LINK_TOKEN",
  "url": "https://www.example-inn.com/pay?paymentLinkToken=PAYMENT_LINK_TOKEN",
  "widgetUrl": "https://www.example-inn.com/pay?paymentLinkToken=PAYMENT_LINK_TOKEN",
  "balanceDue": 300,
  "guestEmailSent": true,
  "reminderSent": false
}

Prepare a console/iOS payment for an existing reservation after applying an optional discount and gift card. Returns Stripe client credentials for collection; it does not record a completed payment yet.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

amountnumber | stringOptional

Amount to collect in major currency units; omit for the remaining balance. Cannot exceed balance due.

discountCodestringOptional

Optional lodging discount code.

giftCardNumberstringOptional

Optional gift card applied before card collection.

giftCardAmountnumberOptional

Requested gift-card contribution in major currency units.

stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive
paymentMethodTypestringOptional

card limits collection to cards; default allows the configured payment methods.

Allowed valuesdefaultcard

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
  • Complete client-side payment authorization, then POST the same amount/adjustments and paymentIntentId to /payments. If requiresPayment:false, no Stripe confirmation is necessary but /payments still applies gift cards/discounts.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/payments/intent' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amount":300,"paymentMethodType":"card"}'
Response · 200
JSON
{
  "clientSecret": "pi_example_secret_example",
  "paymentIntentId": "pi_example",
  "currency": "usd",
  "stripeMode": "live",
  "publishableKey": "pk_live_example",
  "requiresPayment": true,
  "paymentSetupError": null,
  "appliedDiscountAmount": 0,
  "appliedDiscountCode": null,
  "appliedGiftCardAmount": 0,
  "remainingDue": 300,
  "balanceDue": 300,
  "giftCardBalance": null,
  "giftCardRemainingBalance": null
}

Finalize a console/iOS collection: verify the PaymentIntent belongs to this reservation, capture an authorized payment if needed, and persist the payment, discount and gift-card ledger entries.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

amountnumber | stringOptional

Amount to collect in major currency units; omit for the remaining balance. Cannot exceed balance due.

discountCodestringOptional

Optional lodging discount code.

giftCardNumberstringOptional

Optional gift card applied before card collection.

giftCardAmountnumberOptional

Requested gift-card contribution in major currency units.

stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive
paymentIntentIdstringOptional

Intent from /payments/intent; required when cash balance remains after adjustments.

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
  • Keep selection/amount identical to intent creation. Bank payments may be processing and are recorded as pending; do not interpret processing as settled funds.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/payments' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amount":300,"paymentIntentId":"pi_example"}'
Response · 201
JSON
{
  "payment": {
    "id": "payment_123",
    "amount": 300,
    "status": "succeeded",
    "source": "stripe"
  },
  "giftCardRedemption": null
}

Check whether a reusable card is available for this reservation and return masked card details for the collection dialog.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123/payments/card-on-file' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "available": true,
  "cardType": "visa",
  "cardLastFour": "4242",
  "cardholderName": "Alex Morgan",
  "transactionDate": "2027-05-01T12:00:00.000Z"
}

Immediately charge the saved card for the requested portion of the outstanding balance, apply optional discounts/gift cards, record the ledger and send payment receipts.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

amountnumber | stringOptional

Amount to collect in major currency units; omit for the remaining balance. Cannot exceed balance due.

discountCodestringOptional

Optional lodging discount code.

giftCardNumberstringOptional

Optional gift card applied before card collection.

giftCardAmountnumberOptional

Requested gift-card contribution in major currency units.

stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
  • This is a money-moving operation, not a quote. An amount over the remaining balance returns 409. Additional card authentication may require the interactive payment flow.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/payments/card-on-file' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amount":50}'
Response · 201
JSON
{
  "payment": {
    "id": "payment_123",
    "amount": 50,
    "status": "succeeded"
  },
  "paymentIntentId": "pi_example",
  "amount": 50,
  "totalPaid": 300,
  "balanceDue": 0,
  "guestPaymentEmailSent": true,
  "innPaymentEmailSent": true
}

Record a payment received outside Stripe, such as cash, against the reservation ledger. No card charge is made.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

amountnumber | stringOptional

Positive payment in major currency units; omit to record the entire remaining balance.

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
  • Requires a linked guest and a positive outstanding balance. Rejects overpayment.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/payments/manual' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amount":50}'
Response · 201
JSON
{
  "payment": {
    "id": "payment_123",
    "amount": 50,
    "source": "manual",
    "status": "succeeded"
  },
  "amount": 50,
  "remainingBalanceDue": 250
}

Create a card-present PaymentIntent for native iOS Tap to Pay. The iOS Terminal flow collects and confirms the card before the app records the result through the companion confirm endpoint.

Native iOS Tap to Pay payment sheet.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

amountCentsintegerRequired

Integer minor units: 1500 means $15.00 for USD. Must be positive and no more than the reservation balance.

currencystringOptional

Three-letter currency, normalized to lowercase; defaults to the configured payment currency.

paymentTypestringOptional

Payment purpose recorded in metadata.

Allowed valuesremaining_balancedepositcustom_amount
stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/payments/tap-to-pay/payment-intent' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amountCents":30000,"currency":"usd","paymentType":"remaining_balance"}'
Response · 200
JSON
{
  "paymentIntentClientSecret": "pi_example_secret_example",
  "paymentIntentId": "pi_example",
  "amountCents": 30000,
  "currency": "usd"
}

Record a succeeded Tap to Pay PaymentIntent in the reservation ledger after checking its property, reservation and card-present origin.

Native iOS Tap to Pay completion.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

paymentIntentIdstringRequired

Completed Terminal PaymentIntent ID.

stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Response fields

amountCentsintegerOptional

Integer minor units: 1500 means $15.00 for USD.

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
  • Only succeeded payments are accepted. Ledger recording is deduplicated by the payment reference.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/payments/tap-to-pay/confirm' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"paymentIntentId":"pi_example"}'
Response · 200
JSON
{
  "paymentLedgerEntryId": "payment_123",
  "reservationId": "reservation_123",
  "amountCents": 30000,
  "status": "succeeded"
}

Create a short-lived Stripe Terminal connection token and ensure a Terminal location for the property. Pass the returned secret to the Terminal SDK, then use locationId and merchantDisplayName when connecting the reader.

Used by the native innkeeper Tap to Pay reader setup.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Query parameters

stripeModestringOptional

Requested mode where environment policy allows overrides; otherwise server configuration controls the mode.

Allowed valuestestlive

Response fields

secretstringOptional

Sensitive, short-lived Terminal SDK credential. Do not store in logs or reuse as a payment credential.

locationIdstringOptional

Property Terminal location.

merchantDisplayNamestringOptional

Display name for reader presentation.

Behavior & constraints

  • Requires invoice.manage or financials.view. No request body. This does not create or capture a payment.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/stripe/terminal/connection-token' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "secret": "pst_example",
  "locationId": "tml_example",
  "merchantDisplayName": "Cedar Ridge Inn"
}

Receive signed Stripe events and reconcile successful payment intents with widget bookings, payment links, console payments, and Tap to Pay records. Unrecognized payment sources/events are acknowledged without creating a payment.

Stripe server-to-server payment reconciliation; not a guest or staff action endpoint.

Request headers

stripe-signaturestringRequired

Stripe's signature over the unmodified raw request body.

Body fields

idstringRequired

Stripe event ID.

typestringRequired

Handled event types. Other valid event types are acknowledged without reconciliation.

Allowed valuespayment_intent.succeededpayment_intent.payment_failed
data.objectobjectRequired

Stripe PaymentIntent event payload; preserve Stripe-generated metadata and raw body.

Response fields

reconciledstringOptional

Included for these reconciliation paths; Tap to Pay uses received=true without this field.

Allowed valuespayment_linkwidget_bookingconsole

Behavior & constraints

  • Configure Stripe to send events directly to this endpoint. Bearer tokens do not replace the webhook signature.
  • Webhook processing is a reconciliation fallback. A 200 acknowledgment alone does not guarantee every received event changed a reservation.
  • Missing/invalid signatures return 400. Widget/payment-link reconciliation failures can return 500 for provider retry.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/stripe/webhook' \
  -H 'Content-Type: application/json' \
  -H "Stripe-Signature: $STRIPE_SIGNATURE" --data-binary @stripe-event.json
Response · 200
JSON
{
  "received": true,
  "reconciled": "widget_booking"
}

API Reference

Properties

Read a property's ordered FAQs.

Path parameters

idstringRequired

Property ID.

Behavior & constraints

  • Requires property.manage. Separate property-owned data, not webpage settings. Responses are private/no-store. PUT replaces the list; [] clears it. Missing or null faqs is rejected. Questions and answers are trimmed plain text; up to 100 entries, question maximum 500 characters and answer maximum 10000 characters. No FAQs returns an empty array.
Request
cURL
curl 'https://api.wikiup.app/api/properties/property-123/faqs' \
  -H 'Authorization: Bearer <token>'
Example response
JSON
{
  "faqs": [
    {
      "question": "Is parking available?",
      "answer": "Parking is available in the driveway."
    }
  ]
}

Replace a property's ordered FAQs.

Path parameters

idstringRequired

Property ID.

Body fields

faqsarrayRequired

Ordered objects with required question and answer strings.

Behavior & constraints

  • Requires property.manage. Separate property-owned data, not webpage settings. Responses are private/no-store. PUT replaces the list; [] clears it. Missing or null faqs is rejected. Questions and answers are trimmed plain text; up to 100 entries, question maximum 500 characters and answer maximum 10000 characters. No FAQs returns an empty array.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/properties/property-123/faqs' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' --data '{"faqs":[{"question":"Is parking available?","answer":"Parking is available in the driveway."}]}'
Example response
JSON
{
  "faqs": [
    {
      "question": "Is parking available?",
      "answer": "Parking is available in the driveway."
    }
  ]
}

List the current user's property memberships, including each property and the effective access group, permissions, and owner flag.

The console property switcher and iOS onboarding use this list to select an accessible property.

Response fields

[].rolestring

Membership role label. Owner is the system owner role; custom groups may supply other labels.

[].isOwnerboolean

Whether the membership is the property's system owner.

[].permissionsstring[]

Effective permission keys; use these to decide which controls to offer.

Allowed valuesreservations.viewrooms.viewoperations.viewreservations.managereservations.import_exportrooms.manageoperations.managerates.manageaddons.manageinvoice.viewinvoice.managefinancials.viewproperty.managewidgets.manageteam.today.viewteam.today.editteam.tasks.viewteam.tasks.editteam.readings.viewteam.readings.editteam.calendar.viewteam.calendar.editteam.members.viewteam.members.editteam.groups.viewteam.groups.edit

Behavior & constraints

  • API key callers see only current memberships allowed by the key’s propertyIds list. An empty list is normal for a new account.
  • Returns a bare array of memberships, not a {properties: [...]} envelope. Membership propertyId is the context sent in x-property-id to scoped endpoints.
Request
cURL
curl 'https://api.wikiup.app/api/properties' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
[
  {
    "id": "membership_123",
    "uid": "user_123",
    "propertyId": "property_123",
    "role": "Owner",
    "groupId": null,
    "group": null,
    "isOwner": true,
    "permissions": [
      "reservations.view",
      "rooms.view",
      "operations.view",
      "reservations.manage",
      "reservations.import_export",
      "rooms.manage",
      "operations.manage",
      "rates.manage",
      "addons.manage",
      "invoice.view",
      "invoice.manage",
      "financials.view",
      "property.manage",
      "widgets.manage",
      "team.today.view",
      "team.today.edit",
      "team.tasks.view",
      "team.tasks.edit",
      "team.readings.view",
      "team.readings.edit",
      "team.calendar.view",
      "team.calendar.edit",
      "team.members.view",
      "team.members.edit",
      "team.groups.view",
      "team.groups.edit"
    ],
    "property": {
      "id": "property_123",
      "name": "Cedar Ridge Inn",
      "stayType": "inn",
      "tagLine": "A quiet mountain retreat",
      "publicLatitude": null,
      "publicLongitude": null,
      "timeZone": "America/Los_Angeles",
      "websiteUrl": "https://inn.example.com",
      "address": {
        "line1": "100 Main Street",
        "city": "Julian",
        "state": "CA",
        "postalCode": "92036",
        "country": "US"
      }
    }
  }
]

Create a property, postal address, owner membership, and initial settings in one request.

Used by the Create Property wizard and first-property onboarding in the console and iOS app.

Body fields

property.roomBookingModestringOptional

Booking model: named_rooms (default), room_types, or mixed. Existing omitted values retain named-room behavior.

propertyobjectRequired

Required wrapper for the property record.

property.namestringRequired

Guest-facing property name.

property.stayTypestring | nullOptional

Property lodging category, for example inn. Selected during creation and immutable afterward. PUT permits omission or the saved value; changing or clearing it returns 409.

property.tagLinestring | nullOptional

Short property tagline, at most 100 characters. Null clears it; omission preserves it on update. Stored and returned under this same name.

property.publicLocationSelectionobjectOptional

Signed address confirmation from POST /api/properties/location-lookup. Saves the publicLatitude/publicLongitude pair; direct coordinate injection is ignored. No source, status, precision or audit attributes are returned on Property. Ratings belong to the affiliate fetch=ratings expansion, not Property.

property.descriptionstring | nullOptional

Property description used in public content and fallback metadata.

property.emailstringRequired

Property contact email; also the fallback recipient for guest chat notifications.

property.phonestringRequired

Property contact phone number.

property.websiteUrlstring | nullOptional

Property website URL. Normalized on save; omit or clear when no website is configured.

property.logoUrlstring | nullOptional

Logo asset URL used by branding surfaces and transactional email.

property.coverPhotoUrlstring | nullOptional

Property cover photo asset URL.

property.timeZonestringOptional

IANA time-zone identifier, for example America/Los_Angeles. Used for property-local arrival dates, cutoffs, and dashboard days.

property.addressobjectRequired

Postal address object: line1, optional line2, city, state, postalCode, and optional country.

property.address.line1stringRequired

Required address field; send the property’s actual postal address.

property.address.citystringRequired

Required address field; send the property’s actual postal address.

property.address.statestringRequired

Required address field; send the property’s actual postal address.

property.address.postalCodestringRequired

Required address field; send the property’s actual postal address.

property.settingsobjectOptional

Optional initial settings using the property settings contract. Weekend days default to [5,6] and calling apps to [].

Behavior & constraints

  • Property and address IDs are generated by the server. Supplied property.id/address.id and nested members, accessGroups, webpage, or other relation records are ignored. Create supports only the documented core property/address fields and initial settings; it does not update an existing property or accept nested team membership.
  • The authenticated account becomes Owner automatically. The response is the new membership with its nested property, not just the property record. API key callers need read_write and propertyIds: null; a property-restricted key cannot create properties.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/properties' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"property":{"name":"Cedar Ridge Inn","phone":"+17605550100","email":"stay@example.com","timeZone":"America/Los_Angeles","address":{"line1":"100 Main Street","city":"Julian","state":"CA","postalCode":"92036","country":"US"}}}'
Response · 201
JSON
{
  "propertyId": "property_123",
  "uid": "user_123",
  "role": "Owner",
  "groupId": null,
  "isOwner": true,
  "permissions": [
    "reservations.view",
    "rooms.view",
    "operations.view",
    "reservations.manage",
    "reservations.import_export",
    "rooms.manage",
    "operations.manage",
    "rates.manage",
    "addons.manage",
    "invoice.view",
    "invoice.manage",
    "financials.view",
    "property.manage",
    "widgets.manage",
    "team.today.view",
    "team.today.edit",
    "team.tasks.view",
    "team.tasks.edit",
    "team.readings.view",
    "team.readings.edit",
    "team.calendar.view",
    "team.calendar.edit",
    "team.members.view",
    "team.members.edit",
    "team.groups.view",
    "team.groups.edit"
  ],
  "property": {
    "id": "property_123",
    "name": "Cedar Ridge Inn",
    "stayType": "inn",
    "tagLine": "A quiet mountain retreat",
    "publicLatitude": null,
    "publicLongitude": null,
    "timeZone": "America/Los_Angeles",
    "websiteUrl": "https://inn.example.com",
    "address": {
      "line1": "100 Main Street",
      "city": "Julian",
      "state": "CA",
      "postalCode": "92036",
      "country": "US"
    },
    "settings": {
      "id": "property_123",
      "propertyId": "property_123",
      "weekendDays": [
        5,
        6
      ],
      "callingApps": []
    }
  }
}

Retrieve a property and its address, with opt-in related records for settings, media, website configuration, and members.

Console property editors request only the relations needed by the active settings tab or Widget Studio.

Path parameters

idstringRequired

Property ID; the path selects property context for this endpoint.

Query parameters

embedcomma-separated stringOptional

Relation names to include. This is not a boolean. members requires Owner; settings requires property.manage; webpage and media/check-in relations require widgets.manage.

Allowed valuesmemberssettingswebpagegalleryheroGallerycheckinGallerycheckinSteps

Behavior & constraints

  • Unrequested optional relations are removed from the response. Address is always loaded. Membership is required even when no relations are requested.
Request
cURL
curl 'https://api.wikiup.app/api/properties/property_123?embed=settings' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "id": "property_123",
  "name": "Cedar Ridge Inn",
  "stayType": "inn",
  "tagLine": "A quiet mountain retreat",
  "publicLatitude": null,
  "publicLongitude": null,
  "timeZone": "America/Los_Angeles",
  "websiteUrl": "https://inn.example.com",
  "address": {
    "line1": "100 Main Street",
    "city": "Julian",
    "state": "CA",
    "postalCode": "92036",
    "country": "US"
  },
  "settings": {
    "id": "property_123",
    "propertyId": "property_123",
    "weekendDays": [
      5,
      6
    ],
    "checkinTime": "16:00",
    "checkoutTime": "11:00",
    "earlyCheckInEnabled": true,
    "earliestCheckinTime": "13:00",
    "earlyCheckInPrice": 15,
    "lateCheckOutEnabled": true,
    "latestCheckoutTime": "12:00",
    "lateCheckOutPrice": 15,
    "arrivalDepartureEnforcement": "none"
  }
}

Save the property's contact details, branding, time zone, and address. Requires property.manage.

Used by the property editor after editing property details and contact information.

Path parameters

idstringRequired

Existing property ID.

Body fields

idstringRequired

Send the existing property ID; it cannot be changed.

namestringOptional

Guest-facing property name.

stayTypestring | nullOptional

Property lodging category, for example inn. Selected during creation and immutable afterward. PUT permits omission or the saved value; changing or clearing it returns 409.

tagLinestring | nullOptional

Short property tagline, at most 100 characters. Null clears it; omission preserves it on update. Stored and returned under this same name.

publicLocationSelectionobjectOptional

Signed address confirmation from POST /api/properties/location-lookup. Saves the publicLatitude/publicLongitude pair; direct coordinate injection is ignored. No source, status, precision or audit attributes are returned on Property. Ratings belong to the affiliate fetch=ratings expansion, not Property.

descriptionstring | nullOptional

Property description used in public content and fallback metadata.

emailstringOptional

Property contact email; also the fallback recipient for guest chat notifications.

phonestringOptional

Property contact phone number.

instagramUrlstringOptional

Property Instagram URL; send an empty string when unused.

facebookUrlstringOptional

Property Facebook URL; send an empty string when unused.

websiteUrlstring | nullOptional

Property website URL. Normalized on save; omit or clear when no website is configured.

logoUrlstring | nullOptional

Logo asset URL used by branding surfaces and transactional email.

coverPhotoUrlstring | nullOptional

Property cover photo asset URL.

timeZonestringOptional

IANA time-zone identifier, for example America/Los_Angeles. Used for property-local arrival dates, cutoffs, and dashboard days.

addressobjectOptional

Postal address object: line1, optional line2, city, state, postalCode, and optional country.

Behavior & constraints

  • Send the complete editable property record fetched by GET. This handler saves the submitted record; it is not a partial PATCH contract.
  • settings and members are ignored here. Use the dedicated settings and team APIs. A nested address is saved separately while preserving its existing ID.
  • The response is {message, property}; an unchanged payload may return the message ‘No changes to property’.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/properties/property_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"id":"property_123","name":"Cedar Ridge Inn","stayType":"inn","tagLine":"A quiet mountain retreat","publicLatitude":null,"publicLongitude":null,"timeZone":"America/Los_Angeles","websiteUrl":"https://inn.example.com","address":{"line1":"100 Main Street","city":"Julian","state":"CA","postalCode":"92036","country":"US"}}'
Example response
JSON
{
  "message": "Property updated successfully.",
  "property": {
    "id": "property_123",
    "name": "Cedar Ridge Inn",
    "stayType": "inn",
    "tagLine": "A quiet mountain retreat",
    "publicLatitude": null,
    "publicLongitude": null,
    "timeZone": "America/Los_Angeles",
    "websiteUrl": "https://inn.example.com",
    "address": {
      "line1": "100 Main Street",
      "city": "Julian",
      "state": "CA",
      "postalCode": "92036",
      "country": "US"
    }
  }
}

Leave a property by removing the current non-owner user's membership.

Supports leaving a shared property. Owners use the reviewed deletion flow instead.

Path parameters

idstringRequired

Property to leave.

Behavior & constraints

  • Requires an interactive session; API keys cannot leave property membership.
  • Does not delete the property for other users. Owners receive 409 with code PROPERTY_DELETION_REVIEW_REQUIRED; call GET and POST /api/properties/{id}/deletion to review and delete a property.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/properties/property_123' \
  -H 'Authorization: Bearer <access-token>'
Response · 204
HTTP
(empty response body)

Read booking, tax, arrival/departure, calling, and guest-chat settings. Requires property.manage.

The console property settings editor and iOS property/arrival controls share these settings; hosted widgets read them when constructing booking quotes.

Path parameters

idstringRequired

Property ID.

Behavior & constraints

  • Returns the settings object directly, or null when none exists.
  • Enabling early arrival or late departure without a valid HH:mm time and nonnegative price returns 422. Each can be enabled independently.
  • Arrival/departure times are wall-clock times in the property's IANA time zone, not UTC timestamps.
Request
cURL
curl 'https://api.wikiup.app/api/properties/property_123/settings' \
  -H 'Authorization: Bearer <access-token>'
Response · 200
JSON
{
  "id": "property_123",
  "propertyId": "property_123",
  "weekendDays": [
    5,
    6
  ],
  "checkinTime": "16:00",
  "checkoutTime": "11:00",
  "earlyCheckInEnabled": true,
  "earliestCheckinTime": "13:00",
  "earlyCheckInPrice": 15,
  "lateCheckOutEnabled": true,
  "latestCheckoutTime": "12:00",
  "lateCheckOutPrice": 15,
  "arrivalDepartureEnforcement": "none"
}

Create initial property settings. Requires property.manage.

The console property settings editor and iOS property/arrival controls share these settings; hosted widgets read them when constructing booking quotes.

Path parameters

idstringRequired

Property ID.

Body fields

weekendDaysinteger[]Optional

Weekend rate days: 0 is Sunday, 6 is Saturday. Defaults to [5,6] (Friday and Saturday).

Allowed values0123456
checkinTimestring | nullOptional

Standard check-in in property-local 24-hour HH:mm (HH:mm:ss also accepted). Arrival-time fallback is 16:00.

checkoutTimestring | nullOptional

Standard check-out in property-local 24-hour HH:mm (HH:mm:ss also accepted). Departure fallback is 11:00.

earlyCheckInEnabledboolean | nullOptional

Enables guest purchase and charging for early arrival. Off unless enabled. Staff can still record a courtesy early arrival when charging is off.

earliestCheckinTimestring | nullOptional

Required as HH:mm when earlyCheckInEnabled is true; must be earlier than standard check-in. Used as the purchased arrival time and initial ETA.

earlyCheckInPricenumber | nullOptional

Required nonnegative finite amount in major currency units when early arrival charging is enabled; 15 means $15.00 for USD.

lateCheckOutEnabledboolean | nullOptional

Enables guest purchase and charging for late departure independently of early arrival.

latestCheckoutTimestring | nullOptional

Required as HH:mm when lateCheckOutEnabled is true; must be later than standard check-out.

lateCheckOutPricenumber | nullOptional

Required nonnegative finite amount in major currency units when late departure charging is enabled.

arrivalDepartureEnforcementstring | nullOptional

none leaves early-arrival enforcement to staff; strict requires confirmation of the early fee on qualifying early check-in status transitions. Late departure is never automatically applied.

Allowed valuesnonestrict
occupancyTaxRatenumber | nullOptional

Occupancy tax percentage, for example 8 for 8%.

taxablePeriodNightsinteger | nullOptional

Nonnegative maximum taxable stay length in nights. Occupancy tax applies when total nights are at or below this threshold; longer stays are exempt. Omission applies occupancy tax regardless of length.

occupancyTaxDescriptionstring | nullOptional

Label describing the occupancy tax on pricing surfaces.

salesTaxRatenumber | nullOptional

Sales tax percentage applied by the pricing service, for example 7.75.

callingAppsobject[] | nullOptional

Up to five custom calling choices. Each requires label (1–80 characters) and deepLinkUrl (max 2048), a valid URL template containing {phoneNumber}. Defaults to [].

autoSendGuestQuestionAnswersbooleanOptional

Enables eligible AI-generated guest-chat responses; separate from notification email delivery.

guestChatNotificationEmailstring | nullOptional

Email address shown as ‘Send guest chat messages to’ in property settings. An empty value falls back to the property's contact email.

bookingPoliciesobject | nullOptional

Contains cancellationSettings and reschedulingSettings. Send complete nested sections when updating; top-level settings merge does not deep-merge policy sections.

bookingPolicies.cancellationSettings.policyTitlestringOptional

Guest-facing policy heading.

bookingPolicies.cancellationSettings.policySummarystringOptional

Guest-facing policy summary.

bookingPolicies.cancellationSettings.cancellationPolicystringOptional

Whether this policy permits changes at any time or uses a fee/cutoff policy.

Allowed valuesanyTimefeeBased
bookingPolicies.cancellationSettings.cancellationFee.typestringOptional

Fee adjustment mode.

Allowed valuesFixedAmountPercentage
bookingPolicies.cancellationSettings.cancellationFee.valuenumberOptional

Fee amount in major units for FixedAmount, or percentage points for Percentage.

bookingPolicies.cancellationSettings.refundTypestringOptional

Policy outcome used when calculating the guest's quote.

Allowed valuesfullpartialnone
bookingPolicies.cancellationSettings.gracePeriodHoursAfterBookingnumberOptional

Grace period after booking, in hours.

bookingPolicies.cancellationSettings.cutoffDaysBeforeCheckinnumberOptional

Cutoff measured in days before check-in.

bookingPolicies.reschedulingSettings.policyTitlestringOptional

Guest-facing policy heading.

bookingPolicies.reschedulingSettings.policySummarystringOptional

Guest-facing policy summary.

bookingPolicies.reschedulingSettings.reschedulingPolicystringOptional

Whether this policy permits changes at any time or uses a fee/cutoff policy.

Allowed valuesanyTimefeeBased
bookingPolicies.reschedulingSettings.reschedulingFee.typestringOptional

Fee adjustment mode.

Allowed valuesFixedAmountPercentage
bookingPolicies.reschedulingSettings.reschedulingFee.valuenumberOptional

Fee amount in major units for FixedAmount, or percentage points for Percentage.

bookingPolicies.reschedulingSettings.rescheduleTypestringOptional

Policy outcome used when calculating the guest's quote.

Allowed valuesfullpartialnone
bookingPolicies.reschedulingSettings.gracePeriodHoursAfterBookingnumberOptional

Grace period after booking, in hours.

bookingPolicies.reschedulingSettings.cutoffDaysBeforeCheckinnumberOptional

Cutoff measured in days before check-in.

Behavior & constraints

  • Server sets propertyId from the path. PUT requires an existing settings record (404 otherwise) and forbids changing its id.
  • Enabling early arrival or late departure without a valid HH:mm time and nonnegative price returns 422. Each can be enabled independently.
  • Arrival/departure times are wall-clock times in the property's IANA time zone, not UTC timestamps.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/properties/property_123/settings' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"checkinTime":"16:00","checkoutTime":"11:00","earlyCheckInEnabled":true,"earliestCheckinTime":"13:00","earlyCheckInPrice":15}'
Response · 201
JSON
{
  "message": "Settings created.",
  "settings": {
    "id": "property_123",
    "propertyId": "property_123",
    "weekendDays": [
      5,
      6
    ],
    "checkinTime": "16:00",
    "checkoutTime": "11:00",
    "earlyCheckInEnabled": true,
    "earliestCheckinTime": "13:00",
    "earlyCheckInPrice": 15,
    "lateCheckOutEnabled": true,
    "latestCheckoutTime": "12:00",
    "lateCheckOutPrice": 15,
    "arrivalDepartureEnforcement": "none"
  }
}

Update existing property settings, merging supplied top-level values with saved values. Requires property.manage.

The console property settings editor and iOS property/arrival controls share these settings; hosted widgets read them when constructing booking quotes.

Path parameters

idstringRequired

Property ID.

Body fields

weekendDaysinteger[]Optional

Weekend rate days: 0 is Sunday, 6 is Saturday. Defaults to [5,6] (Friday and Saturday).

Allowed values0123456
checkinTimestring | nullOptional

Standard check-in in property-local 24-hour HH:mm (HH:mm:ss also accepted). Arrival-time fallback is 16:00.

checkoutTimestring | nullOptional

Standard check-out in property-local 24-hour HH:mm (HH:mm:ss also accepted). Departure fallback is 11:00.

earlyCheckInEnabledboolean | nullOptional

Enables guest purchase and charging for early arrival. Off unless enabled. Staff can still record a courtesy early arrival when charging is off.

earliestCheckinTimestring | nullOptional

Required as HH:mm when earlyCheckInEnabled is true; must be earlier than standard check-in. Used as the purchased arrival time and initial ETA.

earlyCheckInPricenumber | nullOptional

Required nonnegative finite amount in major currency units when early arrival charging is enabled; 15 means $15.00 for USD.

lateCheckOutEnabledboolean | nullOptional

Enables guest purchase and charging for late departure independently of early arrival.

latestCheckoutTimestring | nullOptional

Required as HH:mm when lateCheckOutEnabled is true; must be later than standard check-out.

lateCheckOutPricenumber | nullOptional

Required nonnegative finite amount in major currency units when late departure charging is enabled.

arrivalDepartureEnforcementstring | nullOptional

none leaves early-arrival enforcement to staff; strict requires confirmation of the early fee on qualifying early check-in status transitions. Late departure is never automatically applied.

Allowed valuesnonestrict
occupancyTaxRatenumber | nullOptional

Occupancy tax percentage, for example 8 for 8%.

taxablePeriodNightsinteger | nullOptional

Nonnegative maximum taxable stay length in nights. Occupancy tax applies when total nights are at or below this threshold; longer stays are exempt. Omission applies occupancy tax regardless of length.

occupancyTaxDescriptionstring | nullOptional

Label describing the occupancy tax on pricing surfaces.

salesTaxRatenumber | nullOptional

Sales tax percentage applied by the pricing service, for example 7.75.

callingAppsobject[] | nullOptional

Up to five custom calling choices. Each requires label (1–80 characters) and deepLinkUrl (max 2048), a valid URL template containing {phoneNumber}. Defaults to [].

autoSendGuestQuestionAnswersbooleanOptional

Enables eligible AI-generated guest-chat responses; separate from notification email delivery.

guestChatNotificationEmailstring | nullOptional

Email address shown as ‘Send guest chat messages to’ in property settings. An empty value falls back to the property's contact email.

bookingPoliciesobject | nullOptional

Contains cancellationSettings and reschedulingSettings. Send complete nested sections when updating; top-level settings merge does not deep-merge policy sections.

bookingPolicies.cancellationSettings.policyTitlestringOptional

Guest-facing policy heading.

bookingPolicies.cancellationSettings.policySummarystringOptional

Guest-facing policy summary.

bookingPolicies.cancellationSettings.cancellationPolicystringOptional

Whether this policy permits changes at any time or uses a fee/cutoff policy.

Allowed valuesanyTimefeeBased
bookingPolicies.cancellationSettings.cancellationFee.typestringOptional

Fee adjustment mode.

Allowed valuesFixedAmountPercentage
bookingPolicies.cancellationSettings.cancellationFee.valuenumberOptional

Fee amount in major units for FixedAmount, or percentage points for Percentage.

bookingPolicies.cancellationSettings.refundTypestringOptional

Policy outcome used when calculating the guest's quote.

Allowed valuesfullpartialnone
bookingPolicies.cancellationSettings.gracePeriodHoursAfterBookingnumberOptional

Grace period after booking, in hours.

bookingPolicies.cancellationSettings.cutoffDaysBeforeCheckinnumberOptional

Cutoff measured in days before check-in.

bookingPolicies.reschedulingSettings.policyTitlestringOptional

Guest-facing policy heading.

bookingPolicies.reschedulingSettings.policySummarystringOptional

Guest-facing policy summary.

bookingPolicies.reschedulingSettings.reschedulingPolicystringOptional

Whether this policy permits changes at any time or uses a fee/cutoff policy.

Allowed valuesanyTimefeeBased
bookingPolicies.reschedulingSettings.reschedulingFee.typestringOptional

Fee adjustment mode.

Allowed valuesFixedAmountPercentage
bookingPolicies.reschedulingSettings.reschedulingFee.valuenumberOptional

Fee amount in major units for FixedAmount, or percentage points for Percentage.

bookingPolicies.reschedulingSettings.rescheduleTypestringOptional

Policy outcome used when calculating the guest's quote.

Allowed valuesfullpartialnone
bookingPolicies.reschedulingSettings.gracePeriodHoursAfterBookingnumberOptional

Grace period after booking, in hours.

bookingPolicies.reschedulingSettings.cutoffDaysBeforeCheckinnumberOptional

Cutoff measured in days before check-in.

Behavior & constraints

  • Server sets propertyId from the path. PUT requires an existing settings record (404 otherwise) and forbids changing its id.
  • Enabling early arrival or late departure without a valid HH:mm time and nonnegative price returns 422. Each can be enabled independently.
  • Arrival/departure times are wall-clock times in the property's IANA time zone, not UTC timestamps.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/properties/property_123/settings' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"checkinTime":"16:00","checkoutTime":"11:00","earlyCheckInEnabled":true,"earliestCheckinTime":"13:00","earlyCheckInPrice":15}'
Response · 200
JSON
{
  "message": "Settings updated.",
  "settings": {
    "id": "property_123",
    "propertyId": "property_123",
    "weekendDays": [
      5,
      6
    ],
    "checkinTime": "16:00",
    "checkoutTime": "11:00",
    "earlyCheckInEnabled": true,
    "earliestCheckinTime": "13:00",
    "earlyCheckInPrice": 15,
    "lateCheckOutEnabled": true,
    "latestCheckoutTime": "12:00",
    "lateCheckOutPrice": 15,
    "arrivalDepartureEnforcement": "none"
  }
}

Review the impact and blockers for permanently deleting a property. Only the property owner can request this review.

Console and iOS deletion dialogs show the returned inventory before asking the owner to confirm.

Path parameters

idstringRequired

Property ID.

Response fields

reviewTokenstring

Opaque token tied to the reviewed property state; send it unchanged when confirming.

blockersstring[]

Reasons deletion cannot proceed, such as pending payments, outstanding gift-card balances, checked-in guests, or paid upcoming stays.

Behavior & constraints

  • Requires an interactive owner session; API keys cannot review or execute property deletion.
  • Review responses use Cache-Control: no-store. A changed property invalidates the previous review token.
Request
cURL
curl 'https://api.wikiup.app/api/properties/property_123/deletion' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "propertyId": "property_123",
  "propertyName": "Cedar Ridge Inn",
  "rooms": 4,
  "reservations": 10,
  "upcomingReservations": 0,
  "members": 2,
  "retainedPayments": 10,
  "blockers": [],
  "reviewToken": "review_token_from_server",
  "inProgress": false
}

Confirm or resume permanent property deletion using a current review token and the exact property name.

Called only after the owner reviews the impact in the console or iOS deletion dialog.

Path parameters

idstringRequired

Property ID.

Body fields

confirmationNamestringRequired

Exact propertyName returned by the review.

reviewTokenstringRequired

Token returned by GET /api/properties/{id}/deletion.

cancelUpcomingbooleanOptional

Must be true when the review has upcoming reservations.

Behavior & constraints

  • Requires an interactive owner session; API keys cannot delete properties.
  • Returns 409 for blockers, a changed review, missing confirmation, or writes still in progress. Re-fetch the review after a state change.
  • Removes the property, memberships, and related operational data/assets. Financial ledger records are retained with personal and reusable-payment data removed. This endpoint does not itself issue charges or refunds.
  • Only the owner who started an interrupted deletion can resume it. A completed retry returns {deleted:true}.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/properties/property_123/deletion' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"confirmationName":"Cedar Ridge Inn","reviewToken":"review_token_from_server","cancelUpcoming":false}'
Example response
JSON
{
  "deleted": true
}

List unfinished property deletions initiated by the current user so they can be resumed.

Account recovery and deletion screens use this list when a previous deletion was interrupted.

Behavior & constraints

  • Requires an interactive session; API keys cannot access deletion recovery.
  • Returns a bare array of deletion reviews with inProgress:true; [] means there are no pending deletions. No property header is required.
Request
cURL
curl 'https://api.wikiup.app/api/properties/deletions' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
[
  {
    "propertyId": "property_123",
    "propertyName": "Cedar Ridge Inn",
    "rooms": 4,
    "reservations": 10,
    "upcomingReservations": 0,
    "members": 2,
    "retainedPayments": 10,
    "blockers": [],
    "reviewToken": "review_token_from_server",
    "inProgress": true
  }
]

Read the ordered property listing photos and the ETag needed to save changes.

Path parameters

idstringRequired

Property identifier owned by the signed-in user.

Response fields

photosArray<object>Required

Photos in display order, first is cover. Empty when none are saved. maxItems: 10

photos[]objectRequired

A saved listing photo with its stable identity and optional group.

photos[].idstringRequired

Stable owner-facing photo identity, preserved when reordered or edited. minLength: 1

photos[].urlstringRequired

Property-owned image URL; existing legacy cover URLs may be retained.

photos[].descriptionstringRequired

Accessible image description, empty when unset. maxLength: 1000

photos[].groupstring | nullRequired

Optional normalized group label, null when ungrouped. maxLength: 80

Error responses

401
Not signed in.
403
Not a verified property owner session.
404
Property or supplied photo ID not found.
409
Another property edit or deletion is in progress.
412
ETag is stale; reload and reconcile changes.
422
Invalid photos, count, dimensions, duplicate or foreign URL.
428
If-Match is missing.
503
Photo validation or storage could not be confirmed.

Behavior & constraints

  • Private, no-store response. GET and successful PUT include an ETag header.
  • The current cover is retained until the first gallery save. Website slideshow/general-gallery images are not imported.
  • Affiliate GET /api/travel/listings/{listingId} returns these photos as coverImage/gallery/galleryGroups using the existing public image contract. Unit/room photos keep their existing source.
  • See /property-listing-photos.md for cURL calls and upload/save behavior.
Request
cURL
curl --fail-with-body 'https://api.wikiup.app/api/properties/property_example/listing-photos' \
  \
  -H 'Authorization: Bearer <session-token>' --include
Example response
JSON
{
  "photos": [
    {
      "id": "photo_example",
      "url": "/api/web-assets/properties/property_example/listing-photos/front.jpg",
      "description": "Front garden",
      "group": "front yard"
    },
    {
      "id": "photo_lounge",
      "url": "/api/web-assets/properties/property_example/listing-photos/lounge.jpg",
      "description": "Guest lounge",
      "group": "lounge"
    }
  ]
}
Response JSON schema

Replace the ordered listing photos; the first photo becomes the property cover.

Path parameters

idstringRequired

Property identifier owned by the signed-in user.

Request headers

If-MatchstringRequired

Exact ETag returned by the latest GET, including quotes.

Body fields

photosarrayRequired

Up to 10 ordered photos. First is cover; [] removes all photos. Existing id preserves identity; omit id for new uploads. Each entry accepts url (required), description (optional, max 1000), and group (optional, max 80, null clears). New or replaced images must be property-owned 16:9 uploads.

Response fields

photosArray<object>Required

Photos in display order, first is cover. Empty when none are saved. maxItems: 10

photos[]objectRequired

A saved listing photo with its stable identity and optional group.

photos[].idstringRequired

Stable owner-facing photo identity, preserved when reordered or edited. minLength: 1

photos[].urlstringRequired

Property-owned image URL; existing legacy cover URLs may be retained.

photos[].descriptionstringRequired

Accessible image description, empty when unset. maxLength: 1000

photos[].groupstring | nullRequired

Optional normalized group label, null when ungrouped. maxLength: 80

Error responses

401
Not signed in.
403
Not a verified property owner session.
404
Property or supplied photo ID not found.
409
Another property edit or deletion is in progress.
412
ETag is stale; reload and reconcile changes.
422
Invalid photos, count, dimensions, duplicate or foreign URL.
428
If-Match is missing.
503
Photo validation or storage could not be confirmed.

Behavior & constraints

  • Private, no-store response. GET and successful PUT include an ETag header.
  • The current cover is retained until the first gallery save. Website slideshow/general-gallery images are not imported.
  • Affiliate GET /api/travel/listings/{listingId} returns these photos as coverImage/gallery/galleryGroups using the existing public image contract. Unit/room photos keep their existing source.
  • See /property-listing-photos.md for cURL calls and upload/save behavior.
Request
cURL
curl --fail-with-body -X PUT 'https://api.wikiup.app/api/properties/property_example/listing-photos' \
  \
  -H 'Authorization: Bearer <session-token>' \
  \
  -H 'If-Match: "etag-from-get"' \
  \
  -H 'Content-Type: application/json' \
  --data '{"photos":[{"id":"photo_example","url":"/api/web-assets/properties/property_example/listing-photos/front.jpg","description":"Front garden","group":"front yard"},{"id":"photo_lounge","url":"/api/web-assets/properties/property_example/listing-photos/lounge.jpg","description":"Guest lounge","group":"lounge"}]}'
Example response
JSON
{
  "photos": [
    {
      "id": "photo_example",
      "url": "/api/web-assets/properties/property_example/listing-photos/front.jpg",
      "description": "Front garden",
      "group": "front yard"
    },
    {
      "id": "photo_lounge",
      "url": "/api/web-assets/properties/property_example/listing-photos/lounge.jpg",
      "description": "Guest lounge",
      "group": "lounge"
    }
  ]
}
Response JSON schema

API Reference

Property messaging

Load the property email branding theme and its optimistic concurrency revision.

Path parameters

idstringRequired

Property identifier. Requires property.manage for this property.

Error responses

409
Stale revision, reused request ID with different content, or concurrent mutation.
422
Invalid theme, image or website reference.
503
Storage/provider is unavailable or image support is not enabled.

Behavior & constraints

  • Requires property.manage. Responses are private, no-store.
  • An unsaved theme returns default values with a null revision and null image references. Empty chat has a null revision and an empty messages array.
  • Assistant patches update the editor draft only. Save theme persists branding. Existing authored email HTML is preserved.
  • Conversation messages include id, role, content and createdAt; assistant themePatch and user attachments/references are optional. Persisted attachments contain name, mediaType and canonical url.
  • Image analysis is unavailable until Onyx image forwarding is verified and enabled in the server configuration. Failed requests preserve drafts.
Request
cURL
curl 'https://api-preview.wikiup.app/api/properties/property-example/email-branding' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "version": "branding-v1",
  "theme": {
    "name": "Custom theme",
    "headerBg": "#436666",
    "headerText": "#f8e9dc",
    "bodyBg": "#ffffff",
    "bodyText": "#30402d",
    "accent": "#fb923c",
    "accentText": "#ffffff",
    "calloutBg": "#f7f2e8",
    "messageBg": "#eef5f2",
    "link": "#2499ba",
    "footerBg": "#f1e8dd",
    "divider": "#e5dccd",
    "font": "fraunces",
    "radius": 16,
    "panelRadius": 16,
    "panelBorderWidth": 1,
    "panelBorderColor": "#e5dccd",
    "logo": "/api/web-assets/properties/property-example/email-branding/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png",
    "banner": "/api/web-assets/properties/property-example/email-branding/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.jpg",
    "bannerPositionX": 50,
    "bannerPositionY": 50
  }
}

Persist the complete property email theme and durable logo/header assets.

Path parameters

idstringRequired

Property identifier. Requires property.manage for this property.

Body fields

versionstring | nullRequired

Last saved theme revision; null only before the first save. Stale revisions return 409.

themeBrandingThemeRequired

Complete theme replacement. All fields required; no unknown keys.

theme.namestringRequired

Trimmed theme name, 1–80 characters.

theme.headerBgstringRequired

Six-digit hex color.

theme.headerTextstringRequired

Six-digit hex color.

theme.bodyBgstringRequired

Six-digit hex color.

theme.bodyTextstringRequired

Six-digit hex color.

theme.accentstringRequired

Six-digit hex color.

theme.accentTextstringRequired

Six-digit hex color.

theme.calloutBgstringRequired

Six-digit hex color.

theme.messageBgstringRequired

Six-digit hex color.

theme.linkstringRequired

Six-digit hex color.

theme.footerBgstringRequired

Six-digit hex color.

theme.dividerstringRequired

Six-digit hex color.

theme.fontstringRequired

One of fraunces, georgia, palatino, times, trebuchet, verdana, arial, sans, inter.

theme.radiusnumberRequired

Even integer 0–28 for button corners.

theme.panelRadiusnumberRequired

Even integer 0–32 for panels.

theme.panelBorderWidthnumberRequired

Integer 0–8 pixels; zero removes borders.

theme.panelBorderColorstringRequired

Six-digit hex color.

theme.logostring | nullRequired

Owned image URL or PNG/JPEG/WebP data URL up to 5 MB decoded; null removes it. Canonical durable URL returned after saving.

theme.bannerstring | nullRequired

Owned image URL or PNG/JPEG/WebP data URL up to 5 MB decoded; null removes it. Canonical durable URL returned after saving.

theme.bannerPositionXnumberRequired

Integer 0–100 percent.

theme.bannerPositionYnumberRequired

Integer 0–100 percent.

Error responses

409
Stale revision, reused request ID with different content, or concurrent mutation.
422
Invalid theme, image or website reference.
503
Storage/provider is unavailable or image support is not enabled.

Behavior & constraints

  • Requires property.manage. Responses are private, no-store.
  • An unsaved theme returns default values with a null revision and null image references. Empty chat has a null revision and an empty messages array.
  • Assistant patches update the editor draft only. Save theme persists branding. Existing authored email HTML is preserved.
  • Conversation messages include id, role, content and createdAt; assistant themePatch and user attachments/references are optional. Persisted attachments contain name, mediaType and canonical url.
  • Image analysis is unavailable until Onyx image forwarding is verified and enabled in the server configuration. Failed requests preserve drafts.
Request
cURL
curl -X PUT 'https://api-preview.wikiup.app/api/properties/property-example/email-branding' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' --data '{"version":"branding-v1","theme":{"name":"Custom theme","headerBg":"#436666","headerText":"#f8e9dc","bodyBg":"#ffffff","bodyText":"#30402d","accent":"#fb923c","accentText":"#ffffff","calloutBg":"#f7f2e8","messageBg":"#eef5f2","link":"#2499ba","footerBg":"#f1e8dd","divider":"#e5dccd","font":"fraunces","radius":16,"panelRadius":16,"panelBorderWidth":1,"panelBorderColor":"#e5dccd","logo":"/api/web-assets/properties/property-example/email-branding/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png","banner":"/api/web-assets/properties/property-example/email-branding/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.jpg","bannerPositionX":50,"bannerPositionY":50}}'
Example response
JSON
{
  "version": "branding-v1",
  "theme": {
    "name": "Custom theme",
    "headerBg": "#436666",
    "headerText": "#f8e9dc",
    "bodyBg": "#ffffff",
    "bodyText": "#30402d",
    "accent": "#fb923c",
    "accentText": "#ffffff",
    "calloutBg": "#f7f2e8",
    "messageBg": "#eef5f2",
    "link": "#2499ba",
    "footerBg": "#f1e8dd",
    "divider": "#e5dccd",
    "font": "fraunces",
    "radius": 16,
    "panelRadius": 16,
    "panelBorderWidth": 1,
    "panelBorderColor": "#e5dccd",
    "logo": "/api/web-assets/properties/property-example/email-branding/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png",
    "banner": "/api/web-assets/properties/property-example/email-branding/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.jpg",
    "bannerPositionX": 50,
    "bannerPositionY": 50
  }
}

Load the single property-scoped email theme assistant conversation history.

Path parameters

idstringRequired

Property identifier. Requires property.manage for this property.

Error responses

409
Stale revision, reused request ID with different content, or concurrent mutation.
422
Invalid theme, image or website reference.
503
Storage/provider is unavailable or image support is not enabled.

Behavior & constraints

  • Requires property.manage. Responses are private, no-store.
  • An unsaved theme returns default values with a null revision and null image references. Empty chat has a null revision and an empty messages array.
  • Assistant patches update the editor draft only. Save theme persists branding. Existing authored email HTML is preserved.
  • Conversation messages include id, role, content and createdAt; assistant themePatch and user attachments/references are optional. Persisted attachments contain name, mediaType and canonical url.
  • Image analysis is unavailable until Onyx image forwarding is verified and enabled in the server configuration. Failed requests preserve drafts.
Request
cURL
curl 'https://api-preview.wikiup.app/api/properties/property-example/email-branding/chat' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "version": "chat-v2",
  "messages": [
    {
      "id": "message-1",
      "role": "user",
      "content": "Match https://example.com",
      "createdAt": "2026-11-17T20:00:00.000Z"
    },
    {
      "id": "message-2",
      "role": "assistant",
      "content": "I warmed the header.",
      "createdAt": "2026-11-17T20:00:02.000Z",
      "themePatch": {
        "headerBg": "#674d3c"
      }
    }
  ]
}

Generate and persist an Onyx assistant reply and validated draft theme changes.

Path parameters

idstringRequired

Property identifier. Requires property.manage for this property.

Body fields

requestIdstringRequired

UUID retry idempotency key; reuse only for the identical request.

versionstring | nullRequired

Last conversation version; null for first turn.

messagestringRequired

1–4000 characters. Include public website URLs directly in the text; up to three references.

themeBrandingThemeRequired

Complete theme replacement. All fields required; no unknown keys.

theme.namestringRequired

Trimmed theme name, 1–80 characters.

theme.headerBgstringRequired

Six-digit hex color.

theme.headerTextstringRequired

Six-digit hex color.

theme.bodyBgstringRequired

Six-digit hex color.

theme.bodyTextstringRequired

Six-digit hex color.

theme.accentstringRequired

Six-digit hex color.

theme.accentTextstringRequired

Six-digit hex color.

theme.calloutBgstringRequired

Six-digit hex color.

theme.messageBgstringRequired

Six-digit hex color.

theme.linkstringRequired

Six-digit hex color.

theme.footerBgstringRequired

Six-digit hex color.

theme.dividerstringRequired

Six-digit hex color.

theme.fontstringRequired

One of fraunces, georgia, palatino, times, trebuchet, verdana, arial, sans, inter.

theme.radiusnumberRequired

Even integer 0–28 for button corners.

theme.panelRadiusnumberRequired

Even integer 0–32 for panels.

theme.panelBorderWidthnumberRequired

Integer 0–8 pixels; zero removes borders.

theme.panelBorderColorstringRequired

Six-digit hex color.

theme.logostring | nullRequired

Owned image URL or PNG/JPEG/WebP data URL up to 5 MB decoded; null removes it. Canonical durable URL returned after saving.

theme.bannerstring | nullRequired

Owned image URL or PNG/JPEG/WebP data URL up to 5 MB decoded; null removes it. Canonical durable URL returned after saving.

theme.bannerPositionXnumberRequired

Integer 0–100 percent.

theme.bannerPositionYnumberRequired

Integer 0–100 percent.

attachmentsArray<{name:string;mediaType:string;dataUrl:string}>Optional

Optional up to three PNG/JPEG/WebP images, each at most 5 MB decoded. Omit when unused.

Error responses

409
Stale revision, reused request ID with different content, or concurrent mutation.
422
Invalid theme, image or website reference.
503
Storage/provider is unavailable or image support is not enabled.

Behavior & constraints

  • Requires property.manage. Responses are private, no-store.
  • An unsaved theme returns default values with a null revision and null image references. Empty chat has a null revision and an empty messages array.
  • Assistant patches update the editor draft only. Save theme persists branding. Existing authored email HTML is preserved.
  • Conversation messages include id, role, content and createdAt; assistant themePatch and user attachments/references are optional. Persisted attachments contain name, mediaType and canonical url.
  • Image analysis is unavailable until Onyx image forwarding is verified and enabled in the server configuration. Failed requests preserve drafts.
Request
cURL
curl -X POST 'https://api-preview.wikiup.app/api/properties/property-example/email-branding/chat' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' --data '{"requestId":"e67dc705-e695-4e53-b46b-f4cdadbf64ae","version":"chat-v1","message":"Match https://example.com","theme":{"name":"Custom theme","headerBg":"#436666","headerText":"#f8e9dc","bodyBg":"#ffffff","bodyText":"#30402d","accent":"#fb923c","accentText":"#ffffff","calloutBg":"#f7f2e8","messageBg":"#eef5f2","link":"#2499ba","footerBg":"#f1e8dd","divider":"#e5dccd","font":"fraunces","radius":16,"panelRadius":16,"panelBorderWidth":1,"panelBorderColor":"#e5dccd","logo":"/api/web-assets/properties/property-example/email-branding/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png","banner":"/api/web-assets/properties/property-example/email-branding/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.jpg","bannerPositionX":50,"bannerPositionY":50},"attachments":[{"name":"forest.jpg","mediaType":"image/jpeg","dataUrl":"data:image/jpeg;base64,<encoded-image-bytes>"}]}'
Example response
JSON
{
  "requestId": "e67dc705-e695-4e53-b46b-f4cdadbf64ae",
  "version": "chat-v2",
  "messages": [
    {
      "id": "message-1",
      "role": "user",
      "content": "Match https://example.com",
      "createdAt": "2026-11-17T20:00:00.000Z"
    },
    {
      "id": "message-2",
      "role": "assistant",
      "content": "I warmed the header.",
      "createdAt": "2026-11-17T20:00:02.000Z",
      "themePatch": {
        "headerBg": "#674d3c"
      }
    }
  ]
}

Read the property's saved confirmation, room-ready, payment-link, modification, and gift-card email templates. Requires property.manage.

The property email editor loads these values before previewing or editing branded messages.

Path parameters

idstringRequired

Property ID.

Behavior & constraints

  • Returns the settings object directly, or null if none is available.
Request
cURL
curl 'https://api.wikiup.app/api/properties/property_123/email-settings' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "id": "property_123",
  "propertyId": "property_123",
  "body": "<p>Thank you for booking with us.</p>",
  "eviteSummary": "Your stay",
  "eviteDescription": "We look forward to welcoming you.",
  "eviteLocation": "Cedar Ridge Inn"
}

Create or save email templates, normalizing hardcoded guest-portal and check-in links into dynamic tokens. Requires property.manage.

The console email editor saves the complete template settings, then shows any returned link-safety warnings.

Path parameters

idstringRequired

Property ID.

Body fields

bodystringOptional

Reservation confirmation HTML template.

eviteSummarystringOptional

Calendar invite title template.

eviteDescriptionstringOptional

Calendar invite description template.

eviteLocationstringOptional

Calendar invite location template.

roomReadySubjectstringOptional

Subject template for this email type.

roomReadyMessagestringOptional

HTML message template for this email type.

paymentLinkSubjectstringOptional

Subject template for this email type.

paymentLinkMessagestringOptional

HTML message template for this email type.

reservationModificationSubjectstringOptional

Subject template for this email type.

reservationModificationMessagestringOptional

HTML message template for this email type.

giftCardSubjectstringOptional

Subject template for this email type.

giftCardMessagestringOptional

HTML message template for this email type.

Behavior & constraints

  • Returns 201 on first creation and 200 when a record exists. The response includes {message, settings, warnings}.
  • Send the complete editable settings object; this handler saves supplied values rather than merging all omitted fields with the old record. IDs are assigned by the server.
  • Confirmation-body and room-ready links to fixed guest pages are replaced with {guestPortalUrl} or {checkinGuideUrl}. The warnings array also flags unsafe preview/local URLs; it is not a general HTML sanitizer.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/properties/property_123/email-settings' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"body":"<p>Thank you for booking with us.</p>","eviteSummary":"Your stay","eviteDescription":"Welcome to Cedar Ridge Inn.","eviteLocation":"Cedar Ridge Inn","roomReadySubject":"Your room is ready","roomReadyMessage":"<p>We look forward to welcoming you.</p>"}'
Example response
JSON
{
  "message": "Settings updated.",
  "settings": {
    "id": "property_123",
    "propertyId": "property_123",
    "roomReadySubject": "Your room is ready",
    "roomReadyMessage": "<p>We look forward to welcoming you.</p>"
  },
  "warnings": []
}

Send an actual sample email through the property's connected Google mailbox, using saved templates with optional unsaved overrides. Requires property.manage.

The console email editor's test action verifies the selected message before saving it.

Path parameters

idstringRequired

Property ID. Also send the same property in x-property-id.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

kindstringOptional

Email type to send. Defaults to reservation.

Allowed valuesreservationroomReadypaymentLinkreservationModificationgiftCard
bodystringOptional

Reservation confirmation HTML template.

eviteSummarystringOptional

Calendar invite title template.

eviteDescriptionstringOptional

Calendar invite description template.

eviteLocationstringOptional

Calendar invite location template.

roomReadySubjectstringOptional

Subject template for this email type.

roomReadyMessagestringOptional

HTML message template for this email type.

paymentLinkSubjectstringOptional

Subject template for this email type.

paymentLinkMessagestringOptional

HTML message template for this email type.

reservationModificationSubjectstringOptional

Subject template for this email type.

reservationModificationMessagestringOptional

HTML message template for this email type.

giftCardSubjectstringOptional

Subject template for this email type.

giftCardMessagestringOptional

HTML message template for this email type.

Behavior & constraints

  • A Google email connection is required. The recipient is the connected mailbox's +test alias, not a guest or arbitrary to address.
  • Uses sample reservation/gift-card data; overrides affect this email only. Returns 400 for an unknown kind.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/properties/property_123/test-email' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"roomReady","roomReadySubject":"Your room is ready","roomReadyMessage":"<p>Welcome! Your room is ready.</p>"}'
Example response
JSON
{
  "success": true,
  "kind": "roomReady"
}

Send a room-ready sample email to the connected Google mailbox's +test alias. Requires property.manage.

A dedicated room-ready template test action; the general test-email endpoint also supports kind:roomReady.

Path parameters

idstringRequired

Property ID; match it in x-property-id.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

roomReadySubjectstringOptional

Subject template for the sample email.

roomReadyMessagestringOptional

HTML template for the sample email.

Behavior & constraints

  • This sends a real email using sample stay details. It does not mark an actual room ready or alter a reservation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/properties/property_123/test-room-ready-email' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"roomReadySubject":"Your room is ready","roomReadyMessage":"<p>Your room is ready for arrival.</p>"}'
Example response
JSON
{
  "success": true
}

List the five standard email templates plus saved custom templates, with the confirmation-colored starter document and placeholder groups. Requires property.manage or reservations.manage.

The property email tab adds custom templates beside the standard ones. The innkeeper app uses the same catalog for its message template menu.

Path parameters

idstringRequired

Property ID.

Behavior & constraints

  • GET returns {templates, starterBody, fields}. starterBody is a full HTML document using the reservation confirmation palette.
  • POST returns 201 and PUT returns 200 with the saved template and a warnings array. DELETE returns 204.
  • Standard template ids are reservation, roomReady, paymentLink, reservationModification, and giftCard. Only reservation and roomReady set canSend.
Request
cURL
curl 'https://api.wikiup.app/api/properties/property_123/email-templates' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "templates": [],
  "starterBody": "<!DOCTYPE html><html><body><p>Dear {guestFirstName},</p></body></html>",
  "fields": [
    {
      "name": "Guest",
      "fields": [
        {
          "label": "Guest First Name",
          "value": "{guestFirstName}"
        }
      ]
    }
  ]
}

Create a custom email template. The body starts from the reservation confirmation palette when the editor requests the catalog. Requires property.manage.

The property email tab adds custom templates beside the standard ones. The innkeeper app uses the same catalog for its message template menu.

Path parameters

idstringRequired

Property ID.

Body fields

titlestringRequired

Custom template title, 1–80 characters. It cannot match a standard template name.

subjectstringRequired

Email subject, 1–180 characters. For the reservation template this is the evite summary.

bodystringRequired

Email HTML. Guest-portal and check-in links are rewritten to dynamic tokens.

eviteDescriptionstringOptional

Reservation template only.

eviteLocationstringOptional

Reservation template only.

Behavior & constraints

  • GET returns {templates, starterBody, fields}. starterBody is a full HTML document using the reservation confirmation palette.
  • POST returns 201 and PUT returns 200 with the saved template and a warnings array. DELETE returns 204.
  • Standard template ids are reservation, roomReady, paymentLink, reservationModification, and giftCard. Only reservation and roomReady set canSend.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/properties/property_123/email-templates' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Late checkout","subject":"Staying a little later","body":"<p>Dear {guestFirstName}, your late checkout is confirmed.</p>"}'
Example response
JSON
{
  "id": "template_123",
  "source": "custom",
  "title": "Late checkout",
  "subject": "Staying a little later",
  "body": "<p>Dear {guestFirstName}, your late checkout is confirmed.</p>",
  "canDelete": true,
  "canSend": false,
  "warnings": []
}

Update a custom template, or the subject and body of a standard template. Requires property.manage.

The property email tab adds custom templates beside the standard ones. The innkeeper app uses the same catalog for its message template menu.

Path parameters

idstringRequired

Property ID.

Query parameters

templateIdstringRequired

Custom template ID, or reservation, roomReady, paymentLink, reservationModification, or giftCard.

Body fields

titlestringOptional

Custom template title, 1–80 characters. It cannot match a standard template name.

subjectstringRequired

Email subject, 1–180 characters. For the reservation template this is the evite summary.

bodystringRequired

Email HTML. Guest-portal and check-in links are rewritten to dynamic tokens.

eviteDescriptionstringOptional

Reservation template only.

eviteLocationstringOptional

Reservation template only.

Behavior & constraints

  • GET returns {templates, starterBody, fields}. starterBody is a full HTML document using the reservation confirmation palette.
  • POST returns 201 and PUT returns 200 with the saved template and a warnings array. DELETE returns 204.
  • Standard template ids are reservation, roomReady, paymentLink, reservationModification, and giftCard. Only reservation and roomReady set canSend.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/properties/property_123/email-templates' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Late checkout","subject":"Staying a little later","body":"<p>Dear {guestFirstName}, your late checkout is confirmed.</p>"}'
Example response
JSON
{
  "id": "template_123",
  "source": "custom",
  "title": "Late checkout",
  "subject": "Staying a little later",
  "body": "<p>Dear {guestFirstName}, your late checkout is confirmed.</p>",
  "canDelete": true,
  "canSend": false,
  "warnings": []
}

Delete a custom email template. Standard templates cannot be deleted. Requires property.manage.

The property email tab adds custom templates beside the standard ones. The innkeeper app uses the same catalog for its message template menu.

Path parameters

idstringRequired

Property ID.

Query parameters

templateIdstringRequired

Custom template ID.

Behavior & constraints

  • GET returns {templates, starterBody, fields}. starterBody is a full HTML document using the reservation confirmation palette.
  • POST returns 201 and PUT returns 200 with the saved template and a warnings array. DELETE returns 204.
  • Standard template ids are reservation, roomReady, paymentLink, reservationModification, and giftCard. Only reservation and roomReady set canSend.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/properties/property_123/email-templates' \
  -H 'Authorization: Bearer <access-token>'
Response · 204
HTTP
(empty response body)

List named SMS templates alphabetically, optionally rendered for a reservation. Requires property.manage or reservations.view.

Property texting settings manage templates; console and iOS reservation message composers request rendered text to hand off to the device's messaging app.

Path parameters

idstringRequired

Property ID.

Query parameters

reservationIdstringOptional

Optional reservation belonging to this property. Adds renderedBody to every returned template.

Behavior & constraints

  • This endpoint stores or renders text; it does not send SMS. Duplicate names return 409; invalid lengths or unsupported placeholders return 422.
  • A supplied reservationId must identify a guest reservation, not a blockout, in this property (404 otherwise).
Request
cURL
curl 'https://api.wikiup.app/api/properties/property_123/text-message-templates' \
  -H 'Authorization: Bearer <access-token>'
Response · 200
JSON
[
  {
    "id": "template_123",
    "propertyId": "property_123",
    "name": "Welcome",
    "body": "Hi {guestFirstName}, your stay at {propertyListingTitle} begins {reservation.startLabel}.",
    "createdAt": "2026-10-22T12:00:00Z",
    "updatedAt": "2026-10-22T12:00:00Z"
  }
]

Create a reusable plain-text message template. Requires property.manage.

Property texting settings manage templates; console and iOS reservation message composers request rendered text to hand off to the device's messaging app.

Path parameters

idstringRequired

Property ID.

Body fields

namestringRequired

Trimmed name, 1–80 characters. Must be unique within the property, ignoring case.

bodystringRequired

Plain text, 1–1000 characters. Supported placeholders are replaced only when rendering for a reservation.

body placeholdersstring tokensOptional

Allowed brace tokens inside body; other brace-delimited placeholders cause 422.

Allowed values{eviteSummary}{eviteDescription}{eviteLocation}{guestName}{guestFirstName}{guestLastName}{guestEmail}{guestPhone}{userFirstName}{reservation.start}{reservation.confirmationNumber}{reservation.startLabel}{reservation.end}{reservation.endLabel}{reservation.statusLabel}{reservation.details.adultsCount}{reservation.details.childrenCount}{reservation.totalGuests}{reservation.guestSummary}{reservation.notes}{propertyListingTitle}{propertyWebsiteUrl}{propertyContactEmail}{propertyContactPhone}{propertyStreetAddress}{propertyCity}{propertyState}{propertyZip}{propertyAddress}{room.name}{checkinGuideUrl}{currentYear}

Behavior & constraints

  • This endpoint stores or renders text; it does not send SMS. Duplicate names return 409; invalid lengths or unsupported placeholders return 422.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/properties/property_123/text-message-templates' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Welcome","body":"Hi {guestFirstName}, your stay at {propertyListingTitle} begins {reservation.startLabel}."}'
Response · 201
JSON
{
  "id": "template_123",
  "propertyId": "property_123",
  "name": "Welcome",
  "body": "Hi {guestFirstName}, your stay at {propertyListingTitle} begins {reservation.startLabel}.",
  "createdAt": "2026-10-22T12:00:00Z",
  "updatedAt": "2026-10-22T12:00:00Z"
}

Replace a named message template's name and body. Requires property.manage.

Property texting settings manage templates; console and iOS reservation message composers request rendered text to hand off to the device's messaging app.

Path parameters

idstringRequired

Property ID.

Query parameters

templateIdstringRequired

ID of the existing template.

Body fields

namestringRequired

Trimmed name, 1–80 characters. Must be unique within the property, ignoring case.

bodystringRequired

Plain text, 1–1000 characters. Supported placeholders are replaced only when rendering for a reservation.

body placeholdersstring tokensOptional

Allowed brace tokens inside body; other brace-delimited placeholders cause 422.

Allowed values{eviteSummary}{eviteDescription}{eviteLocation}{guestName}{guestFirstName}{guestLastName}{guestEmail}{guestPhone}{userFirstName}{reservation.start}{reservation.confirmationNumber}{reservation.startLabel}{reservation.end}{reservation.endLabel}{reservation.statusLabel}{reservation.details.adultsCount}{reservation.details.childrenCount}{reservation.totalGuests}{reservation.guestSummary}{reservation.notes}{propertyListingTitle}{propertyWebsiteUrl}{propertyContactEmail}{propertyContactPhone}{propertyStreetAddress}{propertyCity}{propertyState}{propertyZip}{propertyAddress}{room.name}{checkinGuideUrl}{currentYear}

Behavior & constraints

  • This endpoint stores or renders text; it does not send SMS. Duplicate names return 409; invalid lengths or unsupported placeholders return 422.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/properties/property_123/text-message-templates?templateId=template_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Welcome","body":"Hi {guestFirstName}, your stay at {propertyListingTitle} begins {reservation.startLabel}."}'
Response · 200
JSON
{
  "id": "template_123",
  "propertyId": "property_123",
  "name": "Welcome",
  "body": "Hi {guestFirstName}, your stay at {propertyListingTitle} begins {reservation.startLabel}.",
  "createdAt": "2026-10-22T12:00:00Z",
  "updatedAt": "2026-10-22T12:00:00Z"
}

Delete a named message template. Requires property.manage.

Property texting settings manage templates; console and iOS reservation message composers request rendered text to hand off to the device's messaging app.

Path parameters

idstringRequired

Property ID.

Query parameters

templateIdstringRequired

ID of the existing template.

Behavior & constraints

  • This endpoint stores or renders text; it does not send SMS. Duplicate names return 409; invalid lengths or unsupported placeholders return 422.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/properties/property_123/text-message-templates?templateId=template_123' \
  -H 'Authorization: Bearer <access-token>'
Response · 204
HTTP
(empty response body)

API Reference

Rates & Discounts

List reusable property rate rules, optionally filtering by rule type. Assign a rule to room pricing to make it participate in future stay calculations.

Console rates/room-pricing editors and native reservation pricing adjustments.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

ruleTypestringOptional

Include only this type.

Allowed valuesSeasonalLengthOfStayFrequentGuestHolidayWeekendDiscount
ruleTypeNotstringOptional

Exclude this type.

Allowed valuesSeasonalLengthOfStayFrequentGuestHolidayWeekendDiscount

Behavior & constraints

  • Requires rates.manage.
Request
cURL
curl 'https://api.wikiup.app/api/price-rules' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
[
  {
    "id": "rule_123",
    "propertyId": "PROPERTY_ID",
    "label": "Summer season",
    "type": "Seasonal",
    "appliesTo": "Both",
    "adjustment": {
      "type": "FixedAmount",
      "value": 20
    },
    "processOrder": 1,
    "status": "Active",
    "stackable": true,
    "range": {
      "start": "Jun 01",
      "end": "Aug 31"
    }
  }
]

Create a reusable rate rule and optionally attach it to the supplied rooms' pricing records. Different rule kinds cover seasonal rates, length of stay, frequent guests, holiday weekends and explicit discounts.

Console rate-rule creation and native reservation discounts.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

labelstringRequired

Rate rule display label.

typestringRequired

Rule kind; cannot be changed after creation.

Allowed valuesSeasonalLengthOfStayFrequentGuestHolidayWeekendDiscount
appliesTostringRequired

Which nights the rule affects.

Allowed valuesWeekdaysWeekendsBoth
adjustmentobjectRequired

Price adjustment with type and value.

adjustment.typestringRequired

Whether the adjustment is a currency amount or percentage.

Allowed valuesFixedAmountPercentage
adjustment.valuenumberRequired

Signed adjustment; negative values reduce price. FixedAmount uses major currency units.

processOrderintegerRequired

Positive rule application order; zero is rejected by the current service.

statusstringOptional

Active rules participate in pricing.

Allowed valuesActiveInactive
stackablebooleanOptional

Whether this rule can be combined with other eligible rules.

discountApplicationstringOptional

For Discount rules: per-night versus once per stay.

Allowed valuesPerNightPerStay
rangeobject | nullOptional

Seasonal dates require a real month and day: {start:"Jun 01", end:"Aug 31"}. Full English month names and case/whitespace variants are accepted and normalized to MMM DD; month-only, arbitrary strings, and impossible dates return 400. Year-crossing ranges and Feb 29 are supported.

minimumNightsintegerOptional

LengthOfStay minimum stay length.

maximumNightsintegerOptional

Optional LengthOfStay maximum stay length.

daysInAdvanceintegerOptional

Minimum advance booking period.

requiredFrequencyintegerOptional

FrequentGuest required past-stay count.

termInDaysintegerOptional

FrequentGuest lookback period.

holidays(string | {name:string,date:string})[]Optional

HolidayWeekend named holidays; legacy objects use name to resolve dates annually. The date property does not override the named holiday calculation.

Allowed valuesNewYearsDayValentinesDayMemorialDayIndependenceDayLaborDayThanksgivingChristmas
roomIdsstring[]Optional

Rooms to assign immediately; only existing room pricing records are attached.

Behavior & constraints

  • Requires rates.manage. IDs and property are assigned by the server.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/price-rules' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"label":"Summer season","type":"Seasonal","appliesTo":"Both","adjustment":{"type":"FixedAmount","value":20},"processOrder":1,"status":"Active","stackable":true,"range":{"start":"Jun 01","end":"Aug 31"},"roomIds":["room_123"]}'
Response · 201
JSON
{
  "id": "rule_123",
  "propertyId": "PROPERTY_ID",
  "label": "Summer season",
  "type": "Seasonal",
  "appliesTo": "Both",
  "adjustment": {
    "type": "FixedAmount",
    "value": 20
  },
  "processOrder": 1,
  "status": "Active",
  "stackable": true,
  "range": {
    "start": "Jun 01",
    "end": "Aug 31"
  }
}

Read a reusable price rule and its reservation usage before staging a delete.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires property access. This read does not delete or unassign the rule; DELETE rechecks reservation usage.
Request
cURL
curl 'https://api.wikiup.app/api/price-rules/rule_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "rule": {
    "id": "rule_123",
    "propertyId": "PROPERTY_ID",
    "label": "Summer season",
    "type": "Seasonal",
    "appliesTo": "Both",
    "adjustment": {
      "type": "FixedAmount",
      "value": 20
    },
    "processOrder": 1,
    "status": "Active",
    "stackable": true,
    "range": {
      "start": "Jun 01",
      "end": "Aug 31"
    }
  },
  "reservationCount": 0
}

Replace a reusable rate rule's data. Supply the full rule including matching id/propertyId; use PATCH when only changing a few fields.

Console and native room rate-rule editors. Edits on the room editor remain staged until room save; mapped rooms require channel review first.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

idstringRequired

Existing rule ID.

propertyIdstringRequired

Must match x-property-id.

labelstringRequired

Rate rule display label.

typestringRequired

Rule kind; cannot be changed after creation.

Allowed valuesSeasonalLengthOfStayFrequentGuestHolidayWeekendDiscount
appliesTostringRequired

Which nights the rule affects.

Allowed valuesWeekdaysWeekendsBoth
adjustmentobjectRequired

Price adjustment with type and value.

adjustment.typestringRequired

Whether the adjustment is a currency amount or percentage.

Allowed valuesFixedAmountPercentage
adjustment.valuenumberRequired

Signed adjustment; negative values reduce price. FixedAmount uses major currency units.

processOrderintegerRequired

Positive rule application order; zero is rejected by the current service.

statusstringOptional

Active rules participate in pricing.

Allowed valuesActiveInactive
stackablebooleanOptional

Whether this rule can be combined with other eligible rules.

discountApplicationstringOptional

For Discount rules: per-night versus once per stay.

Allowed valuesPerNightPerStay
rangeobject | nullOptional

Seasonal dates require a real month and day: {start:"Jun 01", end:"Aug 31"}. Full English month names and case/whitespace variants are accepted and normalized to MMM DD; month-only, arbitrary strings, and impossible dates return 400. Year-crossing ranges and Feb 29 are supported.

minimumNightsintegerOptional

LengthOfStay minimum stay length.

maximumNightsintegerOptional

Optional LengthOfStay maximum stay length.

daysInAdvanceintegerOptional

Minimum advance booking period.

requiredFrequencyintegerOptional

FrequentGuest required past-stay count.

termInDaysintegerOptional

FrequentGuest lookback period.

holidays(string | {name:string,date:string})[]Optional

HolidayWeekend named holidays; legacy objects use name to resolve dates annually. The date property does not override the named holiday calculation.

Allowed valuesNewYearsDayValentinesDayMemorialDayIndependenceDayLaborDayThanksgivingChristmas

Behavior & constraints

  • Requires rates.manage. The rule type is immutable and adjustment.value must be non-zero.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/price-rules/rule_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"id":"rule_123","propertyId":"PROPERTY_ID","label":"Summer season","type":"Seasonal","appliesTo":"Both","adjustment":{"type":"FixedAmount","value":20},"processOrder":1,"status":"Active","stackable":true,"range":{"start":"Jun 01","end":"Aug 31"}}'
Response · 200
JSON
{
  "id": "rule_123",
  "propertyId": "PROPERTY_ID",
  "label": "Summer season",
  "type": "Seasonal",
  "appliesTo": "Both",
  "adjustment": {
    "type": "FixedAmount",
    "value": 20
  },
  "processOrder": 1,
  "status": "Active",
  "stackable": true,
  "range": {
    "start": "Jun 01",
    "end": "Aug 31"
  }
}

Merge changes into a reusable rate rule, or detach it from every room without deleting the rule. unassignAllRooms takes precedence over other fields.

Console activate/deactivate and unassign-all rate actions.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

labelstringOptional

Rate rule display label.

typestringOptional

Rule kind; cannot be changed after creation.

Allowed valuesSeasonalLengthOfStayFrequentGuestHolidayWeekendDiscount
appliesTostringOptional

Which nights the rule affects.

Allowed valuesWeekdaysWeekendsBoth
adjustmentobjectOptional

Price adjustment with type and value.

adjustment.typestringOptional

Whether the adjustment is a currency amount or percentage.

Allowed valuesFixedAmountPercentage
adjustment.valuenumberOptional

Signed adjustment; negative values reduce price. FixedAmount uses major currency units.

processOrderintegerOptional

Positive rule application order; zero is rejected by the current service.

statusstringOptional

Active rules participate in pricing.

Allowed valuesActiveInactive
stackablebooleanOptional

Whether this rule can be combined with other eligible rules.

discountApplicationstringOptional

For Discount rules: per-night versus once per stay.

Allowed valuesPerNightPerStay
rangeobject | nullOptional

Seasonal dates require a real month and day: {start:"Jun 01", end:"Aug 31"}. Full English month names and case/whitespace variants are accepted and normalized to MMM DD; month-only, arbitrary strings, and impossible dates return 400. Year-crossing ranges and Feb 29 are supported.

minimumNightsintegerOptional

LengthOfStay minimum stay length.

maximumNightsintegerOptional

Optional LengthOfStay maximum stay length.

daysInAdvanceintegerOptional

Minimum advance booking period.

requiredFrequencyintegerOptional

FrequentGuest required past-stay count.

termInDaysintegerOptional

FrequentGuest lookback period.

holidays(string | {name:string,date:string})[]Optional

HolidayWeekend named holidays; legacy objects use name to resolve dates annually. The date property does not override the named holiday calculation.

Allowed valuesNewYearsDayValentinesDayMemorialDayIndependenceDayLaborDayThanksgivingChristmas
unassignAllRoomsbooleanOptional

true removes room assignments and returns {unassignedCount} instead of a rule.

Behavior & constraints

  • Requires rates.manage. Rule type cannot change.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/price-rules/rule_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"status":"Inactive"}'
Response · 200
JSON
{
  "id": "rule_123",
  "propertyId": "PROPERTY_ID",
  "label": "Summer season",
  "type": "Seasonal",
  "appliesTo": "Both",
  "adjustment": {
    "type": "FixedAmount",
    "value": 20
  },
  "processOrder": 1,
  "status": "Inactive",
  "stackable": true,
  "range": {
    "start": "Jun 01",
    "end": "Aug 31"
  }
}

Delete a reusable price rule and clean up its room-pricing assignments. Returns 409 if existing reservations reference the rule; deactivate it instead to preserve their invoices.

Console rate-rule deletion.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires rates.manage.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/price-rules/rule_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 204
HTTP
(empty response body)

List property discount codes and their applied reservation ledger entries for management and redemption tracking.

Console discount-code catalog and invitation dialog; native iOS discounts.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires rates.manage. Canceled discount ledger entries are excluded from appliedReservations.
Request
cURL
curl 'https://api.wikiup.app/api/discount-codes' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
[
  {
    "id": "discount_123",
    "propertyId": "PROPERTY_ID",
    "code": "WELCOME10",
    "name": "Welcome offer",
    "active": true,
    "discountType": "percent",
    "discountValue": 10,
    "redemptionCount": 0,
    "appliesTo": "lodgingSubtotalOnly",
    "combinable": false,
    "appliedReservations": []
  }
]

Create a lodging-subtotal discount with optional stay, room, date and redemption restrictions. Discount codes do not discount add-ons; the server forces appliesTo to lodgingSubtotalOnly.

Console discount editor and native discount creation.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

codestringRequired

Unique code; trimmed and converted to uppercase.

namestringOptional

Internal display name; defaults to code.

activebooleanOptional

Whether the code can be redeemed; defaults true.

discountTypestringOptional

Percentage or fixed currency reduction; defaults percent on creation.

Allowed valuespercentfixedAmount
discountValuenumberRequired

Positive reduction; percent cannot exceed 100, fixedAmount uses major currency units.

minNightsinteger | nullOptional

Minimum stay length.

startsAtstring | nullOptional

Earliest redemption timestamp.

validUntilstring | nullOptional

Last redemption timestamp.

minSubtotalnumber | nullOptional

Minimum lodging subtotal in major currency units.

maxRedemptionsinteger | nullOptional

Total redemption limit.

maxRedemptionsPerGuestinteger | nullOptional

Per-guest redemption limit.

validCheckInFromstring | nullOptional

Earliest arrival date YYYY-MM-DD.

validCheckInUntilstring | nullOptional

Latest arrival date YYYY-MM-DD.

validCheckOutUntilstring | nullOptional

Latest departure date YYYY-MM-DD.

allowedRoomIdsstring[]Optional

Limit to these rooms; empty allows any room.

excludedPriceRuleIdsstring[]Optional

Room price rules removed when applying this code.

blackoutDatesstring[]Optional

Ineligible stay dates YYYY-MM-DD.

weekdaysOnlybooleanOptional

Disallow the property's configured weekend nights.

combinablebooleanOptional

Whether the discount permits combining with an existing discount.

internalNotestring | nullOptional

Staff-only note.

Response fields

appliesTostringOptional

Server-enforced scope; excludes extras and taxes.

Allowed valueslodgingSubtotalOnly

Behavior & constraints

  • Requires rates.manage. Codes are uppercase and property-unique; duplicate codes return 409.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/discount-codes' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"code":"WELCOME10","name":"Welcome offer","discountType":"percent","discountValue":10,"minNights":2}'
Response · 201
JSON
{
  "id": "discount_123",
  "propertyId": "PROPERTY_ID",
  "code": "WELCOME10",
  "name": "Welcome offer",
  "active": true,
  "discountType": "percent",
  "discountValue": 10,
  "redemptionCount": 0,
  "appliesTo": "lodgingSubtotalOnly",
  "combinable": false
}

Update a property's discount-code configuration. The server preserves identity and redemption count, normalizes the code and rejects duplicate codes.

Console and native discount-code edit/toggle actions.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

codestringOptional

Unique code; trimmed and converted to uppercase.

namestringOptional

Internal display name; defaults to code.

activebooleanOptional

Whether the code can be redeemed; defaults true.

discountTypestringOptional

Percentage or fixed currency reduction; defaults percent on creation.

Allowed valuespercentfixedAmount
discountValuenumberOptional

Positive reduction; percent cannot exceed 100, fixedAmount uses major currency units.

minNightsinteger | nullOptional

Minimum stay length.

startsAtstring | nullOptional

Earliest redemption timestamp.

validUntilstring | nullOptional

Last redemption timestamp.

minSubtotalnumber | nullOptional

Minimum lodging subtotal in major currency units.

maxRedemptionsinteger | nullOptional

Total redemption limit.

maxRedemptionsPerGuestinteger | nullOptional

Per-guest redemption limit.

validCheckInFromstring | nullOptional

Earliest arrival date YYYY-MM-DD.

validCheckInUntilstring | nullOptional

Latest arrival date YYYY-MM-DD.

validCheckOutUntilstring | nullOptional

Latest departure date YYYY-MM-DD.

allowedRoomIdsstring[]Optional

Limit to these rooms; empty allows any room.

excludedPriceRuleIdsstring[]Optional

Room price rules removed when applying this code.

blackoutDatesstring[]Optional

Ineligible stay dates YYYY-MM-DD.

weekdaysOnlybooleanOptional

Disallow the property's configured weekend nights.

combinablebooleanOptional

Whether the discount permits combining with an existing discount.

internalNotestring | nullOptional

Staff-only note.

Response fields

appliesTostringOptional

Server-enforced scope; excludes extras and taxes.

Allowed valueslodgingSubtotalOnly

Behavior & constraints

  • Requires rates.manage. Supply valid discount bounds when editing: percentage 0–100 (exclusive of 0), fixed amount greater than zero.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/discount-codes/discount_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"active":false}'
Response · 200
JSON
{
  "id": "discount_123",
  "propertyId": "PROPERTY_ID",
  "code": "WELCOME10",
  "name": "Welcome offer",
  "active": false,
  "discountType": "percent",
  "discountValue": 10,
  "redemptionCount": 0,
  "appliesTo": "lodgingSubtotalOnly",
  "combinable": false
}

Delete an unused discount code. Codes with applied redemptions cannot be deleted; deactivate them instead to preserve accounting history.

Console and native discount-code deletion.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires rates.manage. Returns 409 when non-canceled discount ledger entries or legacy redemption counts show the code has been used.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/discount-codes/discount_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "message": "Discount code deleted."
}

Calculate discounted stay estimates for a selected room or all eligible available rooms without creating a reservation or consuming the code. Accepts either an existing code or an unsaved draft, enabling invitation previews.

Console DiscountLinkDialog and native discount invitation pricing.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

checkInstringRequired

Arrival date YYYY-MM-DD.

checkOutstringRequired

Departure date YYYY-MM-DD.

guestsintegerRequired

Positive guest count.

roomIdstringOptional

Optional selected room; without it only available eligible rooms are returned.

codestringOptional

Existing code; provide exactly one of code and draft.

draftobjectOptional

Unsaved DiscountCode fields; provide exactly one of code and draft.

excludedPriceRuleIdsstring[]Optional

Override code price-rule exclusions for the estimate.

linkOnlybooleanOptional

Preview a one-use invitation with an existing code.

Behavior & constraints

  • Requires rates.manage. All prices are major currency units and describe lodging; this is not the full checkout invoice. Returns 409 when no rooms qualify or are available.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/discount-codes/estimate' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"code":"WELCOME10","checkIn":"2027-06-10","checkOut":"2027-06-12","guests":2}'
Response · 200
JSON
{
  "roomId": "room_123",
  "roomName": "Garden room",
  "available": true,
  "nights": 2,
  "regularTotal": 300,
  "priceRuleAdjustment": 0,
  "subtotal": 300,
  "discountAmount": 30,
  "total": 270,
  "roomEstimates": [
    {
      "roomId": "room_123",
      "roomName": "Garden room",
      "available": true,
      "nights": 2,
      "regularTotal": 300,
      "priceRuleAdjustment": 0,
      "subtotal": 300,
      "discountAmount": 30,
      "total": 270
    }
  ],
  "excludedPriceRuleIds": []
}

Create a booking invitation URL prefilled with a discount, dates and guest count, optionally for one room. Providing recipientEmail sends the branded invitation immediately; without it only a shareable link is returned.

Console and native iOS discount invitation dialogs.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

codestringRequired

Active discount code.

checkInstringRequired

Arrival YYYY-MM-DD.

checkOutstringRequired

Departure YYYY-MM-DD.

guestsintegerRequired

Positive guest count.

roomIdstringOptional

Optional Active room allowed by this code.

recipientEmailstringOptional

If supplied, send the invitation to this address.

personalMessagestringOptional

Optional non-empty message, maximum 2,000 characters.

excludedPriceRuleIdsstring[]Optional

Custom exclusions; if different from the original code, a separate single-use invitation code is created.

Behavior & constraints

  • Requires rates.manage. The URL does not reserve availability or consume a redemption. Repeated requests with changed exclusions can create additional one-use codes.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/discount-codes/link' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"code":"WELCOME10","checkIn":"2027-06-10","checkOut":"2027-06-12","guests":2}'
Response · 200
JSON
{
  "url": "https://www.example-inn.com/book-a-room?discountCode=WELCOME10",
  "code": "WELCOME10",
  "emailed": false,
  "defaultMessage": "We would love to welcome you."
}

API Reference

Reports

Read the property's normalized payment ledger for transaction reporting. Despite the route name, entries can include Stripe, gift-card, manual and imported payments, refunds and discount adjustments.

Console Reports transaction table.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

fromstringOptional

Report start date YYYY-MM-DD, interpreted in the property time zone.

tostringOptional

Report end date YYYY-MM-DD; converted to an exclusive end boundary.

qstringOptional

Search transaction descriptions, customers and references.

pagestringOptional

Opaque page token from pageInfo.nextPageToken.

limitintegerOptional

Page size, default 20.

stripeModestringOptional

Optional Stripe environment filter.

Allowed valuestestlive

Response fields

transactions[].kindstringOptional

Ledger direction.

Allowed valuespaymentrefund
transactions[].statusstringOptional

Normalized ledger status.

Allowed valuessucceededpendingfailedcanceled
transactions[].amountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

transactions[].refundableAmountnumberOptional

Remaining refundable amount in major currency units.

Behavior & constraints

  • Requires financials.view. This reads the local normalized ledger, not a live Stripe-only list.
Request
cURL
curl 'https://api.wikiup.app/api/reports/stripe-transactions?from=2027-06-01&to=2027-06-30&limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "transactions": [],
  "pageInfo": {
    "limit": 20,
    "pageToken": null,
    "nextPageToken": null,
    "hasNextPage": false,
    "totalCount": 0,
    "usedFallback": false
  },
  "range": {
    "from": "2027-06-01T07:00:00.000Z",
    "to": "2027-07-01T07:00:00.000Z",
    "fromDateOnly": "2027-06-01",
    "toDateOnly": "2027-06-30",
    "timezone": "America/Los_Angeles"
  }
}

Aggregate ledger activity into time buckets with payment/refund counts, gross collected, refunded and net totals for reporting charts.

Console Reports transaction activity chart.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

fromstringOptional

Report start date.

tostringOptional

Report end date.

bucketUnitstringOptional

Aggregation interval; defaults hour.

Allowed valuessecondminutehourdayweekmonthyear
stripeModestringOptional

Optional Stripe environment filter.

Allowed valuestestlive

Behavior & constraints

  • Requires financials.view. Totals use major currency units; bucket boundaries use the property time zone.
Request
cURL
curl 'https://api.wikiup.app/api/reports/transaction-histogram?from=2027-06-01&to=2027-06-30&bucketUnit=day' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "range": {
    "from": "2027-06-01T07:00:00.000Z",
    "to": "2027-07-01T07:00:00.000Z",
    "timezone": "America/Los_Angeles",
    "bucketUnit": "day",
    "bucketCount": 30
  },
  "summary": {
    "transactionCount": 0,
    "refundCount": 0,
    "transactionTotal": 0,
    "refundTotal": 0,
    "netTotal": 0,
    "averageTransactionCountPerBucket": 0,
    "averageTransactionTotalPerBucket": 0,
    "averageNetTotalPerBucket": 0
  },
  "buckets": []
}

Issue a Stripe refund for a property-owned PaymentIntent and reconcile it to the reservation ledger when a reservation and guest can be linked. Requires property owner access.

Console Reports refund dialog.

Path parameters

paymentIntentIdstringRequired

Stripe PaymentIntent ID, beginning pi_.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

amountnumber | stringOptional

Positive major-currency amount; omit to refund the remaining refundable amount.

reasonstringOptional

Optional processor refund reason.

Allowed valuesduplicatefraudulentrequested_by_customer
stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Response fields

ledgerRecordedbooleanOptional

false means the processor refund exists but could not immediately be linked to a reservation ledger row.

Behavior & constraints

  • Owner-only. Rejects amounts above the refundable balance and payments belonging to another property. Console refund metadata and ledger descriptions identify console.wikiup.app; the original payment description is preserved.
  • This endpoint issues a new refund on each successful request; an uncertain network response requires checking the transaction before retrying. It does not cancel the reservation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reports/stripe-transactions/pi_example/refunds' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"amount":25,"reason":"requested_by_customer"}'
Response · 201
JSON
{
  "refund": {
    "id": "re_example",
    "amount": 25,
    "created": "2027-06-01T12:00:00.000Z",
    "status": "succeeded"
  },
  "ledgerRecorded": true,
  "stripeMode": "live"
}

Send a property-branded guest confirmation for an existing console Reports refund. Never creates another refund.

Console Reports post-refund confirmation dialog.

Path parameters

paymentIntentIdstringRequired

Stripe PaymentIntent ID, beginning pi_.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Response fields

guestEmailSentbooleanOptional

The mail service accepted the confirmation.

alreadySentbooleanOptional

An earlier accepted send was found; no duplicate was sent.

Behavior & constraints

  • Owner-only. Verifies the PaymentIntent, refund, reservation and guest belong to the selected property, and that the refund belongs to the specified PaymentIntent and was issued through Reports.
  • Amounts, currency, status and recipient come from authoritative processor/reservation records, never the request body. Only pending or succeeded refunds are eligible; pending emails do not claim completion.
  • A durable receipt prevents repeat sends. A sending or uncertain outcome returns 409 and remains fenced for reconciliation; do not issue another refund to retry an email.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reports/stripe-transactions/pi_example/refunds/[refundId]/email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"stripeMode":"test"}'
Response · 200
JSON
{
  "guestEmailSent": true
}

Reconcile historical Stripe activity into the normalized payment ledger and update imported/older entries. This maintenance operation can create and update ledger records without charging or refunding guests.

Reporting reconciliation/maintenance API.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

fromstringOptional

Optional start date for reconciliation.

tostringOptional

Optional end date for reconciliation.

stripeModestringOptional

Optional payment environment preference. Deployment settings can disable overrides; use the environment returned by the server.

Allowed valuestestlive

Behavior & constraints

  • Requires financials.view. Existing processor references are used to deduplicate ledger entries.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reports/transactions/backfill' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"from":"2027-06-01","to":"2027-06-30"}'
Response · 200
JSON
{
  "updatedCount": 4,
  "createdCount": 2,
  "stripeMode": "live",
  "range": {
    "from": "2027-06-01T07:00:00.000Z",
    "toExclusive": "2027-07-01T07:00:00.000Z",
    "timeZone": "America/Los_Angeles"
  }
}

List issued property gift cards and their redemption history, including linked reservation confirmation numbers. Full card numbers are intentionally omitted from this report.

Console gift-card reporting.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Response fields

cards[].statusstringOptional

Gift-card state.

Allowed valuesActiveRedeemedVoidedExpired
cards[].originalAmountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

cards[].balancenumberOptional

Amount in major currency units: 15 means $15.00 for USD.

redemptions[].amountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

Behavior & constraints

  • Requires financials.view.
Request
cURL
curl 'https://api.wikiup.app/api/reports/gift-cards' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "cards": [
    {
      "id": "giftcard_123",
      "cardNumberLastFour": "1234",
      "originalAmount": 100,
      "balance": 80,
      "currency": "usd",
      "status": "Active",
      "createdAt": "2027-06-01T12:00:00.000Z"
    }
  ],
  "redemptions": [
    {
      "id": "redemption_123",
      "giftCardId": "giftcard_123",
      "cardNumberLastFour": "1234",
      "reservationId": "reservation_123",
      "confirmationNumber": "WUR-EXAMPLE",
      "amount": 20,
      "redeemedAt": "2027-06-02T12:00:00.000Z"
    }
  ]
}

API Reference

Reservations

Finalize the physical room for a pooled reservation before room-specific access disclosure.

Behavior & constraints

  • Requires reservations.manage. Body: optional roomId. Readiness is not a room attribute or assignment prerequisite. The legacy confirmReady input is accepted for compatibility and has no effect. The held room is preferred; a replacement must fulfil the booked type for the entire stay. Both room references and assignment confirmation are checked before success. Assignment retries reuse the same finalized room and timestamp; later moves use the explicit room-move workflow. The booked type and commercial price snapshot are preserved.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/<id>/assignment' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "reservation-id",
  "roomId": "physical-room-id",
  "bookedRoomTypeId": "type-id",
  "roomAssignmentConfirmedAt": "2027-01-10T18:00:00Z"
}

Read a reservation's newest changes with actor attribution and cursor pagination.

Path parameters

idstringRequired

Reservation identifier.

Query parameters

beforestringOptional

Opaque nextCursor returned by the previous page; omit for newest changes.

Response fields

entriesArray<object>Required

Page of events; empty if no visible changes remain.

entries[]objectRequired

Reservation audit event.

entries[].idstringRequired

Stable event identifier.

entries[].datestringRequired

Event timestamp; display in the property time zone.

entries[].actorobjectRequired

Attributed actor.

entries[].actor.type"guest" | "staff" | "system"Required

Actor category.

entries[].actor.namestringRequired

Display name at the time of the event.

entries[].changesArray<object>Required

Visible changes after permission redaction.

entries[].changes[]objectRequired

One user-visible change.

entries[].changes[].typestringRequired

Display label for the kind of change; not a fixed enum.

entries[].changes[].descriptionstringRequired

Human-readable before/after description.

entries[].changes[].financialbooleanOptional

True for financial changes; these are omitted without financial visibility permission.

nextCursorstring | nullRequired

Opaque before cursor for the next page; null at the end.

Behavior & constraints

  • Requires reservations.view and a reservation belonging to the current property. Financial changes require financial visibility permission. Responses are private, no-store.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/<reservation-id>/timeline' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "entries": [
    {
      "id": "event_example",
      "date": "2027-02-09T16:00:00-08:00",
      "actor": {
        "type": "staff",
        "name": "Example Staff"
      },
      "changes": [
        {
          "type": "Guest checked in",
          "description": "Upcoming → Checked in"
        }
      ]
    }
  ],
  "nextCursor": null
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

Review restoration of a canceled direct reservation, keeping its confirmation, guest, payment history and original cancellation deadline. Choose the original or a different room, dates, or both. This does not reactivate the booking or reserve inventory.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

startstringRequired

Check-in in property-local YYYY-MM-DD format; cannot be in the past.

endstringRequired

Exclusive check-out, after start, in YYYY-MM-DD format.

roomIdstringRequired

Active destination room in the same property.

waiveFeesbooleanOptional

Optional, false by default. Only an owner can waive the normal rescheduling fee.

Response fields

quoteIdstringOptional

Server-stored review, scoped to this property and reservation; expires after 15 minutes.

eligiblebooleanOptional

Whether the selected stay is currently available and permitted.

alternativeRoomsarrayOptional

Available alternatives for the requested dates, with pricing and rescheduling fee calculations.

feeAmountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

newBalanceDuenumberOptional

Net unpaid amount after applying prior payments and refunds. No card is charged.

refundAmountnumberOptional

Always zero for restoration; previously issued refunds are not reversed.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • Requires reservations.manage. Provider-owned reservations must be changed with their booking provider when local stay changes are unsupported.
  • Booking rules, preparation buffers, guest capacity, blocked-guest policy and room availability are enforced. Fee-waiver permission is checked again at confirmation.
  • cancellationPolicyCheckin is a server-owned earliest check-in anchor. Moving or restoring a stay cannot extend the original refund deadline or restart the original booking grace period. Manual owner cancellation refund overrides remain separate, explicit actions.
  • Financial amounts can be redacted for callers without financial access. A quote is a review, not an inventory hold.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/restore/quote' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"start":"2027-01-15","end":"2027-01-17","roomId":"room_456","waiveFees":false}'
Response · 200
JSON
{
  "quoteId": "quote_restore_123",
  "eligible": true,
  "feeAmount": 100,
  "newBalanceDue": 100,
  "refundAmount": 0,
  "alternativeRooms": []
}

Restore a canceled reservation using a previously reviewed quote. Rechecks status, availability, rules, prices, payment history, policy and fee waiver before changing the reservation to upcoming.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

quoteIdstringRequired

Unexpired eligible review from restore/quote for this exact property and reservation.

Response fields

reservationIdstringOptional

The existing reservation ID; no replacement reservation is created.

statusstringOptional

upcoming

guestEmailNotificationstringOptional

queued or unavailable. Queued means background submission is scheduled, not inbox delivery. Unavailable means no guest email address is on file.

financialsobjectOptional

Reviewed rescheduling fee and balance due. This call does not charge a card or automatically issue a refund.

updatedReservationobjectOptional

Restored roomId and property-local start/end dates.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • Requires reservations.manage. Changed prices/policies/payments, an occupied stay, expired/reused review or an already restored reservation return 409. Cross-property reviews return 404; non-owner fee waiver returns 403.
  • The existing final database-write guard serializes and validates property inventory, including imports, direct bookings and room/date moves. Overlapping stays cannot both commit. Uncertain write outcomes retain the claim for operator recovery; do not blindly replay a confirmation.
  • Past refunds remain in the payment ledger. Any new balance due is collected separately. Canceled history is retained, and the restoration is recorded in the timeline. A guest email identifies the restored reservation as confirmed and includes its room, dates and confirmation number. Submission acceptance/failure is audited; background delivery failure does not undo the reservation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/restore/confirm' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_restore_123"}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "status": "upcoming",
  "guestEmailNotification": "queued",
  "refundIssuedAmount": 0,
  "refundPaymentIds": [],
  "financials": {
    "feeAmount": 100,
    "chargeAmount": 100,
    "currentBalanceDue": 0,
    "newBalanceDue": 100
  },
  "updatedReservation": {
    "start": "2027-01-15",
    "end": "2027-01-17",
    "roomId": "room_456"
  }
}

Load the property's reservation timeline, search guest stays, or switch to unpaid-balance and cancellation-report views. The response shape depends on the requested view.

Staff reservation and guest management API.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

startDatestringOptional

Timeline range start.

endDatestringOptional

Timeline range end.

searchstringOptional

Reservation/guest search text.

includeCanceledstringOptional

Include canceled stays; false by default.

Allowed valuestruefalse
unpaidBalancesstringOptional

true returns {items:[...]} containing unpaid invoice balances; requires invoice.manage.

Allowed valuestrue
cancellationsstringOptional

true returns paginated canceled stays and totals; requires invoice.manage.

Allowed valuestrue
rangestringOptional

Cancellation-report period only.

Allowed valuesweekmonthyear
pageintegerOptional

Cancellation-report page, starting at 1.

pageSizeintegerOptional

Cancellation report: default 25, maximum 100.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • unpaidBalances takes precedence over cancellations when both are true.
Request
cURL
curl 'https://api.wikiup.app/api/reservations?startDate=2027-06-01&endDate=2027-07-01' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
[
  {
    "id": "reservation_123",
    "propertyId": "PROPERTY_ID",
    "roomId": "room_123",
    "title": "Alex Morgan",
    "type": "reservation",
    "status": "upcoming",
    "start": "2027-06-10T07:00:00.000Z",
    "end": "2027-06-12T07:00:00.000Z",
    "confirmationNumber": "WUR-EXAMPLE"
  }
]

List unpaid reservation balances for invoice follow-up. This explicit alias returns the same result as GET /api/reservations?unpaidBalances=true.

Compatibility alias for unpaid-balance screens; current console also uses the collection query flag.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Response fields

itemsArray<object>Required

Reservations with a positive balance.

items[]objectRequired

Unpaid reservation invoice summary; requires invoice access.

items[].reservationIdstringRequired

Reservation identifier.

items[].confirmationNumberstring | nullRequired

Guest confirmation number; null if unavailable.

items[].guestNamestringRequired

Guest display name.

items[].guestEmailstring | nullRequired

Guest email; null if unavailable.

items[].checkInstringRequired

Reservation check-in timestamp.

items[].checkOutstringRequired

Reservation checkout timestamp.

items[].statusstring | nullRequired

Persisted reservation status; null if unset.

items[].roomNamestring | nullRequired

Room display name; null if missing.

items[].balanceDuenumberRequired

Remaining amount due, in currency major units.

items[].totalDuenumberRequired

Invoice total due, in currency major units.

items[].totalPaidnumberRequired

Collected payment total used for the balance calculation, in currency major units.

items[].currencystringRequired

Currency code.

items[].lastPaymentLinkRecipientEmailstring | nullRequired

Most recent payment-link recipient; null if none.

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/unpaid-balances' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "items": [
    {
      "reservationId": "reservation_example",
      "confirmationNumber": "EXAMPLE-ONLY",
      "guestName": "Example Guest",
      "guestEmail": "guest@example.com",
      "checkIn": "2027-02-09T00:00:00-08:00",
      "checkOut": "2027-02-12T00:00:00-08:00",
      "status": "upcoming",
      "roomName": "Garden King",
      "balanceDue": 300,
      "totalDue": 600,
      "totalPaid": 300,
      "currency": "USD",
      "lastPaymentLinkRecipientEmail": null
    }
  ]
}
Response JSON schema

Synthetic example with no real guest information. Nested required fields apply when their containing object is present. Timestamps should be displayed in the property time zone.

Create an innkeeper reservation or blockout after checking room ownership and overlap. Guest stays receive a confirmation number, pricing snapshot, booking emails and staff push notifications; this call does not collect a card payment.

Staff reservation and guest management API.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

reservationobjectRequired

Required wrapper around reservation fields.

reservation.roomIdstringOptional

Specific physical room; mutually exclusive with roomTypeId.

reservation.startstringRequired

Check-in date/time. Send a property-local midnight represented as an ISO timestamp.

reservation.endstringRequired

Exclusive check-out date/time, later than start.

reservation.titlestringRequired

Display name on the reservation timeline.

reservation.typestringRequired

A guest stay or a room blockout.

Allowed valuesreservationblockout
reservation.statusstringOptional

Reservation status; use PATCH on the reservation to transition an existing stay.

Allowed valuesupcomingcheckedincheckedoutcanceled
reservation.guestIdstring | nullOptional

Existing guest ID, or supply details.guest for guest creation/update.

reservation.detailsobjectOptional

Guest counts, arrival preferences, invoice snapshot, and selected extras.

reservation.details.guestobjectOptional

Guest profile with id (existing guest) or firstName, lastName, email, phone.

reservation.details.adultsCountintegerOptional

Count for this stay.

reservation.details.childrenCountintegerOptional

Count for this stay.

reservation.details.petsCountintegerOptional

Count for this stay.

reservation.details.cotsCountintegerOptional

Count for this stay.

reservation.details.earlyCheckInbooleanOptional

Innkeeper-approved arrival/departure preference. Can be enabled even when the property does not charge this fee.

reservation.details.lateCheckOutbooleanOptional

Innkeeper-approved arrival/departure preference. Can be enabled even when the property does not charge this fee.

reservation.details.earlyCheckInWaivedbooleanOptional

Waive this fee while retaining the corresponding zero-cost invoice line. Independent of ordinary discounts.

reservation.details.lateCheckOutWaivedbooleanOptional

Waive this fee while retaining the corresponding zero-cost invoice line. Independent of ordinary discounts.

reservation.details.selfCheckinbooleanOptional

Guest will use self check-in.

reservation.details.etastring | nullOptional

Expected arrival in HH:mm property-local wall time.

reservation.details.estimatedCheckoutstring | nullOptional

Expected departure in HH:mm property-local wall time.

reservation.details.notesstring | nullOptional

Reservation notes.

reservation.details.addOnsobject[]Optional

Selected invoice snapshots with id, label, amount and qty; amounts use major currency units.

reservation.details.pricingobjectOptional

Reservation pricing snapshot: basePrice, weekendBasePrice, weekendDays, priceRules and priceBreakdown.

reservation.details.devicestringOptional

Booking origin; defaults to browser_console for staff-created reservations.

Allowed valuesbrowser_desktopbrowser_ipadbrowser_mobilebrowser_console
reservation.roomTypeIdstringOptional

Book a pooled classification instead of a specific roomId. The server holds one eligible physical room for the entire stay. Pooled sales must be enabled.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • A conflict returns 409. Canceled reservations do not block availability. Past stays do not receive a guest booking confirmation.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"reservation":{"roomId":"room_123","start":"2027-06-10T07:00:00.000Z","end":"2027-06-12T07:00:00.000Z","title":"Alex Morgan","type":"reservation","details":{"guest":{"firstName":"Alex","lastName":"Morgan","email":"alex@example.com","phone":"+15555550123"},"adultsCount":2}}}'
Response · 201
JSON
{
  "id": "reservation_123",
  "propertyId": "PROPERTY_ID",
  "roomId": "room_123",
  "title": "Alex Morgan",
  "type": "reservation",
  "status": "upcoming",
  "start": "2027-06-10T07:00:00.000Z",
  "end": "2027-06-12T07:00:00.000Z",
  "confirmationNumber": "WUR-EXAMPLE"
}

Retrieve one reservation with optional related objects for the reservation dialog, guest history or invoice. Legacy missing defaults may be repaired during this read.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

embedstringOptional

Comma-separated relations; checkinGuideProgress is case-insensitive.

Allowed valuesdetailsguestroompaymentscheckinGuideProgress

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123?embed=details,guest,room,payments,checkinGuideProgress' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "id": "reservation_123",
  "propertyId": "PROPERTY_ID",
  "roomId": "room_123",
  "title": "Alex Morgan",
  "type": "reservation",
  "status": "upcoming",
  "start": "2027-06-10T07:00:00.000Z",
  "end": "2027-06-12T07:00:00.000Z",
  "confirmationNumber": "WUR-EXAMPLE",
  "details": {
    "adultsCount": 2,
    "eta": "16:00",
    "payments": []
  }
}

Save reservation edits and nested guest, arrival/departure, add-on and pricing details. The body is the reservation itself, without the creation endpoint's reservation wrapper. Use the specialized quote/confirm routes when changing dates or rooms with settlement.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

roomIdstringRequired

Room in the selected property.

startstringRequired

Check-in date/time. Send a property-local midnight represented as an ISO timestamp.

endstringRequired

Exclusive check-out date/time, later than start.

titlestringRequired

Display name on the reservation timeline.

typestringRequired

A guest stay or a room blockout.

Allowed valuesreservationblockout
statusstringOptional

Reservation status; use PATCH on the reservation to transition an existing stay.

Allowed valuesupcomingcheckedincheckedoutcanceled
guestIdstring | nullOptional

Existing guest ID, or supply details.guest for guest creation/update.

detailsobjectOptional

Guest counts, arrival preferences, invoice snapshot, and selected extras.

details.guestobjectOptional

Guest profile with id (existing guest) or firstName, lastName, email, phone.

details.adultsCountintegerOptional

Count for this stay.

details.childrenCountintegerOptional

Count for this stay.

details.petsCountintegerOptional

Count for this stay.

details.cotsCountintegerOptional

Count for this stay.

details.earlyCheckInbooleanOptional

Innkeeper-approved arrival/departure preference. Can be enabled even when the property does not charge this fee.

details.lateCheckOutbooleanOptional

Innkeeper-approved arrival/departure preference. Can be enabled even when the property does not charge this fee.

details.earlyCheckInWaivedbooleanOptional

Waive this fee while retaining the corresponding zero-cost invoice line. Independent of ordinary discounts.

details.lateCheckOutWaivedbooleanOptional

Waive this fee while retaining the corresponding zero-cost invoice line. Independent of ordinary discounts.

details.selfCheckinbooleanOptional

Guest will use self check-in.

details.etastring | nullOptional

Expected arrival in HH:mm property-local wall time.

details.estimatedCheckoutstring | nullOptional

Expected departure in HH:mm property-local wall time.

details.notesstring | nullOptional

Reservation notes.

details.addOnsobject[]Optional

Selected invoice snapshots with id, label, amount and qty; amounts use major currency units.

details.pricingobjectOptional

Reservation pricing snapshot: basePrice, weekendBasePrice, weekendDays, priceRules and priceBreakdown.

details.devicestringOptional

Booking origin; defaults to browser_console for staff-created reservations.

Allowed valuesbrowser_desktopbrowser_ipadbrowser_mobilebrowser_console
paymentReconciliationobjectOptional

Optional settlement instruction for a resulting credit; owner access is required for manual reconciliation.

paymentReconciliation.reasonstringOptional

Credit reconciliation reason.

Allowed valuesreservation_credit
paymentReconciliation.autoRefundAmountnumberOptional

Requested automatic refund in major currency units, when applicable.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • Status changes through PUT are rejected with 409; use PATCH. Waived arrival/departure fees stay visible as zero-cost invoice lines.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/reservations/reservation_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"id":"reservation_123","propertyId":"PROPERTY_ID","roomId":"room_123","title":"Alex Morgan","type":"reservation","status":"upcoming","start":"2027-06-10T07:00:00.000Z","end":"2027-06-12T07:00:00.000Z","confirmationNumber":"WUR-EXAMPLE","details":{"earlyCheckIn":true,"earlyCheckInWaived":true,"eta":"13:00"}}'
Response · 200
JSON
{
  "id": "reservation_123",
  "propertyId": "PROPERTY_ID",
  "roomId": "room_123",
  "title": "Alex Morgan",
  "type": "reservation",
  "status": "upcoming",
  "start": "2027-06-10T07:00:00.000Z",
  "end": "2027-06-12T07:00:00.000Z",
  "confirmationNumber": "WUR-EXAMPLE",
  "details": {
    "earlyCheckIn": true,
    "earlyCheckInWaived": true,
    "eta": "13:00"
  }
}

Transition a stay from upcoming to checkedin, then from checkedin to checkedout. Under strict early-arrival enforcement, an arrival more than one hour before standard check-in requires an explicit fee confirmation before the status changes.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

statusstringRequired

Target status. Repeating the current status is a no-op; backward transitions are rejected.

Allowed valuesupcomingcheckedincheckedout
acceptEarlyCheckInChargebooleanOptional

Set true only after the innkeeper accepts the early check-in confirmation.

acceptedEarlyCheckInPricenumberOptional

Must equal the confirmationAmount returned by the 409 response; major currency units.

Response fields

codestringOptional

409 machine-readable confirmation condition.

Allowed valuesEARLY_CHECK_IN_CONFIRMATION_REQUIRED
confirmationAmountnumberOptional

Current early check-in fee requiring acceptance.

Behavior & constraints

  • The accepted fee is added to the invoice; this status transition is not a card-charge endpoint.
  • Late check-out is never auto-applied by this transition. Use reservation details to select it.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/reservations/reservation_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"status":"checkedin","acceptEarlyCheckInCharge":true,"acceptedEarlyCheckInPrice":15}'
Response · 200
JSON
{
  "message": "Reservation status updated to \"checkedin\".",
  "reservation": {
    "id": "reservation_123",
    "propertyId": "PROPERTY_ID",
    "roomId": "room_123",
    "title": "Alex Morgan",
    "type": "reservation",
    "status": "checkedin",
    "start": "2027-06-10T07:00:00.000Z",
    "end": "2027-06-12T07:00:00.000Z",
    "confirmationNumber": "WUR-EXAMPLE"
  }
}

Permanently remove a blockout, or mark an upcoming reservation canceled and release its availability. This route does not calculate cancellation fees or issue refunds; use cancel/quote followed by cancel/confirm for a paid cancellation.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Checked-in/checked-out stays cannot be canceled with this route. Releasing availability can trigger waitlist delivery and cancellation push notifications.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/reservations/reservation_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "message": "Reservation reservation_123 status updated to \"canceled\".",
  "reservation": {
    "id": "reservation_123",
    "propertyId": "PROPERTY_ID",
    "roomId": "room_123",
    "title": "Alex Morgan",
    "type": "reservation",
    "status": "canceled",
    "start": "2027-06-10T07:00:00.000Z",
    "end": "2027-06-12T07:00:00.000Z",
    "confirmationNumber": "WUR-EXAMPLE"
  }
}

Move a reservation or blockout to new dates after checking overlap. This direct timeline operation updates the stay dates and sends staff push notifications; it does not run the fee/refund settlement workflow.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

startstringRequired

Check-in date, YYYY-MM-DD.

endstringRequired

Check-out date, YYYY-MM-DD; must follow start.

Behavior & constraints

  • Use modify/eligibility and modify/confirm when policy fees or refund/payment adjustments need to be evaluated.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/change-dates' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"start":"2027-06-11","end":"2027-06-13"}'
Response · 200
JSON
{
  "id": "reservation_123",
  "propertyId": "PROPERTY_ID",
  "roomId": "room_123",
  "title": "Alex Morgan",
  "type": "reservation",
  "status": "upcoming",
  "start": "2027-06-11T07:00:00.000Z",
  "end": "2027-06-13T07:00:00.000Z",
  "confirmationNumber": "WUR-EXAMPLE"
}

Preview a staff room change, including optional date changes, with availability, price difference and the settlement choices available for that direction. Nothing is changed by the quote.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

roomIdstringRequired

Destination room.

startstringOptional

Check-in date, YYYY-MM-DD.

endstringOptional

Check-out date, YYYY-MM-DD; must follow start.

Response fields

directionstringOptional

Price comparison with the existing stay.

Allowed valuessameincreasedecrease
requiredActionstring[]Optional

Allowed costAction values for confirmation.

Allowed valuesproceedwaive_creditcollectrefundkeep

Behavior & constraints

  • All totals are major currency units. Confirm by repeating the selection to change-room or change-room-and-dates; this preview does not create a quoteId.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/change-room/quote' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"roomId":"room_456"}'
Response · 200
JSON
{
  "allowed": true,
  "denialReason": null,
  "roomId": "room_456",
  "roomName": "Mountain room",
  "start": "2027-06-10",
  "end": "2027-06-12",
  "currentStayTotal": 300,
  "newStayTotal": 340,
  "difference": 40,
  "direction": "increase",
  "currentBalanceDue": 0,
  "newBalanceDue": 40,
  "refundableAmount": 0,
  "requiredAction": [
    "waive_credit",
    "collect"
  ]
}

Apply a staff room change and its chosen cost treatment, update the pricing snapshot and release the former room. Increased prices can be left due or waived with a credit; decreased prices can be refunded or retained.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

roomIdstringRequired

Destination room.

startstringOptional

Check-in date, YYYY-MM-DD.

endstringOptional

Check-out date, YYYY-MM-DD; must follow start.

costActionstringOptional

Must match requiredAction from change-room/quote. collect leaves the difference on the balance; waive_credit offsets it; refund returns eligible paid funds; keep retains payment; proceed applies to no difference.

Allowed valuesproceedwaive_creditcollectrefundkeep

Behavior & constraints

  • Availability and pricing are re-evaluated at confirmation. Invalid settlement choices return 422. This call does not automatically charge a stored card for collect.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/change-room' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"roomId":"room_456","costAction":"collect"}'
Response · 200
JSON
{
  "id": "reservation_123",
  "propertyId": "PROPERTY_ID",
  "roomId": "room_456",
  "title": "Alex Morgan",
  "type": "reservation",
  "status": "upcoming",
  "start": "2027-06-10T07:00:00.000Z",
  "end": "2027-06-12T07:00:00.000Z",
  "confirmationNumber": "WUR-EXAMPLE"
}

Apply a staff room change and its chosen cost treatment, update the pricing snapshot and release the former room. Increased prices can be left due or waived with a credit; decreased prices can be refunded or retained.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

roomIdstringRequired

Destination room.

startstringRequired

Check-in date, YYYY-MM-DD.

endstringRequired

Check-out date, YYYY-MM-DD; must follow start.

costActionstringOptional

Must match requiredAction from change-room/quote. collect leaves the difference on the balance; waive_credit offsets it; refund returns eligible paid funds; keep retains payment; proceed applies to no difference.

Allowed valuesproceedwaive_creditcollectrefundkeep

Behavior & constraints

  • Availability and pricing are re-evaluated at confirmation. Invalid settlement choices return 422. This call does not automatically charge a stored card for collect.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/change-room-and-dates' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"roomId":"room_456","start":"2027-06-11","end":"2027-06-13","costAction":"collect"}'
Response · 200
JSON
{
  "id": "reservation_123",
  "propertyId": "PROPERTY_ID",
  "roomId": "room_456",
  "title": "Alex Morgan",
  "type": "reservation",
  "status": "upcoming",
  "start": "2027-06-10T07:00:00.000Z",
  "end": "2027-06-12T07:00:00.000Z",
  "confirmationNumber": "WUR-EXAMPLE"
}

Evaluate proposed dates and room against the property's rescheduling policy, availability and current payments before the innkeeper commits a change.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

startstringRequired

Check-in date, YYYY-MM-DD.

endstringRequired

Check-out date, YYYY-MM-DD; must follow start.

roomIdstringOptional

Destination room; omit to keep the current room.

waiveFeesstringOptional

Owner-only waiver of modification fees.

Allowed valuestrue1yeson

Response fields

rescheduleTypestringOptional

Whether lower-priced changes generate a full, partial or no refund.

Allowed valuesfullpartialnone

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • This is a preview, not a reservation hold. Monetary amounts use major currency units.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123/modify/eligibility?start=2027-06-11&end=2027-06-13&roomId=room_123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "eligible": true,
  "messages": [],
  "beforeCutoff": true,
  "withinGracePeriod": false,
  "appliedRule": "anyTime",
  "denialReason": null,
  "refundAmount": 0,
  "feeAmount": 0,
  "chargeAmount": 0,
  "currentBalanceDue": 0,
  "newBalanceDue": 0,
  "roomAvailable": true,
  "roomId": "room_123",
  "rescheduleType": "full",
  "alternativeRooms": []
}

Commit an innkeeper reschedule after recomputing policy and availability. Applies the new dates/room, records fees, issues eligible refunds and updates the remaining invoice balance.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

startstringRequired

Check-in date, YYYY-MM-DD.

endstringRequired

Check-out date, YYYY-MM-DD; must follow start.

roomIdstringRequired

Destination room, including the current room when changing dates only.

waiveFeesbooleanOptional

Owner-only modification-fee waiver.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • This staff flow uses the proposed selection directly, not a guest quoteId. Amounts are major currency units.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/modify/confirm' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"start":"2027-06-11","end":"2027-06-13","roomId":"room_123","waiveFees":false}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "status": "upcoming",
  "refundIssuedAmount": 0,
  "financials": {
    "feeAmount": 0,
    "chargeAmount": 0,
    "currentBalanceDue": 0,
    "newBalanceDue": 0
  }
}

Preview or complete an early departure from a checked-in stay. Calculates the shortened stay and an optional innkeeper-specified refund before releasing unused nights.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

endstring | nullOptional

New check-out date YYYY-MM-DD; omit to use the service's current-day default.

previewbooleanOptional

true returns the calculation without changing the stay; false/omitted completes it.

refundAmountnumber | string | nullOptional

Optional refund in major currency units, default 0.

Behavior & constraints

  • Completion returns the saved reservation and sends staff modification notifications. This is ending a stay early, not purchasing late check-out.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/early-checkout' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"end":"2027-06-11","preview":true,"refundAmount":50}'
Response · 200
JSON
{
  "start": "2027-06-10",
  "currentEnd": "2027-06-12",
  "newEnd": "2027-06-11",
  "originalNights": 2,
  "newNights": 1,
  "removedNights": 1,
  "checkoutAt": "2027-06-11T07:00:00.000Z",
  "maxRefundableAmount": 300,
  "refundAmount": 50
}

With preview:true, an early-check-out calculation; otherwise the saved reservation.

Explain whether an upcoming reservation can be canceled and evaluate the property's grace period, cutoff, fee and refundable amounts.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • Amounts are major currency units. Use cancel/quote to obtain a confirmation token before settling a paid cancellation.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123/cancel/eligibility' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "eligible": true,
  "messages": [],
  "beforeCutoff": true,
  "withinGracePeriod": false,
  "appliedRule": "feeBased",
  "denialReason": null,
  "refundAmount": 200,
  "feeAmount": 100
}

Create a staff cancellation quote with the policy fee and separate lodging/add-on refund amounts. The quote binds a financial decision to the current reservation before money is returned.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

reasonstring | nullOptional

Cancellation reason retained in the audit trail.

waiveFeesbooleanOptional

Owner-only cancellation-fee waiver.

refundOverrideAmountnumber | string | nullOptional

Owner-only manual refund override, in major currency units.

Response fields

quoteIdstring | nullOptional

Pass to cancel/confirm if the quote is allowed.

expiresAtstringOptional

Quote expiry timestamp; request a fresh quote after expiry or price changes.

Behavior & constraints

  • Requires reservations.view for GET or reservations.manage for mutations; financial fields can be redacted when financial access is unavailable.
  • Amounts in this staff quote are major currency units. Guests use a different cancellation quote route whose amounts are cents.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/cancel/quote' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Travel plans changed","waiveFees":false}'
Response · 200
JSON
{
  "quoteId": "quote_123",
  "allowed": true,
  "expiresAt": "2027-06-01T12:10:00.000Z",
  "financials": {
    "feeAmount": 100,
    "stayRefundAmount": 200,
    "addOnRefundAmount": 15,
    "refundAmount": 215
  },
  "messages": [],
  "canWaiveFees": true,
  "feesWaived": false
}

Confirm a staff cancellation quote, issue its refunds, mark the reservation canceled and trigger guest/staff cancellation delivery and waitlist handling.

Staff reservation and guest management API.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

quoteIdstringRequired

Allowed, unexpired quote from this reservation's cancel/quote route.

Behavior & constraints

  • Amounts are major currency units. Owner access is rechecked for fee/refund overrides. Financial values may be redacted according to the caller's access.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/cancel/confirm' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_123"}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "status": "canceled",
  "refundIssuedAmount": 215,
  "refundPaymentIds": [
    "payment_refund_123"
  ],
  "canceledAt": "2027-06-01T12:01:00.000Z"
}

Prepare a property-branded, reservation-specific email draft with resolved subject and HTML body for staff editing before sending.

Native email template selection into an editable composer.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Query parameters

templateIdstringRequired

reservation, roomReady, or a custom template ID belonging to this property.

Behavior & constraints

  • Requires reservations.manage; API keys require read_write access because the draft can contain guest portal access capabilities. Responses are private, no-store.
  • Preparing a draft does not send email or change room-ready status. Transaction-bound built-in templates and unresolved merge fields return 422. Reservations, guests and custom templates must belong to the current property.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123/email-templatetemplateId=reservation' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "subject": "Your reservation is confirmed",
  "body": "<html>…</html>"
}

Render the current branded reservation confirmation email for preview, including the guest, room and purchased arrival/departure times. No email is sent.

Console email preview/composer and native iOS resend confirmation action.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • API keys require read_write access, including for GET previews, because email content includes a guest portal access capability.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123/confirmation-email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "subject": "Your reservation is confirmed",
  "body": "<html>…</html>"
}

Resend the guest's branded booking confirmation for an existing reservation. Delivery failures return 502; a missing guest email returns 400.

Console email preview/composer and native iOS resend confirmation action.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • API keys require read_write access, including for GET previews, because email content includes a guest portal access capability.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/confirmation-email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "confirmationNumber": "WUR-EXAMPLE",
  "guestEmailSent": true
}

Send the saved reservation's update or cancellation email. This endpoint sends notification only; it does not modify or cancel the reservation itself.

Console's post-edit and cancellation email decisions.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

modificationTypestringOptional

Email variant; defaults to updated.

Allowed valuesupdatedcanceled
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/modification-email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"modificationType":"updated"}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "confirmationNumber": "WUR-EXAMPLE",
  "guestEmailSent": true
}

Notify the guest about a reservation credit already applied to the invoice, including the resulting balance. This endpoint does not create the credit or move money.

Console's post-credit email prompt.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

creditAmountnumber | stringRequired

Positive credit amount to describe; major currency units.

Behavior & constraints

  • Requires invoice.manage in addition to the reservation permission for this method.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/credit-email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"creditAmount":25}'
Response · 200
JSON
{
  "reservationId": "reservation_123",
  "confirmationNumber": "WUR-EXAMPLE",
  "creditAmount": 25,
  "balanceDue": 0,
  "guestEmailSent": true
}

Create a signed access link to this reservation's guest portal. Requires a guest stay with a guest email; the returned URL grants access and should only be shared with the intended guest.

Console and native iOS share/open guest portal actions.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • The guest exchanges the link token for a guest session using /api/guest-portal/access/exchange.
  • API keys require read_write access: this GET creates a credential that can modify the reservation.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123/guest-portal-access' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "url": "https://www.example-inn.com/guest?token=ACCESS_GRANT"
}

Build an email draft containing the guest's reservation portal link for use in the message composer. Does not send the email.

Console guest message composer via getGuestPortalReservationReplyEmail.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Behavior & constraints

  • API keys require read_write access because the generated draft contains a guest portal access capability.
Request
cURL
curl 'https://api.wikiup.app/api/reservations/reservation_123/guest-portal-reply-email' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID'
Response · 200
JSON
{
  "subject": "Your reservation",
  "body": "<p>View your reservation in your guest portal.</p>"
}

Review removal of an early check-in or late checkout extra from a paid reservation. Returns whether immediate-refund confirmation is required and the exact refundable reduction including applicable taxes.

Innkeeper reservation editor paid-extra removal confirmation.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

kindstringRequired

Extra being removed.

Allowed valuesearlylate

Response fields

requiresConfirmationbooleanOptional

Whether removal requires confirmation and immediate refund.

quoteIdstringOptional

Staff-scoped quote to confirm with PATCH when confirmation is required.

refundAmountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

currencystringOptional

Refund currency.

Behavior & constraints

  • Requires reservations.manage and invoice.manage. Preparing a quote does not remove the extra or issue a refund.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/reservations/reservation_123/arrival-departure' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"early"}'
Response · 200
JSON
{
  "requiresConfirmation": true,
  "quoteId": "quote_123",
  "refundAmount": 16.5,
  "currency": "usd"
}

Confirm a staff-scoped paid-extra removal quote, issue its refund immediately, and update the reservation's invoice and stay times only after the refund succeeds. Replaying a completed quote does not refund twice.

Innkeeper reservation editor Remove and refund action.

Path parameters

idstringRequired

Identifier of the resource in this path.

Request headers

AuthorizationstringRequired

Bearer followed by a Wikiup session/access token.

x-property-idstringRequired

Property to operate on; the caller must belong to this property.

Body fields

quoteIdstringRequired

Quote returned by POST for this reservation and staff member.

Response fields

updatedReservationobjectOptional

Reservation after removal of the paid extra.

refundIssuedAmountnumberOptional

Amount in major currency units: 15 means $15.00 for USD.

Behavior & constraints

  • Requires reservations.manage and invoice.manage. Expired quotes or changed reservation totals require a fresh review.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/reservations/reservation_123/arrival-departure' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-property-id: PROPERTY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"quote_123"}'
Response · 200
JSON
{
  "updatedReservation": {
    "id": "reservation_123",
    "details": {
      "earlyCheckIn": false,
      "eta": "16:00"
    }
  },
  "refundIssuedAmount": 16.5
}

API Reference

Room classifications

Assign an existing unassigned suite. Body: {roomId}.

Behavior & constraints

  • Requires rooms.manage. Same-property ownership and mutation claims are enforced.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/room-types/{id}/rooms' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "type-id",
  "name": "Deluxe King",
  "status": "Draft"
}

Update room name, extraAmenityIds and overrides (nullable maxGuestsCount/maxPets, additionalBeds) without changing the advertised type baseline.

Behavior & constraints

  • Requires rooms.manage. Same-property ownership and mutation claims are enforced.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/room-types/{id}/rooms/{roomId}' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "type-id",
  "name": "Deluxe King",
  "status": "Draft"
}

Append a type-owned photo. Body: {url, description?}.

Behavior & constraints

  • Requires rooms.manage. Same-property ownership and mutation claims are enforced.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/room-types/{id}/gallery' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "type-id",
  "name": "Deluxe King",
  "status": "Draft"
}

List room classifications and shared pricing for the selected property. Requires rooms.view, rooms.manage or reservations.manage.

Behavior & constraints

  • Room types are additive. Existing roomId bookings retain named-room behavior. A type is property-scoped and starts paused. New pooled sales require complete-stay physical assignability; nightly counts alone do not promise a stay.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/room-types' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
[]

Create a room type with its own baseline content and shared pricing before adding suites.

Behavior & constraints

  • Room types are additive. Existing roomId bookings retain named-room behavior. A type is property-scoped and starts paused. New pooled sales require complete-stay physical assignability; nightly counts alone do not promise a stay.
  • Requires rooms.manage and rates.manage. Body: name, memberRoomIds, templateRoomId, status (Draft, Active or Inactive; defaults to Draft), pricing, optional content {version:1, listingTitle, details}, priceRuleIds and dateRanges. Content owns beds and baseline amenities; members may add extras. New types start in Draft. Legacy Paused remains accepted as a non-selling status. Omitted rule/date collections are preserved; explicit empty lists clear them. Date ranges may include enabledPriceRuleIds. Members must be same-property and match advertised bedding, amenities, occupancy and pet promises. Cross-property membership, overlapping inventory mappings and unsafe active-hold membership changes are rejected.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/room-types' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "type-id",
  "name": "Deluxe King",
  "status": "Draft"
}

Read type-owned content, configured suites and shared pricing (legacy types retain representative fallback). Requires rooms.view, rooms.manage or reservations.manage.

Behavior & constraints

  • Room types are additive. Existing roomId bookings retain named-room behavior. A type is property-scoped and starts paused. New pooled sales require complete-stay physical assignability; nightly counts alone do not promise a stay.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/room-types/<id>' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "type-id",
  "name": "Deluxe King",
  "status": "Draft"
}

Update a classification, shared pricing and eligible physical members. Requires rooms.manage and rates.manage.

Behavior & constraints

  • Room types are additive. Existing roomId bookings retain named-room behavior. A type is property-scoped and starts paused. New pooled sales require complete-stay physical assignability; nightly counts alone do not promise a stay.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/room-types/<id>' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "type-id",
  "name": "Deluxe King",
  "status": "Draft"
}

Pause new pooled sales while retaining existing holds for service and assignment.

Behavior & constraints

  • Requires rooms.manage. Body: {"status":"Draft"} or {"status":"Inactive"}. Legacy Paused is still accepted. Does not cancel holds or release physical rooms.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/room-types/<id>' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "id": "type-id",
  "name": "Deluxe King",
  "status": "Draft"
}

Delete an unused, unmapped classification while retaining its physical rooms and named-room prices.

Behavior & constraints

  • Requires rooms.manage. Any booking history or active inventory mapping prevents deletion; pause new sales instead.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/room-types/<id>' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "deleted": true
}

Read nightly counts and full-stay assignability for a room classification.

Behavior & constraints

  • Requires rooms.view, rooms.manage or reservations.manage. Optional excludeReservationId must belong to this property and classification. Paused classifications remain readable for assignment. start and end are property-local YYYY-MM-DD; checkout is exclusive. availableRoomCount counts members eligible for the entire stay. eligibleRooms lists staff-visible full-stay member identities and readiness. nights contains derived roomTypeId/date/availableRoomCount cells. Each physical hold is counted once. Ranges are limited to 730 nights.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/room-types/<id>/availability?start=2027-01-10&end=2027-01-12' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "roomTypeId": "type-id",
  "roomCount": 2,
  "availableRoomCount": 1,
  "nights": [
    {
      "roomTypeId": "type-id",
      "date": "2027-01-10",
      "availableRoomCount": 1
    }
  ]
}

API Reference

Room pricing

Save base/weekend prices and all six room booking rules in an existing pricing record. Requires rates.manage.

Console and iOS pricing editors save the base pricing here, while special date ranges and price-rule assignments use separate endpoints.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

basePricenumberOptional

Standard nightly amount in major currency units.

weekendBasePricenumberOptional

Weekend nightly amount in major currency units. Weekend days come from property settings.

minimumStayinteger | nullOptional

Room floor in nights, 1–365. Channel minimums may tighten it; stricter preserved baselines are not weakened.

maximumStayinteger | nullOptional

1–1125 nights; cannot be less than minimumStay (default floor 1). Null clears the local override.

advanceNoticeHoursinteger | nullOptional

Hours before property-local check-in: 0–24, 48, 72 or 168. Null clears the local override.

sameDayBookingCutoffstring | nullOptional

Property-local HH:mm (24-hour). Channel publication requires a uniform mapped-room cutoff, at/after 02:00 on a half-hour boundary. Unsupported channel cutoffs remain needs_attention; direct enforcement is separate.

preparationDaysinteger | nullOptional

0, 1 or 2 nights before AND after each stay; overlapping occupancy must remain closed until all occupancy is removed. Null clears local override.

bookingWindowDaysinteger | nullOptional

Allowed arrival horizon: 30,60,90,120,150,180,210,240,270,300,330,365. Checkout may extend beyond that horizon. Null clears local override.

Behavior & constraints

  • Returns 404 when no pricing record belongs to this room in the current property. Do not send changes to id, propertyId, or roomId. Only basePrice, weekendBasePrice and the six documented rules are accepted by this PATCH; group is not writable here.
  • Saving succeeds before channel delivery is verified. Inspect channel Activity for sent/verified/needs_attention; a 200 response is not proof of OTA enforcement. Existing stricter channel baselines remain protected. Clearing a local rule does not mean removing an independently stricter channel policy.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/rooms/room_123/pricing' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"basePrice":160,"weekendBasePrice":185,"minimumStay":2,"maximumStay":45,"advanceNoticeHours":24,"preparationDays":0,"bookingWindowDays":90,"sameDayBookingCutoff":null}'
Example response
JSON
{
  "success": true,
  "pricing": {
    "id": "pricing_123",
    "roomId": "room_123",
    "propertyId": "property_123",
    "basePrice": 160,
    "weekendBasePrice": 185,
    "weekendDays": [
      5,
      6
    ],
    "priceDateRanges": [],
    "priceRules": []
  }
}

Attach or detach existing price rules from a room's pricing record. Requires rates.manage.

The console Rooms context updates rule associations when the innkeeper chooses rate adjustments for a room.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

addstring[]Optional

Price rule IDs to attach. Defaults to [].

removestring[]Optional

Price rule IDs to detach. Defaults to [].

Behavior & constraints

  • Removals are processed before additions. Already attached rule IDs are skipped. This changes associations, not the definitions of the price rules.
  • When additions occur, returns {addedRules:[...]}; otherwise returns {message:'Price rules updated successfully'}.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/rooms/room_123/price-rules' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"add":["rule_123"],"remove":[]}'
Example response
JSON
{
  "addedRules": [
    {
      "id": "room_rule_123",
      "roomPricingId": "pricing_123",
      "priceRuleId": "rule_123"
    }
  ]
}

Apply dated nightly prices, splitting or replacing overlapping saved ranges so the new prices take precedence. Requires rates.manage.

Console and iOS rate calendars use this to set holiday, seasonal, or selected-date prices.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

dateRangePricesobject[]Required

Ranges to apply, processed in array order.

replaceIdsstring[]Optional

Optional existing range IDs in this room to replace in the same save. An empty dateRangePrices array removes only these ranges.

pricingobjectOptional

Optional basePrice, weekendBasePrice and booking-rule fields, saved with the ranges before one channel sync. Uses the room pricing validation and room-save approval.

dateRangePrices[].idstringOptional

Optional range ID; generated if omitted.

dateRangePrices[].startDatestringRequired

First priced date, YYYY-MM-DD (inclusive).

dateRangePrices[].endDatestringRequired

Last priced date, YYYY-MM-DD (inclusive).

dateRangePrices[].pricenumberRequired

Nightly amount in major currency units.

Behavior & constraints

  • The room must already have pricing (404 otherwise). propertyId, roomId, and roomPricingId are assigned by the server.
  • This is not a simple append: an overlap can shorten, split, or delete an old range. Use ascending valid date ranges and re-fetch rooms to see the resulting intervals.
  • All range edits in this request finish before channel publication. An uncertain partial failure remains held for reconciliation; a timeout does not imply rollback.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/rooms/room_123/pricing-date-ranges' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"dateRangePrices":[{"startDate":"2026-12-24","endDate":"2026-12-26","price":220}]}'
Example response
JSON
{
  "updated": true
}

Remove dated prices by range IDs or clear an inclusive date interval, preserving portions outside that interval. Requires rates.manage.

The console and iOS calendars clear special prices so the room's base/weekend pricing can apply again.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Query parameters

startDatestringOptional

First date to clear, YYYY-MM-DD. Required with endDate when not deleting by IDs.

endDatestringOptional

Last date to clear, YYYY-MM-DD (inclusive).

Body fields

dateRangePricesobject[]Optional

For ID-based deletion, supply [{id: ...}]. At least one valid ID is required.

Behavior & constraints

  • This DELETE requires JSON: use {dateRangePrices:[{id:...}]} for IDs, or an empty {} body with startDate/endDate query parameters for an interval.
  • No matching ranges return 404. ID deletion returns ‘ID-based price ranges removed.’; interval deletion returns ‘Deleted/trimmed overlapping date range(s).’.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/rooms/room_123/pricing-date-ranges?startDate=2026-12-24&endDate=2026-12-26' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{}'
Example response
JSON
{
  "message": "Deleted/trimmed overlapping date range(s)."
}

API Reference

Rooms

List property rooms alphabetically with details, amenities, nightly pricing, price rules/date ranges, galleries, and check-in instructions. Requires rooms.view.

The console Rooms screen, room chooser, Widget Studio, and iOS room repository use this shared room inventory.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Query parameters

statusstringOptional

Optional exact status filter. Without it, draft and inactive rooms are included.

Allowed valuesActiveInactiveDraft
filtersJSON-encoded object[]Optional

Optional additional AND filters with field, operator, and value, for example [{"field":"name","operator":"EQUAL","value":"Garden Suite"}]. URL-encode the JSON.

Behavior & constraints

  • Returns a bare array. Public availability uses Active rooms; fetching this administrative list does not mean every returned room is bookable.
  • connectedChannels is read-only [{code,name}] display metadata for enabled channel management, active non-simulated connections and current room/listing mappings. Duplicate channels are collapsed. An empty array means no qualifying connections; omission means metadata could not be loaded. This does not certify upstream sync or change channel settings.
  • pricing.weekendDays is populated from property settings, falling back to [5,6]. Malformed filters JSON returns 400.
Request
cURL
curl 'https://api.wikiup.app/api/rooms?status=Active' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
[
  {
    "id": "room_123",
    "propertyId": "property_123",
    "name": "Garden Suite",
    "status": "Active",
    "details": {
      "id": "details_123",
      "roomId": "room_123",
      "propertyId": "property_123",
      "description": "A quiet suite overlooking the garden.",
      "maxGuestsCount": 2,
      "petsAllowed": false,
      "beds": [
        {
          "type": "Queen",
          "count": 1
        }
      ],
      "amenities": []
    },
    "pricing": {
      "id": "pricing_123",
      "roomId": "room_123",
      "propertyId": "property_123",
      "basePrice": 150,
      "weekendBasePrice": 175,
      "weekendDays": [
        5,
        6
      ],
      "priceDateRanges": [],
      "priceRules": []
    },
    "gallery": {
      "id": "gallery_123",
      "propertyId": "property_123",
      "roomId": "room_123",
      "images": []
    }
  }
]

Create a draft room together with its details, pricing, optional amenity links, and gallery. Requires rooms.manage.

The console and iOS Add Room forms create the room in draft state before publishing it.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

roomobjectRequired

Required room wrapper.

room.namestringRequired

Internal staff label, trimmed nonempty string up to 25 characters.

room.listingTitlestring | nullOptional

Guest-facing listing title, up to 255 characters; falls back to room.name if not set.

room.detailsobjectRequired

Room details object. Include maxGuestsCount and the room's description, beds, and pets policy.

room.details.descriptionstringOptional

Room description shown in room details and availability content.

room.details.maxGuestsCountintegerOptional

Maximum occupancy. Must be at least 1 when patching room details.

room.details.petsAllowedbooleanOptional

Legacy compatibility flag. Derived from maxPets > 0 when a numeric limit is supplied; old boolean-only updates remain supported.

room.details.maxPetsinteger | nullOptional

Maximum pets, 0–5. Zero disallows pets. Null/missing preserves the legacy boolean and an unspecified limit; no existing limit is invented.

room.details.petPolicyNotesstring | nullOptional

Owner-written plain text, up to 5000 UTF-16 code units. Displayed on the guest listing only while pets are allowed. Notes stay in Wikiup when the channel has no dedicated pet-policy text transport.

room.details.petFeeAmountnumber | nullOptional

Pet fee in USD, 0–100000 with at most two decimals. Zero explicitly removes a fee; null leaves a channel fee unmanaged. Airbnb publication requires whole USD amounts.

room.details.petFeePeriodstring | nullOptional

Required with a configured amount.

Allowed valuesper_stayper_night
room.details.petFeeChargestring | nullOptional

Required with a configured amount.

Allowed valuesflatper_pet
room.details.bedsobject[]Optional

Bed inventory. Each item contains type, count, and optional description.

room.details.beds[].typestringOptional

Supported bed type (case-sensitive).

Allowed valuesSingleQueenKingCal KingFullTwinCot
room.details.beds[].countintegerOptional

Number of beds of this type.

room.details.amenitiesobject[]Optional

Optional existing amenities represented by objects with id; each becomes a room amenity link.

room.pricingobjectRequired

Pricing object; include basePrice, optional weekendBasePrice and supported booking-rule fields in major currency units/property-local policy values.

room.pricing.basePricenumber | nullOptional

Base nightly rate in major currency units; 150 means $150.00 for USD.

room.pricing.weekendBasePricenumber | nullOptional

Optional nightly rate for the property's configured weekend days, in major currency units.

room.pricing.minimumStayinteger | nullOptional

Room floor in nights, 1–365. Channel minimums may tighten it; stricter preserved baselines are not weakened.

room.pricing.maximumStayinteger | nullOptional

1–1125 nights; cannot be less than minimumStay (default floor 1). Null clears the local override.

room.pricing.advanceNoticeHoursinteger | nullOptional

Hours before property-local check-in: 0–24, 48, 72 or 168. Null clears the local override.

room.pricing.sameDayBookingCutoffstring | nullOptional

Property-local HH:mm (24-hour). Channel publication requires a uniform mapped-room cutoff, at/after 02:00 on a half-hour boundary. Unsupported channel cutoffs remain needs_attention; direct enforcement is separate.

room.pricing.preparationDaysinteger | nullOptional

0, 1 or 2 nights before AND after each stay; overlapping occupancy must remain closed until all occupancy is removed. Null clears local override.

room.pricing.bookingWindowDaysinteger | nullOptional

Allowed arrival horizon: 30,60,90,120,150,180,210,240,270,300,330,365. Checkout may extend beyond that horizon. Null clears local override.

room.pricing.priceDateRangesobject[]Optional

Optional date range pricing overrides (startDate, endDate, price).

room.pricing.priceRulesobject[]Optional

Optional existing price rules to attach.

room.galleryobjectOptional

Optional gallery with images.

Behavior & constraints

  • The server always sets status to Draft and propertyId from the request context, even if another status is submitted. Activate with PATCH /api/rooms/{id} after setup.
  • Returns the created room with details, pricing, and gallery, not a {room: ...} envelope.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/rooms' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"room":{"name":"Garden Suite","details":{"maxGuestsCount":2,"petsAllowed":false,"beds":[{"type":"Queen","count":1}]},"pricing":{"basePrice":150,"weekendBasePrice":175}}}'
Response · 201
JSON
{
  "id": "room_123",
  "propertyId": "property_123",
  "name": "Garden Suite",
  "status": "Draft",
  "details": {
    "id": "details_123",
    "propertyId": "property_123",
    "roomId": "room_123",
    "maxGuestsCount": 2,
    "petsAllowed": false,
    "beds": [
      {
        "type": "Queen",
        "count": 1
      }
    ]
  },
  "pricing": {
    "id": "pricing_123",
    "propertyId": "property_123",
    "roomId": "room_123",
    "basePrice": 150,
    "weekendBasePrice": 175
  }
}

Update a room internal name, guest-facing listing title, or publication status. Requires rooms.manage.

Console and iOS use this to activate, deactivate, or rename a room without rewriting its pricing or details.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

namestringOptional

New internal staff label, nonempty and at most 25 characters. Supply name, listingTitle or status.

listingTitlestring | nullOptional

Guest-facing title, at most 255 characters. Clearing it restores the room.name fallback.

statusstringOptional

Room lifecycle state. Active rooms are offered in public availability; Draft and Inactive rooms are not.

Allowed valuesActiveInactiveDraft

Behavior & constraints

  • At least one of name, listingTitle or status is required (400 otherwise). A room outside the selected property returns 404.
  • This route returns only a success message. Read the room list again if your client needs the refreshed object. There is no GET /api/rooms/{id} handler.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/rooms/room_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"status":"Active"}'
Example response
JSON
{
  "message": "Room updated successfully."
}

Delete a room and clean up its related details, pricing, galleries, instructions, and canceled reservations. Requires rooms.manage.

Console and iOS room deletion actions use this endpoint; deactivation is available when a room still has reservations.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • Returns 409 if any reservation for the room is not canceled, including past non-canceled reservations. Mark the room Inactive instead when its history must remain.
  • No JSON body is required.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/rooms/room_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Response · 204
HTTP
(empty response body)

Merge changes into a room's description, capacity, pets policy, and beds, creating a missing details record when necessary. Requires rooms.manage.

Used by console and iOS room editors; amenities have their own attachment endpoints.

Path parameters

idstringRequired

Room ID, not a RoomDetails ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

descriptionstringOptional

Room description shown in room details and availability content.

maxGuestsCountintegerOptional

Maximum occupancy. Must be at least 1 when patching room details.

petsAllowedbooleanOptional

Legacy compatibility flag. Derived from maxPets > 0 when a numeric limit is supplied; old boolean-only updates remain supported.

maxPetsinteger | nullOptional

Maximum pets, 0–5. Zero disallows pets. Null/missing preserves the legacy boolean and an unspecified limit; no existing limit is invented.

petPolicyNotesstring | nullOptional

Owner-written plain text, up to 5000 UTF-16 code units. Displayed on the guest listing only while pets are allowed. Notes stay in Wikiup when the channel has no dedicated pet-policy text transport.

petFeeAmountnumber | nullOptional

Pet fee in USD, 0–100000 with at most two decimals. Zero explicitly removes a fee; null leaves a channel fee unmanaged. Airbnb publication requires whole USD amounts.

petFeePeriodstring | nullOptional

Required with a configured amount.

Allowed valuesper_stayper_night
petFeeChargestring | nullOptional

Required with a configured amount.

Allowed valuesflatper_pet
bedsobject[]Optional

Bed inventory. Each item contains type, count, and optional description.

beds[].typestringOptional

Supported bed type (case-sensitive).

Allowed valuesSingleQueenKingCal KingFullTwinCot
beds[].countintegerOptional

Number of beds of this type.

Behavior & constraints

  • The merged record must have maxGuestsCount >= 1. An id in the body is discarded; the existing details ID is preserved.
  • Use /api/room-details/{roomId}/amenities to manage amenity associations.
  • maxGuestsCount is a local staff/booking setting and is not propagated as channel guest capacity. Pet-policy/fee edits save configuration and require owner review at /api/rooms/{id}/pet-policy before channel publication. Imported/default values are not automatically published. Existing reservation charges are not recalculated by this room-settings update.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/rooms/room_123/details' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"maxGuestsCount":3,"petsAllowed":true}'
Example response
JSON
{
  "roomDetails": {
    "id": "details_123",
    "roomId": "room_123",
    "propertyId": "property_123",
    "description": "A quiet suite overlooking the garden.",
    "maxGuestsCount": 3,
    "petsAllowed": true,
    "beds": [
      {
        "type": "Queen",
        "count": 1
      }
    ],
    "amenities": []
  },
  "message": "Room details updated successfully"
}

Review mapped room changes, approve saving, and track authoritative channel verification.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

actionstringRequired

review prepares a proposal without channel writes; approve authorizes it; progress checks delivery; status reads durable progress without provider calls; latest resumes an incomplete save; cancel abandons an untouched proposal.

Allowed valuesreviewapproveprogressstatuslatestcancel
draftobjectOptional

Proposed identity, details, pricing, priceRules, priceDateRanges, ruleActions and amenities. Required for review.

reviewIdstringOptional

Proposal UUID for approve/progress/status/cancel.

resumeIdstringOptional

Prior proposal UUID when reviewing an interrupted save again.

advancebooleanOptional

For progress only: true verifies domain persistence and starts the reviewed synchronization. Default false only reads channel state.

Behavior & constraints

  • Requires rooms.manage; approve and progress with advance require the property owner. Reviews expire after 15 minutes. Unmapped rooms return mapped:false and save through the ordinary room APIs.
  • After approval, persist the draft through the ordinary audited APIs; details/pricing may include x-wikiup-room-save-review to defer inline sync. That header is bound to the owner, property, room and reviewed field values. Call progress with advance:true only after all domain writes succeed.
  • Response: review returns {reviewId:string|null,mapped:boolean,rows:RoomSaveRow[]}; latest returns that plus draft and saved, or null. approve returns {status:"approved"}; progress returns {status:"pending"|"complete",rows}; status includes stage without calling the provider. Row fields: id, roomId, room, channel, listing, setting, current, proposed, status, optional reason. Row statuses include ready, verified, local_only, unsupported, unavailable, needs_attention and pending; accepted requests are not proof of enforcement.
  • The iOS room editor uses the same review/approve/persist/progress protocol and resumes interrupted saves through latest. Neither client silently bypasses approval if review fails. Persist only the reviewed changed fields, preserving explicit null versus omission. Price-rule definitions and room assignments use their ordinary audited endpoints after approval.
  • Partial saves retain a durable delivery hold and can be resumed through latest/review. Cancellation releases an approval only if domain data still matches the original baseline. Accepted delivery remains pending until authoritative readback verifies it.
  • The table distinguishes verified, pending, unavailable, unsupported and Wikiup-only settings. Metadata/guest capacity have no current channel transport; automatic price sync remains opt-in. Shared rule changes include other affected mapped rooms.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/rooms/room_123/save-review' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"action":"review","draft":{"pricing":{"basePrice":150}}}'
Example response
JSON
{
  "reviewId": "00000000-0000-4000-8000-000000000001",
  "mapped": true,
  "rows": []
}

Review or publish this room's pet policy and fee to connected listings. Requires the property owner and property.manage.

Path parameters

idstringRequired

Room ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

actionstringRequired

review reads effective settings and creates a 15-minute proposal; publish submits only that reviewed proposal.

Allowed valuesreviewpublish
reviewIdstringOptional

UUID from review; required for publish.

Behavior & constraints

  • Currently supports Airbnb native flat/per-pet fees per stay/per night. Other channels, unknown fees, currency mismatches and fractional Airbnb fee amounts remain unsupported; no silent conversion is performed.
  • Airbnb capacity is explicit 0–5. Numeric maxPets drives petsAllowed; unknown upstream capacity is held rather than guessed. Pet policy notes have no dedicated current channel text transport and stay in Wikiup. Legacy boolean-only targets preserve verified upstream counts.
  • Review does not write to channels. Publication validates current room settings, identities and upstream settings. A timeout retains an uncertain receipt without blind replay; fresh listing readback is required for verified status.
  • Unrelated pricing, fees and taxes are preserved. Channex's pricing-settings operation triggers provider-side synchronization; passing local tests does not prove provider enforcement.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/rooms/room_123/pet-policy' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"action":"review"}'
Example response
JSON
{
  "reviewId": "00000000-0000-4000-8000-000000000001",
  "rows": []
}

Materialize selected built-in amenities without replacing custom entries.

Requires rooms.manage. Accepts up to 1000 IDs returned by GET /api/amenities. Validates the complete selection against this property, reuses existing saved entries, and inserts only selected defaults. Returns saved amenities for the existing room draft/save workflow. Retries preserve IDs, names and custom icons.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

amenityIdsstring[]Required

Property catalog IDs selected by the owner.

Behavior & constraints

  • Does not attach entries to a room or publish OTA amenities. No schema publication is required. All built-in templates remain available after a property catalog entry is deleted.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/amenities/selection' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"amenityIds":["default-amenity-v1-example"]}'
Example response
JSON
{
  "amenities": [
    {
      "id": "amenity_123",
      "propertyId": "property_123",
      "name": "Wi-Fi",
      "icon": "wifi",
      "description": "Wireless internet"
    }
  ]
}

List built-in amenities merged with the property's custom reusable catalog. Requires rooms.view.

Read-only array for new and existing properties. Built-in entries include isDefault, catalogKey, category and aliases with deterministic property-scoped IDs. Existing custom names and icons take precedence. Call POST /api/amenities/selection for selected default IDs before assigning them to a room.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • Returns a bare array. Reading does not seed the database or attach any amenity to a room. Catalog availability does not imply channel delivery support.
Request
cURL
curl 'https://api.wikiup.app/api/amenities' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
[
  {
    "id": "amenity_123",
    "propertyId": "property_123",
    "name": "Wi-Fi",
    "icon": "wifi",
    "description": "Wireless internet"
  }
]

Create an amenity definition for reuse across rooms. Requires rooms.manage.

Used by the console Amenities Catalog dialog before attaching a new feature to rooms.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

namestringRequired

Display name; a nonempty value is required.

iconstringRequired

Icon identifier or image reference used by the client; a nonempty value is required.

descriptionstringOptional

Optional feature description.

Behavior & constraints

  • The server creates the ID and assigns the selected property. Returns the amenity directly.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/amenities' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Wi-Fi","icon":"wifi","description":"Wireless internet"}'
Response · 201
JSON
{
  "id": "amenity_123",
  "propertyId": "property_123",
  "name": "Wi-Fi",
  "icon": "wifi",
  "description": "Wireless internet"
}

Retrieve a single amenity belonging to the selected property. Requires rooms.view.

Available to resolve a known amenity ID when building a room-management integration.

Path parameters

idstringRequired

Amenity ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • An absent amenity or one outside the selected property returns 404.
Request
cURL
curl 'https://api.wikiup.app/api/amenities/amenity_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
{
  "id": "amenity_123",
  "propertyId": "property_123",
  "name": "Wi-Fi",
  "icon": "wifi",
  "description": "Wireless internet"
}

Remove an unused amenity definition from the property catalog. Requires rooms.manage.

Used when maintaining the console amenity catalog; detach the amenity from rooms first.

Path parameters

idstringRequired

Amenity ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • Returns 409 when the amenity is in use by a room. Deleting the definition is separate from detaching a room association.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/amenities/amenity_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Response · 204
HTTP
(empty response body)

List amenities attached to a room. Requires rooms.view.

The console room editor adds and removes amenity selections through this route.

Path parameters

roomIdstringRequired

Room ID, despite the room-details path prefix; do not pass a RoomDetails ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • Returns a bare array; a missing details record produces [].
Request
cURL
curl 'https://api.wikiup.app/api/room-details/room_123/amenities' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Response · 200
JSON
[
  {
    "id": "amenity_123",
    "propertyId": "property_123",
    "name": "Wi-Fi",
    "icon": "wifi",
    "description": "Wireless internet"
  }
]

Attach one or more existing catalog amenities to a room. Requires rooms.manage.

The console room editor adds and removes amenity selections through this route.

Path parameters

roomIdstringRequired

Room ID, despite the room-details path prefix; do not pass a RoomDetails ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

amenityIdsstring[]Required

Nonempty list of catalog amenity IDs.

Behavior & constraints

  • A missing room details record is initialized before adding associations. Returns {message, added}, where added contains association records. If any requested amenity is already attached, the request returns 400 rather than silently ignoring it.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/room-details/room_123/amenities' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"amenityIds":["amenity_123"]}'
Response · 201
JSON
{
  "message": "Amenities added successfully",
  "added": [
    {
      "id": "room_amenity_123",
      "roomDetailsId": "details_123",
      "amenityId": "amenity_123"
    }
  ]
}

Detach one or more amenities from a room without deleting their catalog definitions. Requires rooms.manage.

The console room editor adds and removes amenity selections through this route.

Path parameters

roomIdstringRequired

Room ID, despite the room-details path prefix; do not pass a RoomDetails ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Body fields

amenityIdsstring[]Required

Nonempty list of catalog amenity IDs.

Behavior & constraints

  • A missing details record is treated as already detached and still returns success. This DELETE requires a JSON body.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/room-details/room_123/amenities' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123' \
  -H 'Content-Type: application/json' \
  -d '{"amenityIds":["amenity_123"]}'
Response · 200
JSON
{
  "message": "Amenities deleted successfully"
}

Detach a single catalog amenity from a room. Requires rooms.manage.

Single-association alternative to the batch room-amenities DELETE used by the console editor.

Path parameters

roomIdstringRequired

Room ID.

amenityIdstringRequired

Catalog amenity ID, not the association ID.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • Returns 404 when the selected room has no details record. No request body is needed; only DELETE is implemented on this item route.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/room-details/room_123/amenities/amenity_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
{
  "message": "Amenity deleted successfully"
}

API Reference

Staging test data

Read sandbox reservation simulations and their actual import status.

Path parameters

idstringRequired

Wikiup property ID.

Behavior & constraints

  • Preview only, owner-only, requires property.manage. Use the preview API base URL. Production rejects this endpoint. No provider credentials or IDs are returned.
  • Returns the 25 most recently created simulations. delivery is pending, received, or applied. received can indicate an import issue; inspect the main channel workspace. reservationIds identify the corresponding Wikiup reservations.
Request
cURL
curl 'https://api-preview.wikiup.app/api/properties/{id}/channel-management/sandbox-reservations' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "simulations": [
    {
      "id": "simulation-uuid",
      "roomId": "room-id",
      "arrivalDate": "2027-08-16",
      "departureDate": "2027-08-18",
      "nightlyPriceUsd": 123,
      "status": "submitted",
      "delivery": "applied",
      "reservationIds": [
        "wikiup-reservation-id"
      ]
    }
  ]
}

Prepare Booking CRS or submit and verify isolated staging reservation events.

Path parameters

idstringRequired

Wikiup property ID.

Body fields

actionstringRequired

Sandbox action.

Allowed valuespreparecreatemodifycancelverifywebhook_evidence
requestIdstringOptional

Client-generated UUID for idempotent create/modify/cancel requests.

simulationIdstringOptional

Returned simulator ID, required for modify/cancel.

roomIdstringOptional

A room belonging to this property; required for prepare/create.

arrivalDatestringOptional

YYYY-MM-DD; required for create/modify.

departureDatestringOptional

Exclusive checkout date; required for create/modify.

nightlyPriceUsdnumberOptional

Price in USD, e.g. 123 means $123. Required for create/modify.

Commands

webhook_evidenceRead Channex HTTP delivery outcomes for this isolated property.

Success response: HTTP 200

Owner-only and preview-only. Reads the registered property webhook after checking upstream isolation; accepts no hook ID from the caller.

No booking, replay, provider write, guest payload, authorization header or provider error body is returned. A local receipt or successful import alone does not establish callback HTTP success.

webhook_evidence request body
JSON
{
  "action": "webhook_evidence"
}
webhook_evidence response
JSON
{
  "deliveries": [
    {
      "id": "<delivery-id>",
      "success": true,
      "statusCode": 200,
      "event": "booking_new",
      "attempt": 0,
      "responseTime": 1000
    }
  ]
}
prepareInstall/reuse Booking CRS and prepare the selected room from its saved pricing.

Success response: HTTP 200

Enable the isolated property after owner terms review. Requires a room or room-type:<id> classification selection in that property; a new mapping needs a positive saved basePrice.

Checks local and upstream no-OTA scope. Reuses completed room provisioning; creates no reservation or payment and publishes no inventory.

prepare request body
JSON
{
  "action": "prepare",
  "roomId": "<isolated-room-id>"
}
prepare response
JSON
{
  "status": "ready",
  "roomId": "<isolated-room-id>"
}
createSubmit an external staging booking to the normal revision delivery pipeline.

Success response: HTTP 202

Dates are YYYY-MM-DD, departure exclusive, 1–30 nights. Price is USD per night, positive and at most 100000. A fixed synthetic guest and one adult are used.

202 means submitted, not imported. Retain simulationId, reuse identical requestId/body after an uncertain client response, then poll delivery.

create request body
JSON
{
  "action": "create",
  "requestId": "<new UUID>",
  "roomId": "<isolated-room-id>",
  "arrivalDate": "2027-03-10",
  "departureDate": "2027-03-12",
  "nightlyPriceUsd": 137
}
create response
JSON
{
  "simulationId": "<simulation-id>",
  "status": "submitted",
  "action": "create"
}
modifyChange only a recorded test booking belonging to this property.

Success response: HTTP 202

Use the original simulationId, not an external booking ID. Modifies dates/price for the recorded room; a room move is not part of this command.

The same connectionId scope used during create must be retained when testing a simulated channel.

modify request body
JSON
{
  "action": "modify",
  "requestId": "<new UUID>",
  "simulationId": "<simulation-id>",
  "arrivalDate": "2027-03-10",
  "departureDate": "2027-03-13",
  "nightlyPriceUsd": 149
}
modify response
JSON
{
  "simulationId": "<simulation-id>",
  "status": "submitted",
  "action": "modify"
}
cancelCancel only the recorded external staging test booking.

Success response: HTTP 202

Cannot cancel arbitrary provider reservations. Confirm destructive intent in your UI before submitting.

Poll until status=canceled and delivery=applied; a submitted cancellation is not completed ingestion.

cancel request body
JSON
{
  "action": "cancel",
  "requestId": "<new UUID>",
  "simulationId": "<simulation-id>"
}
cancel response
JSON
{
  "simulationId": "<simulation-id>",
  "status": "submitted",
  "action": "cancel"
}
verifyConsume and acknowledge booking revisions for this isolated property.

Success response: HTTP 200

Owner-only and preview-only; checks local and upstream isolation before ingestion.

Runs the normal revision consumer, not broad synchronization. Does not publish rates, restrictions or availability. Inspect blocked/complete and per-row delivery, not HTTP 200 alone.

verify request body
JSON
{
  "action": "verify"
}
verify response
JSON
{
  "simulations": [],
  "verification": {
    "applied": 0,
    "blocked": 0,
    "complete": true
  }
}

Error responses

401
Missing/invalid session or API key.
403
Production, nonowner, or missing property.manage permission.
404
Room or recorded simulation not found in this property.
409
Disabled setup, real channel connection, mismatched mapping, reused request ID with different input, or unresolved create outcome.
422
Invalid dates, price, command body, room pricing or upstream no-OTA guard.
503
Missing preview integration configuration.

Behavior & constraints

  • Owner-only, preview only. Enable channel management first and use a dedicated sandbox property with no real connected OTA channels. Simulated preview connections are allowed. The server also checks the upstream property has zero connected channels before sending a test booking.
  • webhook_evidence reads provider HTTP delivery logs for the registered property webhook after upstream isolation is checked. It returns only success/status/event/timing metadata and does not replay notifications. The receiver stores metadata promptly; normal feed processing imports and acknowledges bookings separately.
  • prepare requires action and roomId; returns 200 ready. It installs/reuses Booking CRS and provisions/reuses that room mapping from saved room pricing. Requires a positive base price for a new mapping. It does not submit a booking, activate an OTA or accept subscription terms.
  • create requires action, UUID requestId, roomId, arrivalDate, departureDate, and nightlyPriceUsd. Optional connectionId scopes the test to an active simulated channel and requires a room mapped to that channel. Uses a fixed synthetic guest, USD, one adult and a stay of 1–30 nights. Does not create a real OTA booking, payment, or guest email.
  • modify requires a new UUID requestId, simulationId, arrivalDate, departureDate and nightlyPriceUsd. cancel requires a new UUID requestId and simulationId. Only simulator-created bookings belonging to this property can be changed; arbitrary external reservation IDs are not accepted.
  • Reuse the same requestId and identical command when retrying. Changed input with the same ID returns 409. Uncertain upstream writes require reconciliation, never a blind duplicate create.
  • create, modify and cancel return 202 submitted; that is not proof of import. Poll GET for delivery:applied. verify guards both local and provider no-OTA scope, then runs only the normal booking revision consumer and acknowledgement path; it does not publish rates, restrictions or availability. It returns 200 with simulations and verification counts. No reservation is inserted directly by this simulator.
Request
cURL
curl -X POST 'https://api-preview.wikiup.app/api/properties/{id}/channel-management/sandbox-reservations' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"action":"create","requestId":"7bb0f85c-a641-4d3b-968b-c786c7be1b4d","roomId":"room-id","arrivalDate":"2027-08-16","departureDate":"2027-08-18","nightlyPriceUsd":123}'
Response · 202
JSON
{
  "simulationId": "7bb0f85c-a641-4d3b-968b-c786c7be1b4d",
  "status": "submitted",
  "action": "create"
}

This example is create (202 submitted). prepare, verify and webhook_evidence return 200; expand the selected command for its actual response. Neither 200 nor 202 alone proves imported delivery.

API Reference

System

Sends a feature suggestion from the public feature catalog to the Wikiup team. No account or property is required.

The request form shown after searching the public PMS feature catalog.

Body fields

namestringRequired

Your name, 1–100 characters. Control characters are not accepted.

emailstringRequired

Valid contact email, at most 254 characters; used as the reply-to address.

descriptionstringRequired

The requested feature, 20–5,000 characters after trimming.

searchQuerystringOptional

Optional feature-search context, at most 200 characters.

websitestringOptional

Spam-prevention field; omit or leave empty.

Allowed values

Behavior & constraints

  • Send application/json with a body no larger than 32 KiB. Invalid input returns 400; oversized bodies return 413; another content type returns 415.
  • Successful submissions return only {ok:true} after the email provider accepts the message. Delivery failures return 503 without provider details; do not retry automatically because a timed-out delivery may already have been accepted.
  • Abuse checks may return 429 with Retry-After. The form uses a honeypot and bounded per-instance request limits; these limits are not a distributed delivery guarantee.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/feature-requests' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alex Morgan","email":"owner@example.com","description":"I would love a calendar view for planning seasonal room maintenance.","searchQuery":"maintenance calendar"}'
Example response
JSON
{
  "ok": true
}

Checks that the API can respond to a request. Used by deployment smoke checks and load balancers.

Behavior & constraints

  • This is a liveness check; it does not query property data or verify payment and email integrations.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/health'
Example response
JSON
{
  "status": "ok"
}

Identifies the running API release and environment so clients can diagnose a deployment mismatch.

Response fields

versionstring

Application package version, or unknown if unavailable.

commitstring

Build's source commit, or unknown when not supplied by the deployment.

deploymentEnvstring

Deployment environment label, normally production or preview; unknown when not configured.

Request
cURL
curl -X GET 'https://api.wikiup.app/api/version'
Example response
JSON
{
  "version": "0.1.0",
  "commit": "abc123",
  "deploymentEnv": "production"
}

Returns one random llama photo URL for account profile photo selection. Each request may return a different image.

Used by current console registration and iOS onboarding/profile selection.

Behavior & constraints

  • The response is JSON containing a URL, not image bytes. A photo-provider failure returns 502; keep the previous selection and allow retry.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/random-llama'
Example response
JSON
{
  "url": "https://images.example.com/llama.jpg"
}

API Reference

Team & Access

Read the selected property's owners, team members, access groups, and invitation summaries. Membership records include effective access and a profile for display.

Used by console Team management and the native innkeeper team/onboarding flows.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.members.view or team.groups.view.
  • The current shared authorization guard requires an owner membership. Delegated team permission keys alone do not grant access to this route.
  • The response is one summary object; there are no separate GET collection routes for team/groups or team/invites.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/team' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 200
JSON
{
  "propertyId": "property_example",
  "owners": [],
  "members": [],
  "groups": [
    {
      "id": "group_example",
      "propertyId": "property_example",
      "name": "Front desk",
      "description": null,
      "permissions": [
        "reservations.view",
        "reservations.manage"
      ],
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    }
  ],
  "invites": []
}

Create a property-specific access group for inviting or assigning staff. Permissions determine which console and API operations members can perform.

Used by console Team management and the native innkeeper team/onboarding flows.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

namestringRequired

Unique property access-group name, 1–120 characters.

descriptionstring | nullOptional

Optional group description, up to 500 characters.

permissionsstring[]Required

At least one supported permission. Dependencies are expanded; for example edit permissions include the corresponding view access.

Allowed valuesreservations.viewrooms.viewoperations.viewreservations.managereservations.import_exportrooms.manageoperations.managerates.manageaddons.manageinvoice.viewinvoice.managefinancials.viewproperty.managewidgets.manageteam.today.viewteam.today.editteam.tasks.viewteam.tasks.editteam.readings.viewteam.readings.editteam.calendar.viewteam.calendar.editteam.members.viewteam.members.editteam.groups.viewteam.groups.edit

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.groups.edit.
  • The current shared authorization guard makes all /api/team endpoints owner-only, including routes that also check delegated permission keys.
  • Duplicate names are rejected with 409.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/team/groups' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Front desk","permissions":["reservations.view","reservations.manage"]}'
Response · 201
JSON
{
  "id": "group_example",
  "propertyId": "property_example",
  "name": "Front desk",
  "description": null,
  "permissions": [
    "reservations.view",
    "reservations.manage"
  ],
  "createdByUid": "user_example",
  "createdAt": "2026-10-22T17:00:00.000Z",
  "updatedAt": "2026-10-22T17:00:00.000Z"
}

Change an access group's name, description, or permission set. Permission changes affect the team's effective access; send the complete desired permissions array when replacing it.

Used by console Team management and the native innkeeper team/onboarding flows.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

namestringOptional

Unique property access-group name, 1–120 characters.

descriptionstring | nullOptional

Optional group description, up to 500 characters.

permissionsstring[]Optional

At least one supported permission. Dependencies are expanded; for example edit permissions include the corresponding view access.

Allowed valuesreservations.viewrooms.viewoperations.viewreservations.managereservations.import_exportrooms.manageoperations.managerates.manageaddons.manageinvoice.viewinvoice.managefinancials.viewproperty.managewidgets.manageteam.today.viewteam.today.editteam.tasks.viewteam.tasks.editteam.readings.viewteam.readings.editteam.calendar.viewteam.calendar.editteam.members.viewteam.members.editteam.groups.viewteam.groups.edit

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.groups.edit.
  • The current shared authorization guard makes all /api/team endpoints owner-only, including routes that also check delegated permission keys.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/team/groups/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"description":"Reservation and guest service staff"}'
Response · 200
JSON
{
  "id": "group_example",
  "propertyId": "property_example",
  "name": "Front desk",
  "description": "Reservation and guest service staff",
  "permissions": [
    "reservations.view",
    "reservations.manage"
  ],
  "createdByUid": "user_example",
  "createdAt": "2026-10-22T17:00:00.000Z",
  "updatedAt": "2026-10-22T17:00:00.000Z"
}

Delete an unused property access group. A group still assigned to members or active invitations cannot be deleted; reassign or remove those references first.

Used by console Team management and the native innkeeper team/onboarding flows.

Path parameters

idstringRequired

ID of the record in the selected property.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.groups.edit.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/team/groups/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

Update a property member’s status, access group, and duty assignments. The path identifies the membership record, not the person’s user ID.

Used by console Team management and the native innkeeper team/onboarding flows.

Path parameters

idstringRequired

Property membership ID returned by GET /api/team.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

groupIdstring | nullOptional

Changes the access group; the group must belong to this property. Omit to preserve it.

promoteToOwnerbooleanOptional

True grants owner access and clears the group. Owner authorization is required; defaults to false.

statusactive | inactiveOptional

Property membership status; defaults to the current status.

dutyIdsstring[]Optional

Complete set of eligible duty IDs in this property. Omit to preserve assignments; an empty array clears them.

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.members.edit.
  • The current shared authorization guard makes all /api/team endpoints owner-only, including routes that also check delegated permission keys.
  • The last active owner cannot be deactivated, removed or demoted (409). Inactive memberships cannot access the property. Assignments define coverage eligibility independently of notification delivery preferences.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/team/members/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"group_example"}'
Response · 200
JSON
{
  "id": "membership_example",
  "propertyId": "property_example",
  "uid": "staff_user",
  "role": "Front desk",
  "groupId": "group_example"
}

Revoke a person's membership in this property. This removes property access without deleting the person's Wikiup account or memberships elsewhere.

Used by console Team management and the native innkeeper team/onboarding flows.

Path parameters

idstringRequired

Membership ID, not user UID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.members.edit.
  • The current shared authorization guard makes all /api/team endpoints owner-only, including routes that also check delegated permission keys.
  • The last owner cannot be removed (409).
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/team/members/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

Email a seven-day property-access invitation. Existing pending invitations for the same email/property are revoked before issuing the new link.

Used by console Team management and the native innkeeper team/onboarding flows.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Body fields

emailstringRequired

Invitee email; normalized to lowercase. An existing property member cannot be invited again.

groupIdstring | nullOptional

Required unless inviteAsOwner is true.

inviteAsOwnerbooleanOptional

Invite as owner instead of a group member. Only an owner can set true; defaults to false.

Response fields

statusstringOptional

Persisted invitation status. Preview/summary statusLabel can additionally be expired when a pending invite has passed expiresAt.

Allowed valuespendingacceptedrevokedrejected

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.members.edit.
  • The current shared authorization guard makes all /api/team endpoints owner-only, including routes that also check delegated permission keys.
  • The invitation link is sent by email; the raw invitation token is not returned for clients to construct their own links.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/team/invites' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID" \
  -H 'Content-Type: application/json' \
  -d '{"email":"staff@example.com","groupId":"group_example"}'
Response · 201
JSON
{
  "id": "invite_example",
  "propertyId": "property_example",
  "email": "staff@example.com",
  "groupId": "group_example",
  "roleLabel": "Front desk",
  "invitedByUid": "user_example",
  "status": "pending",
  "expiresAt": "2026-10-29T17:00:00.000Z",
  "createdAt": "2026-10-22T17:00:00.000Z"
}

Replace an unaccepted invitation with a new seven-day invitation and send a fresh email. The prior link is revoked; retain the returned new invitation ID.

Used by console Team management and the native innkeeper team/onboarding flows.

Path parameters

idstringRequired

Existing invitation ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Response fields

statusstringOptional

Persisted invitation status. Preview/summary statusLabel can additionally be expired when a pending invite has passed expiresAt.

Allowed valuespendingacceptedrevokedrejected

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.members.edit.
  • The current shared authorization guard makes all /api/team endpoints owner-only, including routes that also check delegated permission keys.
  • No body required. Accepted invitations cannot be resent (409).
Request
cURL
curl -X POST 'https://api.wikiup.app/api/team/invites/id_example/resend' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 201
JSON
{
  "id": "replacement_invite",
  "propertyId": "property_example",
  "email": "staff@example.com",
  "groupId": "group_example",
  "roleLabel": "Front desk",
  "invitedByUid": "user_example",
  "status": "pending",
  "expiresAt": "2026-10-29T17:00:00.000Z",
  "createdAt": "2026-10-22T17:00:00.000Z"
}

Delete an unaccepted invitation so its link no longer grants access. Accepted invitations cannot be deleted; revoke the resulting membership instead.

Used by console Team management and the native innkeeper team/onboarding flows.

Path parameters

idstringRequired

Invitation ID.

Request headers

x-property-idstringRequired

Property whose membership and permissions authorize this operation.

Behavior & constraints

  • Requires an interactive account session. API keys cannot read or change property access management.
  • Currently requires property ownership as well as team.members.edit.
  • The current shared authorization guard makes all /api/team endpoints owner-only, including routes that also check delegated permission keys.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/team/invites/id_example' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H "x-property-id: $PROPERTY_ID"
Response · 204
HTTP
No response body.

Preview an invitation link without accepting it. Returns the property, invited email, role/group, inviter, expiry, and status so the recipient can choose the correct account.

Used by the invitation landing screen before sign-in.

Body fields

tokenstringRequired

Opaque token from the invitation email URL.

Response fields

statusLabelstringOptional

Current invitation state, including derived expiry.

Allowed valuespendingacceptedrevokedrejectedexpired

Behavior & constraints

  • A preview can describe an inactive or expired invite. Check statusLabel and isExpired before presenting acceptance.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/property-access-invites/resolve' \
  -H 'Content-Type: application/json' \
  -d '{"token":"invitation_token"}'
Response · 200
JSON
{
  "inviteId": "invite_example",
  "propertyId": "property_example",
  "propertyName": "Cedar Ridge Inn",
  "email": "staff@example.com",
  "roleLabel": "Front desk",
  "inviter": {
    "uid": "user_example",
    "displayName": "Alex Morgan",
    "email": "owner@example.com"
  },
  "group": {
    "id": "group_example",
    "propertyId": "property_example",
    "name": "Front desk",
    "description": null,
    "permissions": [
      "reservations.view",
      "reservations.manage"
    ],
    "createdByUid": "user_example",
    "createdAt": "2026-10-22T17:00:00.000Z",
    "updatedAt": "2026-10-22T17:00:00.000Z"
  },
  "expiresAt": "2026-10-29T17:00:00.000Z",
  "statusLabel": "pending",
  "isExpired": false
}

List active pending property invitations for the authenticated account's email. Used during onboarding and sign-in to offer joining an existing property before creating a new one.

Used by console Team management and the native innkeeper team/onboarding flows.

Behavior & constraints

  • No x-property-id is needed. Returns a bare array, not an invites envelope; already-held memberships and expired invitations are excluded.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/property-access-invites/pending' \
  -H "Authorization: Bearer $WIKIUP_TOKEN"
Response · 200
JSON
[
  {
    "inviteId": "invite_example",
    "propertyId": "property_example",
    "propertyName": "Cedar Ridge Inn",
    "email": "staff@example.com",
    "roleLabel": "Front desk",
    "inviter": {
      "uid": "user_example",
      "displayName": "Alex Morgan",
      "email": "owner@example.com"
    },
    "group": {
      "id": "group_example",
      "propertyId": "property_example",
      "name": "Front desk",
      "description": null,
      "permissions": [
        "reservations.view",
        "reservations.manage"
      ],
      "createdByUid": "user_example",
      "createdAt": "2026-10-22T17:00:00.000Z",
      "updatedAt": "2026-10-22T17:00:00.000Z"
    },
    "expiresAt": "2026-10-29T17:00:00.000Z",
    "statusLabel": "pending",
    "isExpired": false
  }
]

Accept an emailed invitation token and create property membership for the authenticated account. The account email must match the invitation email.

Used by the signed-in invitation landing screen.

Body fields

tokenstringRequired

Opaque token from the invitation email.

Behavior & constraints

  • No property header required. Expired invitations return 410, inactive/already-member cases return 409, and an email mismatch returns 403.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/property-access-invites/accept' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"token":"invitation_token"}'
Response · 200
JSON
{
  "inviteId": "invite_example",
  "propertyId": "property_example",
  "membership": {
    "uid": "staff_user",
    "propertyId": "property_example",
    "isOwner": false,
    "groupId": "group_example",
    "permissions": [
      "reservations.view",
      "reservations.manage"
    ]
  }
}

Accept or reject a pending invitation identified by ID from the account's invitation list. Acceptance creates membership; rejection records the decision without joining the property.

Used by console Team management and the native innkeeper team/onboarding flows.

Body fields

inviteIdstringRequired

Invitation ID returned by pending or resolve.

actionstringOptional

Always send explicitly. The current route defaults to reject if omitted.

Allowed valuesacceptreject

Behavior & constraints

  • The authenticated email must match the invite. No x-property-id is needed.
  • Accept returns inviteId, propertyId, and membership; reject returns inviteId, propertyId, and status=rejected.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/property-access-invites/respond' \
  -H "Authorization: Bearer $WIKIUP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"inviteId":"invite_example","action":"reject"}'
Response · 200
JSON
{
  "inviteId": "invite_example",
  "propertyId": "property_example",
  "status": "rejected"
}

API Reference

Team Notifications

Read the authenticated member's unread count or ten-item unread or recent history page for the current property.

Request headers

AuthorizationstringRequired

Bearer session token or authorized property API key. Recipient identity is always derived from the authenticated credential.

x-property-idstringRequired

Current property. Current membership and operation permission are checked on every request.

Query parameters

viewstringOptional

Defaults to unread. Recent includes read and unread nonexpired alerts. Count always returns only unread alerts.

Allowed valuesunreadrecent
countstringOptional

Set to true for a count-only response. Otherwise returns records and nextCursor.

cursorstringOptional

Opaque nextCursor from the previous response. Omit for newest ten unread alerts.

Behavior & constraints

  • Requires reservations.view. No client-supplied UID is accepted. Responses are private, no-store.
  • Expired alerts are excluded at read time; retention is 30 days. Count first, then fetch the first page. Optional secondary requests must not gate console loading.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/notifications?count=true' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
{
  "count": 12
}

Mark one alert read by removing it from the authenticated member's unread inbox.

Path parameters

idstringRequired

Notification ID returned by the current user's inbox.

Request headers

AuthorizationstringRequired

Bearer session token or authorized property API key. Recipient identity is always derived from the authenticated credential.

x-property-idstringRequired

Current property. Current membership and operation permission are checked on every request.

Behavior & constraints

  • Requires reservations.view. Idempotent, bodyless DELETE. UID and property scope are applied to the update query. Sets readAt without deleting the record. Read alerts remain in Recent until their original 30-day expiry.
Request
cURL
curl -X DELETE 'https://api.wikiup.app/api/notifications/<notification-id>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: <property-id>'
Response · 204
HTTP
204 No Content

Read the property group's opt-in reservation and waitlist console alert subscriptions.

Request headers

AuthorizationstringRequired

Bearer session token or authorized property API key. Recipient identity is always derived from the authenticated credential.

x-property-idstringRequired

Current property. Current membership and operation permission are checked on every request.

Behavior & constraints

  • Requires team.groups.view. Missing settings mean unsubscribed. The virtual owners group configures owners who have no access-group assignment.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/team/notification-settings' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: <property-id>'
Example response
JSON
[]

Enable or disable reservation and waitlist alerts for one property access group.

Request headers

AuthorizationstringRequired

Bearer session token or authorized property API key. Recipient identity is always derived from the authenticated credential.

x-property-idstringRequired

Current property. Current membership and operation permission are checked on every request.

Body fields

groupIdstringRequired

An existing property group ID or owners for the virtual owner group.

reservationNotificationsbooleanRequired

Opt in to reservation created, updated, canceled and waitlist created/updated events.

Behavior & constraints

  • Requires team.groups.edit. Non-owner groups must exist in this property. Recipient memberships must also grant reservations.view. This does not change existing mobile push delivery.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/team/notification-settings' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: <property-id>' \
  -H 'Content-Type: application/json' --data '{"groupId":"owners","reservationNotifications":true}'
Example response
JSON
{
  "id": "<settings-id>",
  "propertyId": "<property-id>",
  "groupId": "owners",
  "reservationNotifications": true,
  "updatedAt": "2026-10-27T12:00:00.000Z"
}

API Reference

Travel

Browse all active hotel rooms or pooled room types with their galleries, without dates.

Path parameters

listingIdstringRequired

Opaque parent hotel listing ID, URL-encoded once.

Query parameters

pageintegerOptional

One-based property page, 1–1000; default 1.

Response fields

roomsArray<object>Required

Active hotel rooms or pooled types, independent of date availability. Same fields as individual room detail. maxItems: 12

rooms[]objectRequired

Public details and photos for one active hotel room or pooled room type.

rooms[].idstringRequired

Opaque option ID, identical to the parent availability option id. Encode once per path segment.

rooms[].listingIdstringRequired

Parent hotel listing ID; inns use hotel booking identity too.

rooms[].propertyIdstringRequired

Stable property ID.

rooms[].roomIdstring | nullRequired

Named room ID, or null for pooled room types.

rooms[].roomTypeIdstring | nullRequired

Pooled room type ID, or null for named rooms. No physical member is selected.

rooms[].namestringRequired

Public title or saved room/type name.

rooms[].descriptionstring | nullRequired

Saved public room/type description; may contain HTML. Sanitize before rendering. Null when absent; never property fallback.

rooms[].capacityinteger | nullRequired

Advertised maximum guest count, or null when unknown. Fresh availability still applies party restrictions. minimum: 1

rooms[].amenitiesArray<string>Required

Public room/type amenity names. Empty when absent.

rooms[].amenities[]stringRequired

One public amenity name.

rooms[].coverImageobject | nullRequired

First room/type gallery image or null; never a property-photo fallback.

rooms[].coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

rooms[].coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

rooms[].coverImage.altstringRequired

Image alternative text for accessible presentation.

rooms[].coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

rooms[].coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

rooms[].coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

rooms[].coverImage.variants[]objectRequired

Response structure: ImageVariant.

rooms[].coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

rooms[].coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

rooms[].coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

rooms[].coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

rooms[].coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

rooms[].coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

rooms[].coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

rooms[].galleryArray<object>Required

Ordered public room/type gallery, empty when absent. Excludes check-in galleries.

rooms[].gallery[]objectRequired

Response structure: PublicImage.

rooms[].gallery[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

rooms[].gallery[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

rooms[].gallery[].altstringRequired

Image alternative text for accessible presentation.

rooms[].gallery[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

rooms[].gallery[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

rooms[].gallery[].variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

rooms[].gallery[].variants[]objectRequired

Response structure: ImageVariant.

rooms[].gallery[].variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

rooms[].gallery[].variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

rooms[].gallery[].variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

rooms[].gallery[].variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

rooms[].gallery[].groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

rooms[].gallery[].group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

rooms[].gallery[].group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

rooms[].galleryGroupsArray<object>Required

Ordered photo groups referencing gallery image IDs.

rooms[].galleryGroups[]objectRequired

Response structure: GalleryGroup.

rooms[].galleryGroups[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

rooms[].galleryGroups[].titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

rooms[].galleryGroups[].imageIdsArray<string>Required

IDs of gallery images in this group, in display order. minItems: 1

rooms[].galleryGroups[].imageIds[]stringRequired

One value in the ordered collection.

metaobjectRequired

Pagination for this room collection; follow nextPage until null.

meta.pageintegerRequired

Requested page, starting at 1. minimum: 1

meta.nextPageinteger | nullRequired

Next page number, or null when all rooms have been returned. minimum: 1

Error responses

401
Missing or invalid authentication.
403
Wrong credential scope, inactive affiliate or denied property access.
404
Direct listing is missing, blacklisted, inactive or has the wrong listing type.
422
Invalid query/body. See error and details[].field/message.
429
Rate limited; wait for Retry-After before retrying.
503
Provider unavailable or timed out. This is not sold-out inventory.

Behavior & constraints

  • Affiliate API key or verified active affiliate session; the same approval, suspension, blacklist and active-inventory checks as individual room detail apply. Rental parents return 404.
  • Twelve rooms per page in stable ID order. Follow meta.nextPage until null. No dates, prices, availability or booking links; occupied rooms remain visible. No physical pooled members or private guest data.
  • Private and CDN no-store. Shared one-request-per-account-per-second budget; honor Retry-After on 429. Fifteen-second deadline. A failed page returns 503 with complete:false, never empty success. Retry that page.
  • Each rooms[] object uses the individual room-detail schema. See /hotel-room-details.md.
Request
cURL
curl --get --fail-with-body 'https://api-preview.wikiup.app/api/travel/listings/hotel%3Aproperty_example/rooms' \
  -H 'Authorization: Bearer <affiliate-api-key>' --data-urlencode 'page=1'
Response · 200
JSON
{
  "rooms": [
    {
      "id": "room_example",
      "listingId": "hotel:property_example",
      "propertyId": "property_example",
      "roomId": "room_example",
      "roomTypeId": null,
      "name": "Garden King",
      "description": "<p>A king room with a private terrace.</p>",
      "capacity": 2,
      "amenities": [
        "Wi-Fi",
        "Private terrace"
      ],
      "coverImage": {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      },
      "gallery": [
        {
          "id": "photo_example",
          "url": "https://images.example.com/hotel/original.jpg",
          "alt": "Example hotel courtyard",
          "width": 1600,
          "height": 900,
          "variants": [
            {
              "url": "https://images.example.com/hotel/640.webp",
              "width": 640,
              "height": 360,
              "format": "webp"
            }
          ],
          "group": {
            "id": "exterior",
            "title": "Exterior"
          }
        }
      ],
      "galleryGroups": [
        {
          "id": "exterior",
          "title": "Exterior",
          "imageIds": [
            "photo_example"
          ]
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "nextPage": null
  }
}
Response JSON schema
Validation error · HTTP 422
Validation error
JSON
{
  "error": "Invalid search criteria.",
  "details": [
    {
      "field": "checkOut",
      "message": "Check-out must follow check-in."
    }
  ]
}
Provider unavailable · HTTP 503
Provider unavailable
JSON
{
  "error": "Travel service temporarily unavailable.",
  "complete": false
}

Synthetic successful response. Photo URLs, IDs and booking tokens are examples, not live inventory. Ratings and address/contact additions await deployment; see their rollout notes. Required fields inside optional objects apply only when that object is present.

Read public content for an exact hotel room or pooled room type before booking.

Path parameters

listingIdstringRequired

Opaque parent hotel listing ID returned by Wikiup.

roomIdstringRequired

Exact options[].id from parent availability; named room or pooled room type.

Response fields

roomobjectRequired

Date-free public content for one eligible hotel option. Not an availability quote or a reservation.

room.idstringRequired

Opaque option ID, identical to the parent availability option id. Encode once per path segment.

room.listingIdstringRequired

Parent hotel listing ID; inns use hotel booking identity too.

room.propertyIdstringRequired

Stable property ID.

room.roomIdstring | nullRequired

Named room ID, or null for pooled room types.

room.roomTypeIdstring | nullRequired

Pooled room type ID, or null for named rooms. No physical member is selected.

room.namestringRequired

Public title or saved room/type name.

room.descriptionstring | nullRequired

Saved public room/type description; may contain HTML. Sanitize before rendering. Null when absent; never property fallback.

room.capacityinteger | nullRequired

Advertised maximum guest count, or null when unknown. Fresh availability still applies party restrictions. minimum: 1

room.amenitiesArray<string>Required

Public room/type amenity names. Empty when absent.

room.amenities[]stringRequired

One public amenity name.

room.coverImageobject | nullRequired

First room/type gallery image or null; never a property-photo fallback.

room.coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

room.coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

room.coverImage.altstringRequired

Image alternative text for accessible presentation.

room.coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

room.coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

room.coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

room.coverImage.variants[]objectRequired

Response structure: ImageVariant.

room.coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

room.coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

room.coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

room.coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

room.coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

room.coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

room.coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

room.galleryArray<object>Required

Ordered public room/type gallery, empty when absent. Excludes check-in galleries.

room.gallery[]objectRequired

Response structure: PublicImage.

room.gallery[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

room.gallery[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

room.gallery[].altstringRequired

Image alternative text for accessible presentation.

room.gallery[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

room.gallery[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

room.gallery[].variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

room.gallery[].variants[]objectRequired

Response structure: ImageVariant.

room.gallery[].variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

room.gallery[].variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

room.gallery[].variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

room.gallery[].variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

room.gallery[].groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

room.gallery[].group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

room.gallery[].group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

room.galleryGroupsArray<object>Required

Ordered photo groups referencing gallery image IDs.

room.galleryGroups[]objectRequired

Response structure: GalleryGroup.

room.galleryGroups[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

room.galleryGroups[].titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

room.galleryGroups[].imageIdsArray<string>Required

IDs of gallery images in this group, in display order. minItems: 1

room.galleryGroups[].imageIds[]stringRequired

One value in the ordered collection.

Error responses

401
Missing or invalid authentication.
403
Wrong credential scope, inactive affiliate or denied property access.
404
Direct listing is missing, blacklisted, inactive or has the wrong listing type.
422
Invalid query/body. See error and details[].field/message.
429
Rate limited; wait for Retry-After before retrying.
503
Provider unavailable or timed out. This is not sold-out inventory.

Behavior & constraints

  • Affiliate key or verified active affiliate session. Approval and no suspension are required for the authenticated affiliate. Encode each opaque ID once per path segment. The option must belong to this hotel listing; inns use hotel listing identity. No dates, party or other query parameters are accepted.
  • Eligibility and affiliate blacklist apply on every request. Missing, inactive, wrong-parent and blacklisted options return 404. Missing credentials return 401; disallowed credentials 403; malformed IDs or query 422.
  • No-store; one request per affiliate account per second, Retry-After on 429. Content loading has a 15-second deadline; provider errors return 503 with complete false, never an empty successful option.
  • Only the room/type’s public content is returned. Missing fields are null or empty; property photos and private check-in material are not substituted. No prices or booking URLs.
  • Refresh parent listing availability with dates and party; match options[].id exactly and use that option’s bookingUrl unchanged. A sold-out option remains readable here. See /hotel-room-details.md.
Request
cURL
curl 'https://api-preview.wikiup.app/api/travel/listings/hotel%3Aproperty_example/rooms/room_example' \
  -H 'Authorization: Bearer <affiliate-api-key>'
Response · 200
JSON
{
  "room": {
    "id": "room_example",
    "listingId": "hotel:property_example",
    "propertyId": "property_example",
    "roomId": "room_example",
    "roomTypeId": null,
    "name": "Garden King",
    "description": "<p>A king room with a private terrace.</p>",
    "capacity": 2,
    "amenities": [
      "Wi-Fi",
      "Private terrace"
    ],
    "coverImage": {
      "id": "photo_example",
      "url": "https://images.example.com/hotel/original.jpg",
      "alt": "Example hotel courtyard",
      "width": 1600,
      "height": 900,
      "variants": [
        {
          "url": "https://images.example.com/hotel/640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ],
      "group": {
        "id": "exterior",
        "title": "Exterior"
      }
    },
    "gallery": [
      {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      }
    ],
    "galleryGroups": [
      {
        "id": "exterior",
        "title": "Exterior",
        "imageIds": [
          "photo_example"
        ]
      }
    ]
  }
}
Response JSON schema
Pooled room type with no saved photos
Pooled room type with no saved photos
JSON
{
  "room": {
    "id": "room-type:king_type",
    "listingId": "hotel:property_example",
    "propertyId": "property_example",
    "roomId": null,
    "roomTypeId": "king_type",
    "name": "King Room",
    "description": null,
    "capacity": 2,
    "amenities": [],
    "coverImage": null,
    "gallery": [],
    "galleryGroups": []
  }
}
Validation error · HTTP 422
Validation error
JSON
{
  "error": "Invalid search criteria.",
  "details": [
    {
      "field": "checkOut",
      "message": "Check-out must follow check-in."
    }
  ]
}
Provider unavailable · HTTP 503
Provider unavailable
JSON
{
  "error": "Travel service temporarily unavailable.",
  "complete": false
}

Synthetic successful response. Photo URLs, IDs and booking tokens are examples, not live inventory. Ratings and address/contact additions await deployment; see their rollout notes. Required fields inside optional objects apply only when that object is present.

Find property map candidates from its address during owner setup.

Body fields

addressobjectRequired

Complete property address.

positionobjectOptional

Optional owner-adjusted latitude/longitude. Omit for provider lookup; null is rejected. Signs the position without a provider request or consuming provider lookup budget.

propertyIdstringOptional

Omit only for new-property setup.

Behavior & constraints

  • User session required; API keys are not accepted. For an existing property, send propertyId and owner permission is required. One lookup per account per ten seconds, six-second provider timeout.
  • Send address with line1, optional line2, city, state, postalCode and country. Returns candidates with formattedAddress, latitude, longitude and a signed confirmation receipt for an exact rooftop match valid for 30 minutes. Does not save or publish anything. No town-center fallback.
  • See /listing-locations.md. Server-side GEOCODIO_API_KEY required; missing configuration and provider failures return explicit 503.
Request
cURL
curl -X POST 'https://api-preview.wikiup.app/api/properties/location-lookup' \
  -H 'Authorization: Bearer <user-session>'
Example response
JSON
{
  "status": "no_match",
  "candidates": []
}

Read a property’s public map disclosure.

Behavior & constraints

  • Property owner only; affiliate and travel keys are denied. Private, no-store. PUT accepts status published with confirmation from address lookup, or status withheld/missing. No arbitrary coordinates.
  • Confirmation is bound to the owner, property and current address. Changing the saved address clears the old published pin. Creation and property update also accept publicLocationSelection in the property payload. See /listing-locations.md.
Request
cURL
curl -X GET 'https://api-preview.wikiup.app/api/properties/PROPERTY_ID/public-location' \
  -H 'Authorization: Bearer <owner-session>'
Example response
JSON
{
  "mapLocation": null,
  "timeZone": "America/Los_Angeles"
}

Confirm or withhold a property’s public map location.

Behavior & constraints

  • Property owner only; affiliate and travel keys are denied. Private, no-store. PUT accepts status published with confirmation from address lookup, or status withheld/missing. No arbitrary coordinates.
  • Confirmation is bound to the owner, property and current address. Changing the saved address clears the old published pin. Creation and property update also accept publicLocationSelection in the property payload. See /listing-locations.md.
Request
cURL
curl -X PUT 'https://api-preview.wikiup.app/api/properties/PROPERTY_ID/public-location' \
  -H 'Authorization: Bearer <owner-session>'
Example response
JSON
{
  "mapLocation": null,
  "timeZone": "America/Los_Angeles"
}

Browse eligible area listings without checking dates, prices or reservations.

Query parameters

destinationstringOptional

Optional destination, parent region or county ID. Omit to browse all approved properties, including those with unknown geography. Empty is invalid.

pageintegerOptional

One-based property page, 1–1000; default 1.

pageSizeintegerOptional

Properties per page, 1–12; default 12. Rental properties may produce multiple listing cards.

includeImagesbooleanOptional

Default false; true loads prepared cover thumbnail metadata.

fetchstringOptional

Optional ratings expansion. Unknown, empty or repeated fetch values return 422.

Allowed valuesratings

Response fields

contractVersion2Required

Response contract version; currently 2.

queryobjectRequired

Validated search inputs and defaults used to produce this response.

query.destinationstringOptional

Optional geographic filter. Omitted when browsing all approved properties; otherwise a canonical destination, parent-region or county ID.

query.pageintegerRequired

One-based property page number. minimum: 0

query.pageSizeintegerRequired

Property count per page, not listing-card count; rental properties can produce multiple cards. minimum: 0

query.includeImagesbooleanRequired

Whether prepared cover metadata was requested; defaults to false.

query.fetch"ratings"Optional

Present only when the request opted into affiliate ratings.

listingsArray<object>Required

Public display listings for this response. Catalog listings are unchecked; priced listings represent matching availability.

listings[]objectRequired

Response structure: CatalogListing.

listings[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

listings[].propertyIdstringRequired

Raw Wikiup property identifier.

listings[].namestringRequired

Public display name.

listings[].propertyNamestringRequired

Public property listing title, falling back to property name.

listings[].locationstringRequired

Saved city/state display label, not a street address or map position.

listings[].destinationstringRequired

Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography.

listings[].type"hotel" | "vacation_rental"Required

Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit.

listings[].maxGuestsinteger | nullOptional

Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards.

listings[].availabilityStatus"unchecked"Required

Unchecked means no date/occupancy/pricing calculation has run for this catalog card.

listings[].coverImageobject | nullRequired

Public cover image metadata, or null when absent.

listings[].coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listings[].coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listings[].coverImage.altstringRequired

Image alternative text for accessible presentation.

listings[].coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listings[].coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listings[].coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

listings[].coverImage.variants[]objectRequired

Response structure: ImageVariant.

listings[].coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listings[].coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listings[].coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listings[].coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

listings[].coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

listings[].coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listings[].coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

listings[].imageStatus"deferred" | "none" | "pending" | "ready"Required

deferred: not requested; none: no photo; ready: metadata available; pending: source exists but metadata is unavailable.

listings[].mapLocationobject | nullRequired

Exact approved public coordinate pair, or null. Never use town-center guesses.

listings[].mapLocation.latitudenumberRequired

Exact approved public latitude in decimal degrees. minimum: -90; maximum: 90

listings[].mapLocation.longitudenumberRequired

Exact approved public longitude in decimal degrees. minimum: -180; maximum: 180

listings[].timeZonestring | nullRequired

Validated property IANA time zone. Use for local timestamps; null means unknown.

listings[].stayType"hotel" | "inn" | "bed_and_breakfast" | "resort" | "vacation_rental" | nullRequired

Owner-supplied subtype compatible with the existing broad type; null when unknown or inconsistent. Does not select the booking flow.

listings[].descriptionstring | nullRequired

Plain text from this exact listing description. HTML and common booking/placeholder prompts removed. Unknown is null. maxLength: 240

listings[].tagLinestring | nullRequired

Explicit owner-provided hotel facts or beds/baths from the exact rental unit or room-type content. Not live available inventory. Unknown is null. Limited to 100 Unicode characters including an ellipsis when shortened. maxLength: 100

listings[].ratingsobjectOptional

Present only with fetch=ratings; omitted otherwise. Unset values are null.

listings[].ratings.starRatingnumber | nullRequired

Requesting affiliate’s editorial star ratings; 1–5 in half-star increments. Not guest reviews. minimum: 1; maximum: 5; multipleOf: 0.5

listings[].ratings.priceTierinteger | nullRequired

Requesting affiliate’s price tier, 1–5. Not a price quote. minimum: 1; maximum: 5

failuresArray<object>Required

Provider failures; never interpret these as sold-out inventory.

failures[]objectRequired

One record in failures.

failures[].propertyIdstringRequired

Raw Wikiup property identifier.

failures[].code"timeout" | "provider_unavailable"Required

Machine-readable provider failure code.

failures[].retryabletrueRequired

True when the failed provider request may be retried.

metaobjectRequired

Pagination and completion metadata.

meta.pageintegerRequired

One-based property page number. minimum: 0

meta.pageSizeintegerRequired

Property count per page, not listing-card count; rental properties can produce multiple cards. minimum: 0

meta.matchedPropertiesintegerRequired

Eligible properties matching geography before this page is evaluated. minimum: 0

meta.checkedPropertiesintegerRequired

Properties successfully processed in this response. minimum: 0

meta.withdrawnPropertiesintegerRequired

Properties removed because eligibility changed while processing. minimum: 0

meta.nextPageinteger | nullRequired

Next property page number, or null at the end.

meta.paginationBasis"affiliate_properties"Required

Pagination counts affiliate properties or owner-published properties according to key scope.

meta.partialbooleanRequired

True when provider failures make the current response incomplete.

meta.pageCompletebooleanRequired

True when this page has no provider failures; does not imply all pages were fetched.

meta.completebooleanRequired

Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search.

meta.generatedAtstringRequired

Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date. format: date-time

Error responses

401
Missing or invalid authentication.
403
Wrong credential scope, inactive affiliate or denied property access.
404
Direct listing is missing, blacklisted, inactive or has the wrong listing type.
422
Invalid query/body. See error and details[].field/message.
429
Rate limited; wait for Retry-After before retrying.
503
Provider unavailable or timed out. This is not sold-out inventory.

Behavior & constraints

  • Affiliate key or verified active affiliate session; only approved, unsuspended eligible properties for that affiliate, excluding its blacklist. No dates or property header. Catalog cards are unchecked, never evidence of availability. Nullable card metadata: stayType, description (plain text, max 240 characters) and tagLine (max 100 characters). Ratings are omitted by default. Add fetch=ratings to attach the authenticated affiliate’s nested ratings object; one bounded Onyx resolver query per page. See /affiliate-listing-ratings.md. Direct content retains its full description.
  • Default skips image storage; includeImages=true reads prepared cover thumbnails without downloading originals. No prices or booking URLs.
  • Each card includes mapLocation as an exact latitude/longitude pair or null, plus property timeZone. Plot non-null pairs only; no status/precision fields or approximate points. See /listing-locations.md.
  • Page 1–1000, pageSize 1–12 properties; a rental property can produce multiple cards. Follow meta.nextPage and failures. Three concurrent properties, 10-second deadline. See /affiliate-lazy-loading.md.
Request
cURL
curl 'https://api-preview.wikiup.app/api/travel/listings?destination=julian-ca&page=1&pageSize=12&includeImages=true&fetch=ratings' \
  -H 'Authorization: Bearer <affiliate-api-key>'
Response · 200
JSON
{
  "contractVersion": 2,
  "query": {
    "destination": "julian-ca",
    "page": 1,
    "pageSize": 12,
    "includeImages": true,
    "fetch": "ratings"
  },
  "listings": [
    {
      "id": "hotel:property_example",
      "type": "hotel",
      "propertyId": "property_example",
      "name": "Example Hotel",
      "propertyName": "Example Hotel",
      "location": "Julian, CA",
      "mapLocation": null,
      "timeZone": "America/Los_Angeles",
      "destination": "julian-ca",
      "stayType": "inn",
      "description": "A small inn with private rooms and a shared courtyard.",
      "tagLine": "Private rooms in Julian",
      "availabilityStatus": "unchecked",
      "coverImage": {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      },
      "imageStatus": "ready",
      "ratings": {
        "starRating": 4.5,
        "priceTier": 3
      }
    },
    {
      "id": "rental:rental_property:room:room_rental",
      "type": "vacation_rental",
      "propertyId": "rental_property",
      "name": "Example Cottage",
      "propertyName": "Example Cottages",
      "location": "Julian, CA",
      "mapLocation": null,
      "timeZone": "America/Los_Angeles",
      "destination": "julian-ca",
      "stayType": "vacation_rental",
      "description": "A small inn with private rooms and a shared courtyard.",
      "tagLine": "2 bedrooms, 1 bath",
      "availabilityStatus": "unchecked",
      "coverImage": {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      },
      "imageStatus": "ready",
      "ratings": {
        "starRating": 4.5,
        "priceTier": 3
      },
      "maxGuests": 4
    }
  ],
  "failures": [],
  "meta": {
    "page": 1,
    "pageSize": 12,
    "nextPage": null,
    "paginationBasis": "affiliate_properties",
    "matchedProperties": 2,
    "checkedProperties": 2,
    "withdrawnProperties": 0,
    "partial": false,
    "pageComplete": true,
    "complete": true,
    "generatedAt": "2027-01-10T09:00:00-08:00"
  }
}
Response JSON schema
Default lightweight request: images deferred, ratings omitted
Default lightweight request: images deferred, ratings omitted
JSON
{
  "contractVersion": 2,
  "query": {
    "destination": "julian-ca",
    "page": 1,
    "pageSize": 12,
    "includeImages": false
  },
  "listings": [
    {
      "id": "hotel:property_example",
      "type": "hotel",
      "propertyId": "property_example",
      "name": "Example Hotel",
      "propertyName": "Example Hotel",
      "location": "Julian, CA",
      "mapLocation": null,
      "timeZone": "America/Los_Angeles",
      "destination": "julian-ca",
      "stayType": "inn",
      "description": "A small inn with private rooms and a shared courtyard.",
      "tagLine": "Private rooms in Julian",
      "availabilityStatus": "unchecked",
      "coverImage": null,
      "imageStatus": "deferred"
    }
  ],
  "failures": [],
  "meta": {
    "page": 1,
    "pageSize": 12,
    "nextPage": null,
    "paginationBasis": "affiliate_properties",
    "matchedProperties": 1,
    "checkedProperties": 1,
    "withdrawnProperties": 0,
    "partial": false,
    "pageComplete": true,
    "complete": true,
    "generatedAt": "2027-01-10T09:00:00-08:00"
  }
}
Partial provider failure
Partial provider failure
JSON
{
  "contractVersion": 2,
  "query": {
    "destination": "julian-ca",
    "page": 1,
    "pageSize": 12,
    "includeImages": true,
    "fetch": "ratings"
  },
  "listings": [
    {
      "id": "hotel:property_example",
      "type": "hotel",
      "propertyId": "property_example",
      "name": "Example Hotel",
      "propertyName": "Example Hotel",
      "location": "Julian, CA",
      "mapLocation": null,
      "timeZone": "America/Los_Angeles",
      "destination": "julian-ca",
      "stayType": "inn",
      "description": "A small inn with private rooms and a shared courtyard.",
      "tagLine": "Private rooms in Julian",
      "availabilityStatus": "unchecked",
      "coverImage": {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      },
      "imageStatus": "ready",
      "ratings": {
        "starRating": 4.5,
        "priceTier": 3
      }
    }
  ],
  "failures": [
    {
      "propertyId": "rental_property",
      "code": "provider_unavailable",
      "retryable": true
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 12,
    "nextPage": null,
    "paginationBasis": "affiliate_properties",
    "matchedProperties": 2,
    "checkedProperties": 1,
    "withdrawnProperties": 0,
    "partial": true,
    "pageComplete": false,
    "complete": false,
    "generatedAt": "2027-01-10T09:00:00-08:00"
  }
}
Validation error · HTTP 422
Validation error
JSON
{
  "error": "Invalid search criteria.",
  "details": [
    {
      "field": "checkOut",
      "message": "Check-out must follow check-in."
    }
  ]
}
Provider unavailable · HTTP 503
Provider unavailable
JSON
{
  "error": "Travel service temporarily unavailable.",
  "complete": false
}

Synthetic successful response. Photo URLs, IDs and booking tokens are examples, not live inventory. Ratings and address/contact additions await deployment; see their rollout notes. Required fields inside optional objects apply only when that object is present.

Check fresh availability and prices for up to twelve visible listing IDs or properties.

Body fields

listingIdsstring[]Optional

Choose one array: 1–12 unique IDs.

propertyIdsstring[]Optional

Choose one array: 1–12 unique IDs.

checkInstringRequired

Arrival date in property-local YYYY-MM-DD. Stay must be 1–28 nights and within the supported two-year window.

checkOutstringRequired

Exclusive departure date in property-local YYYY-MM-DD; must follow checkIn.

adultsinteger | numeric stringOptional

Integer 1–20; default 2. Adults plus children must not exceed 20.

childreninteger | numeric stringOptional

Integer 0–19; default 0. Adults plus children must not exceed 20.

petsinteger | numeric stringOptional

Integer 0–10; default 0. The booking engine enforces each room’s pet policy.

Response fields

queryobjectRequired

Validated search inputs and defaults used to produce this response.

query.checkInstringRequired

Arrival calendar date in the property timezone, YYYY-MM-DD. format: date

query.checkOutstringRequired

Departure calendar date, YYYY-MM-DD; checkout is not an occupied night. format: date

query.adultsintegerRequired

Adult guest count; defaults to 2 in requests. minimum: 0

query.childrenintegerRequired

Child guest count; defaults to 0 in requests. minimum: 0

query.petsintegerRequired

Pet count; defaults to 0 in requests. minimum: 0

resultsArray<object>Required

Per-property or per-request results. Inspect individual outcomes rather than treating every HTTP 200 as complete.

results[]objectRequired

Response structure: BatchResult.

results[].requestIdstringOptional

Exact requested listing ID or raw property ID; use to merge results with the request.

results[].propertyIdstringOptional

Raw Wikiup property identifier.

results[].status"available" | "sold_out" | "not_found" | "error"Optional

Outcome discriminator; available and sold_out are successful checks, not_found is inaccessible inventory, error is a provider failure where supported.

results[].listingsArray<object>Optional

Public display listings for this response. Catalog listings are unchecked; priced listings represent matching availability.

results[].listings[]objectRequired

Response structure: BatchListing.

results[].listings[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].listings[].type"hotel" | "vacation_rental"Required

Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit.

results[].listings[].propertyIdstringRequired

Raw Wikiup property identifier.

results[].listings[].namestringRequired

Public display name.

results[].listings[].propertyNamestringRequired

Public property listing title, falling back to property name.

results[].listings[].locationstringRequired

Saved city/state display label, not a street address or map position.

results[].listings[].maxGuestsintegerOptional

Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards. minimum: 0

results[].listings[].availableRoomCountintegerOptional

Number of qualifying rooms across the hotel for these dates and party. minimum: 0

results[].listings[].currencystringRequired

Three-letter currency code. All amounts are in major currency units.

results[].listings[].nightlyRatenumber | nullRequired

Average accommodation rate per night for this requested stay, excluding taxes and fees. minimum: 0

results[].listings[].staySubtotalnumber | nullRequired

Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees. minimum: 0

results[].listings[].priceBasis"accommodation_subtotal"Required

Prices are accommodation subtotals, not final checkout totals.

results[].listings[].taxesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

results[].listings[].feesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

results[].listings[].finalTotalnullRequired

Determined at checkout. Null must not be displayed as zero.

results[].listings[].bookingUrlstringRequired

Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it. format: uri

results[].listings[].priceLabel"From" | "Stay"Required

From for the lowest qualifying hotel option; Stay for a rental.

results[].listings[].mapLocationobject | nullRequired

Exact approved public coordinate pair, or null. Never use town-center guesses.

results[].listings[].mapLocation.latitudenumberRequired

Exact approved public latitude in decimal degrees. minimum: -90; maximum: 90

results[].listings[].mapLocation.longitudenumberRequired

Exact approved public longitude in decimal degrees. minimum: -180; maximum: 180

results[].listings[].timeZonestring | nullRequired

Validated property IANA time zone. Use for local timestamps; null means unknown.

results[].optionsArray<object>Optional

Exact bookable room/rental options matching the dates and party.

results[].options[]objectRequired

Response structure: BatchOption.

results[].options[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].options[].roomIdstring | nullRequired

Physical room identifier; null for a pooled room-type option.

results[].options[].roomTypeIdstring | nullRequired

Room-type identifier for pooled inventory; null for a named room.

results[].options[].namestringRequired

Public display name.

results[].options[].capacityintegerRequired

Maximum supported guests for this exact bookable option. minimum: 0

results[].options[].availableCountintegerRequired

Number of physical units assignable throughout the entire requested stay; not a hold. minimum: 0

results[].options[].currencystringRequired

Three-letter currency code. All amounts are in major currency units.

results[].options[].nightlyRatenumberRequired

Average accommodation rate per night for this requested stay, excluding taxes and fees. minimum: 0

results[].options[].staySubtotalnumberRequired

Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees. minimum: 0

results[].options[].priceBasis"accommodation_subtotal"Required

Prices are accommodation subtotals, not final checkout totals.

results[].options[].taxesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

results[].options[].feesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

results[].options[].finalTotalnullRequired

Determined at checkout. Null must not be displayed as zero.

results[].options[].bookingUrlstringRequired

Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it. format: uri

results[].code"timeout" | "provider_unavailable"Optional

Machine-readable provider failure code.

results[].retryabletrueOptional

True when the failed provider request may be retried.

completebooleanRequired

Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search.

metaobjectRequired

Pagination and completion metadata.

meta.requestedintegerRequired

Number of requested listing/property targets. minimum: 0

meta.checkedPropertiesintegerRequired

Properties successfully processed in this response. minimum: 0

meta.failedPropertiesintegerRequired

Number of properties with provider failures; inaccessible properties are not counted. minimum: 0

meta.generatedAtstringRequired

Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date. format: date-time

Error responses

401
Missing or invalid authentication.
403
Wrong credential scope, inactive affiliate or denied property access.
404
Direct listing is missing, blacklisted, inactive or has the wrong listing type.
422
Invalid query/body. See error and details[].field/message.
429
Rate limited; wait for Retry-After before retrying.
503
Provider unavailable or timed out. This is not sold-out inventory.

Behavior & constraints

  • Affiliate key only. Send either listingIds or propertyIds; dates and party counts match existing availability. Read-only POST, 8 KiB body maximum.
  • One booking-engine calculation per distinct property, three concurrently, 15-second deadline. Per-item available, sold_out, not_found or error. A 200 response can be incomplete; inspect complete and each status. Images are omitted; merge pricing into catalog cards by ID.
  • No-store. Existing account-wide one request/second admission; honor Retry-After. Preserve signed bookingUrl. See /affiliate-lazy-loading.md and /travel-listings.schema.json.
Request
cURL
curl -X POST 'https://api-preview.wikiup.app/api/travel/listings/availability' \
  -H 'Authorization: Bearer <affiliate-api-key>' \
  -H 'Content-Type: application/json' --data '{"listingIds":["hotel:property_example"],"checkIn":"2027-02-09","checkOut":"2027-02-12","adults":2,"children":0,"pets":0}'
Response · 200
JSON
{
  "query": {
    "checkIn": "2027-02-09",
    "checkOut": "2027-02-12",
    "adults": 2,
    "children": 0,
    "pets": 0
  },
  "results": [
    {
      "requestId": "hotel:property_example",
      "propertyId": "property_example",
      "status": "available",
      "listings": [
        {
          "id": "hotel:property_example",
          "type": "hotel",
          "propertyId": "property_example",
          "name": "Example Hotel",
          "propertyName": "Example Hotel",
          "location": "Julian, CA",
          "mapLocation": null,
          "timeZone": "America/Los_Angeles",
          "currency": "USD",
          "nightlyRate": 200,
          "staySubtotal": 600,
          "priceBasis": "accommodation_subtotal",
          "taxes": null,
          "fees": null,
          "finalTotal": null,
          "priceLabel": "From",
          "availableRoomCount": 1,
          "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN"
        }
      ],
      "options": [
        {
          "id": "room_example",
          "roomId": "room_example",
          "roomTypeId": null,
          "name": "Garden King",
          "capacity": 2,
          "availableCount": 1,
          "currency": "USD",
          "nightlyRate": 200,
          "staySubtotal": 600,
          "priceBasis": "accommodation_subtotal",
          "taxes": null,
          "fees": null,
          "finalTotal": null,
          "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&roomId=room_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN"
        }
      ]
    }
  ],
  "complete": true,
  "meta": {
    "requested": 1,
    "checkedProperties": 1,
    "failedProperties": 0,
    "generatedAt": "2027-01-10T09:00:00-08:00"
  }
}
Response JSON schema
Mixed batch: available, unavailable and provider failure
Mixed batch: available, unavailable and provider failure
JSON
{
  "query": {
    "checkIn": "2027-02-09",
    "checkOut": "2027-02-12",
    "adults": 2,
    "children": 0,
    "pets": 0
  },
  "results": [
    {
      "requestId": "hotel:property_example",
      "propertyId": "property_example",
      "status": "available",
      "listings": [
        {
          "id": "hotel:property_example",
          "type": "hotel",
          "propertyId": "property_example",
          "name": "Example Hotel",
          "propertyName": "Example Hotel",
          "location": "Julian, CA",
          "mapLocation": null,
          "timeZone": "America/Los_Angeles",
          "currency": "USD",
          "nightlyRate": 200,
          "staySubtotal": 600,
          "priceBasis": "accommodation_subtotal",
          "taxes": null,
          "fees": null,
          "finalTotal": null,
          "priceLabel": "From",
          "availableRoomCount": 1,
          "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN"
        }
      ],
      "options": [
        {
          "id": "room_example",
          "roomId": "room_example",
          "roomTypeId": null,
          "name": "Garden King",
          "capacity": 2,
          "availableCount": 1,
          "currency": "USD",
          "nightlyRate": 200,
          "staySubtotal": 600,
          "priceBasis": "accommodation_subtotal",
          "taxes": null,
          "fees": null,
          "finalTotal": null,
          "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&roomId=room_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN"
        }
      ]
    },
    {
      "requestId": "hotel:sold_out",
      "propertyId": "sold_out",
      "status": "sold_out",
      "listings": [],
      "options": []
    },
    {
      "requestId": "hotel:withdrawn",
      "propertyId": "withdrawn",
      "status": "not_found"
    },
    {
      "requestId": "hotel:retry",
      "propertyId": "retry",
      "status": "error",
      "code": "timeout",
      "retryable": true
    }
  ],
  "complete": false,
  "meta": {
    "requested": 4,
    "checkedProperties": 2,
    "failedProperties": 1,
    "generatedAt": "2027-01-10T09:00:00-08:00"
  }
}
Validation error · HTTP 422
Validation error
JSON
{
  "error": "Invalid search criteria.",
  "details": [
    {
      "field": "checkOut",
      "message": "Check-out must follow check-in."
    }
  ]
}
Provider unavailable · HTTP 503
Provider unavailable
JSON
{
  "error": "Travel service temporarily unavailable.",
  "complete": false
}

Synthetic successful response. Photo URLs, IDs and booking tokens are examples, not live inventory. Ratings and address/contact additions await deployment; see their rollout notes. Required fields inside optional objects apply only when that object is present.

Read public listing content, cover photograph and ordered gallery.

Path parameters

listingIdstringRequired

Stable listing ID returned by search; preserve unchanged.

Query parameters

fetchstringOptional

Optional affiliate ratings expansion.

Allowed valuesratings

Response fields

listingobjectRequired

Public detail for the requested stable listing ID.

listing.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listing.type"hotel" | "vacation_rental"Required

Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit.

listing.propertyIdstringRequired

Raw Wikiup property identifier.

listing.namestringRequired

Public display name.

listing.propertyNamestringRequired

Public property listing title, falling back to property name.

listing.locationstringRequired

Saved city/state display label, not a street address or map position.

listing.destinationstring | nullRequired

Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography.

listing.descriptionstring | nullRequired

Full saved description for the exact listing; may contain HTML. Null when unknown. The catalog uses a bounded plain-text excerpt instead.

listing.amenitiesArray<string>Required

Public amenity names for this exact listing. Empty means none supplied; do not invent amenities.

listing.amenities[]stringRequired

One value in the ordered collection.

listing.maxGuestsinteger | nullOptional

Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards. minimum: 0

listing.coverImageobject | nullRequired

Public cover image metadata, or null when absent.

listing.coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listing.coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listing.coverImage.altstringRequired

Image alternative text for accessible presentation.

listing.coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listing.coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listing.coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

listing.coverImage.variants[]objectRequired

Response structure: ImageVariant.

listing.coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listing.coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listing.coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listing.coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

listing.coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

listing.coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listing.coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

listing.galleryArray<object>Required

Ordered public listing photos, including thumbnails and group labels.

listing.gallery[]objectRequired

Response structure: PublicImage.

listing.gallery[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

listing.gallery[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listing.gallery[].altstringRequired

Image alternative text for accessible presentation.

listing.gallery[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listing.gallery[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listing.gallery[].variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

listing.gallery[].variants[]objectRequired

Response structure: ImageVariant.

listing.gallery[].variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listing.gallery[].variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listing.gallery[].variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listing.gallery[].variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

listing.gallery[].groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

listing.gallery[].group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

listing.gallery[].group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

listing.galleryGroupsArray<object>Required

Ordered photo groups referencing gallery image IDs.

listing.galleryGroups[]objectRequired

Response structure: GalleryGroup.

listing.galleryGroups[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

listing.galleryGroups[].titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

listing.galleryGroups[].imageIdsArray<string>Required

IDs of gallery images in this group, in display order. minItems: 1

listing.galleryGroups[].imageIds[]stringRequired

One value in the ordered collection.

listing.mapLocationobject | nullRequired

Exact approved public coordinate pair, or null. Never use town-center guesses.

listing.mapLocation.latitudenumberRequired

Exact approved public latitude in decimal degrees. minimum: -90; maximum: 90

listing.mapLocation.longitudenumberRequired

Exact approved public longitude in decimal degrees. minimum: -180; maximum: 180

listing.timeZonestring | nullRequired

Validated property IANA time zone. Use for local timestamps; null means unknown.

listing.stayType"hotel" | "inn" | "bed_and_breakfast" | "resort" | "vacation_rental" | nullRequired

Owner-supplied subtype compatible with the existing broad type; null when unknown or inconsistent. Does not select the booking flow.

listing.tagLinestring | nullRequired

Explicit owner-provided hotel facts or beds/baths from the exact rental unit or room-type content. Not live available inventory. Unknown is null. Limited to 100 Unicode characters including an ellipsis when shortened. maxLength: 100

listing.ratingsobjectOptional

Present only with fetch=ratings; omitted otherwise. Unset values are null.

listing.ratings.starRatingnumber | nullRequired

Requesting affiliate’s editorial star ratings; 1–5 in half-star increments. Not guest reviews. minimum: 1; maximum: 5; multipleOf: 0.5

listing.ratings.priceTierinteger | nullRequired

Requesting affiliate’s price tier, 1–5. Not a price quote. minimum: 1; maximum: 5

listing.addressobject | nullRequired

Saved property address, not owner-account address. Null when all address fields are empty. Detail only.

listing.address.line1string | nullRequired

Saved property street address.

listing.address.line2string | nullRequired

Optional additional property address line; null when empty.

listing.address.citystring | nullRequired

Saved property city.

listing.address.statestring | nullRequired

Saved property state/province.

listing.address.postalCodestring | nullRequired

Saved property postal/ZIP code; a string to preserve leading zeros.

listing.address.countrystring | nullRequired

Saved country value; may be a country name or code. Do not assume ISO format.

listing.contactobjectRequired

Property business contact details. No account records or credentials are included.

listing.contact.phonestring | nullRequired

Property business phone text, not an owner-account phone; null when absent.

listing.contact.emailstring | nullRequired

Property business email, not an owner-account email; null when absent.

listing.contact.websiteUrlstring | nullRequired

Saved HTTP(S) property website, or null for absent/invalid/credential-bearing values. Not an affiliate-attributed checkout URL.

Error responses

401
Missing or invalid authentication.
403
Wrong credential scope, inactive affiliate or denied property access.
404
Direct listing is missing, blacklisted, inactive or has the wrong listing type.
422
Invalid query/body. See error and details[].field/message.
429
Rate limited; wait for Retry-After before retrying.
503
Provider unavailable or timed out. This is not sold-out inventory.

Behavior & constraints

  • Affiliate API key or verified active affiliate session required. Approval, suspension, eligibility and blacklist are checked on every request. One request per account per second; honor Retry-After. Never cache these JSON responses.
  • Content excludes prices and booking capabilities. Availability returns exact bookable options, fresh prices and checkout links. API-key links include signed commission attribution; session preview links do not. Sold out is 200 with status sold_out; provider failure is 503, complete false.
  • Complete schemas and consumer migration: /travel-listings.schema.json and /travel-listings.md.
Request
cURL
curl 'https://api-preview.wikiup.app/api/travel/listings/hotel%3Aproperty_example?fetch=ratings' \
  -H 'Authorization: Bearer <affiliate-api-key>'
Response · 200
JSON
{
  "listing": {
    "id": "hotel:property_example",
    "type": "hotel",
    "propertyId": "property_example",
    "name": "Example Hotel",
    "propertyName": "Example Hotel",
    "location": "Julian, CA",
    "mapLocation": null,
    "timeZone": "America/Los_Angeles",
    "destination": "julian-ca",
    "stayType": "inn",
    "description": "<p>A small inn with private rooms and a shared courtyard.</p>",
    "tagLine": "Private rooms in Julian",
    "ratings": {
      "starRating": 4.5,
      "priceTier": 3
    },
    "address": {
      "line1": "100 Example Lane",
      "line2": null,
      "city": "Julian",
      "state": "CA",
      "postalCode": "92036",
      "country": "United States"
    },
    "contact": {
      "phone": "+1 202-555-0142",
      "email": "hello@example.com",
      "websiteUrl": "https://example.com/"
    },
    "amenities": [],
    "coverImage": {
      "id": "photo_example",
      "url": "https://images.example.com/hotel/original.jpg",
      "alt": "Example hotel courtyard",
      "width": 1600,
      "height": 900,
      "variants": [
        {
          "url": "https://images.example.com/hotel/640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ],
      "group": {
        "id": "exterior",
        "title": "Exterior"
      }
    },
    "gallery": [
      {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      }
    ],
    "galleryGroups": [
      {
        "id": "exterior",
        "title": "Exterior",
        "imageIds": [
          "photo_example"
        ]
      }
    ]
  }
}
Response JSON schema
Rental detail with amenities and unknown contact details
Rental detail with amenities and unknown contact details
JSON
{
  "listing": {
    "id": "rental:rental_property:room:room_rental",
    "type": "vacation_rental",
    "propertyId": "rental_property",
    "name": "Example Cottage",
    "propertyName": "Example Cottages",
    "location": "Julian, CA",
    "mapLocation": null,
    "timeZone": "America/Los_Angeles",
    "destination": "julian-ca",
    "stayType": "vacation_rental",
    "description": "<p>A small inn with private rooms and a shared courtyard.</p>",
    "tagLine": "2 bedrooms, 1 bath",
    "ratings": {
      "starRating": null,
      "priceTier": null
    },
    "address": null,
    "contact": {
      "phone": null,
      "email": null,
      "websiteUrl": null
    },
    "amenities": [
      "Wi-Fi",
      "Kitchen"
    ],
    "coverImage": {
      "id": "photo_example",
      "url": "https://images.example.com/hotel/original.jpg",
      "alt": "Example hotel courtyard",
      "width": 1600,
      "height": 900,
      "variants": [
        {
          "url": "https://images.example.com/hotel/640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ],
      "group": {
        "id": "exterior",
        "title": "Exterior"
      }
    },
    "gallery": [
      {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      }
    ],
    "galleryGroups": [
      {
        "id": "exterior",
        "title": "Exterior",
        "imageIds": [
          "photo_example"
        ]
      }
    ],
    "maxGuests": 4
  }
}
Validation error · HTTP 422
Validation error
JSON
{
  "error": "Invalid search criteria.",
  "details": [
    {
      "field": "checkOut",
      "message": "Check-out must follow check-in."
    }
  ]
}
Provider unavailable · HTTP 503
Provider unavailable
JSON
{
  "error": "Travel service temporarily unavailable.",
  "complete": false
}

Synthetic successful response. Photo URLs, IDs and booking tokens are examples, not live inventory. Ratings and address/contact additions await deployment; see their rollout notes. Required fields inside optional objects apply only when that object is present.

Read fresh room or rental availability for one stable public listing ID.

Path parameters

listingIdstringRequired

Stable listing ID returned by search; preserve unchanged.

Query parameters

checkInstringRequired

Arrival date in property-local YYYY-MM-DD. Stay must be 1–28 nights and within the supported two-year window.

checkOutstringRequired

Exclusive departure date in property-local YYYY-MM-DD; must follow checkIn.

adultsintegerOptional

Integer 1–20; default 2. Adults plus children must not exceed 20.

childrenintegerOptional

Integer 0–19; default 0. Adults plus children must not exceed 20.

petsintegerOptional

Integer 0–10; default 0. The booking engine enforces each room’s pet policy.

Response fields

listingIdstringRequired

Stable hotel or rental listing ID from the catalog.

status"available" | "sold_out"Required

Outcome discriminator; available and sold_out are successful checks, not_found is inaccessible inventory, error is a provider failure where supported.

optionsArray<object>Required

Exact bookable room/rental options matching the dates and party.

options[]objectRequired

Response structure: Option.

options[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

options[].roomIdstring | nullRequired

Physical room identifier; null for a pooled room-type option.

options[].roomTypeIdstring | nullRequired

Room-type identifier for pooled inventory; null for a named room.

options[].namestringRequired

Public display name.

options[].coverImageobject | nullOptional

Public cover image metadata, or null when absent.

options[].coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

options[].coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

options[].coverImage.altstringRequired

Image alternative text for accessible presentation.

options[].coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

options[].coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

options[].coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

options[].coverImage.variants[]objectRequired

Response structure: ImageVariant.

options[].coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

options[].coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

options[].coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

options[].coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

options[].coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

options[].coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

options[].coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

options[].photosArray<string>Required

Public photo URLs for this inventory; may be empty.

options[].photos[]stringRequired

One value in the ordered collection. format: uri

options[].capacityintegerRequired

Maximum supported guests for this exact bookable option. minimum: 0

options[].availableCountintegerRequired

Number of physical units assignable throughout the entire requested stay; not a hold. minimum: 0

options[].currencystringRequired

Three-letter currency code. All amounts are in major currency units.

options[].nightlyRatenumberRequired

Average accommodation rate per night for this requested stay, excluding taxes and fees. minimum: 0

options[].staySubtotalnumberRequired

Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees. minimum: 0

options[].priceBasis"accommodation_subtotal"Required

Prices are accommodation subtotals, not final checkout totals.

options[].taxesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

options[].feesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

options[].finalTotalnullRequired

Determined at checkout. Null must not be displayed as zero.

options[].bookingUrlstringRequired

Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it. format: uri

options[].imagestring | nullRequired

Cover photo URL, or null if no public photo exists.

options[].imageVariantsArray<object>Required

Prepared responsive sizes for the cover image.

options[].imageVariants[]objectRequired

Response structure: ImageVariant.

options[].imageVariants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

options[].imageVariants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

options[].imageVariants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

options[].imageVariants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

options[].maxGuestsintegerRequired

Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards. minimum: 0

completetrueRequired

Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search.

generatedAtstringRequired

Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date. format: date-time

Error responses

401
Missing or invalid authentication.
403
Wrong credential scope, inactive affiliate or denied property access.
404
Direct listing is missing, blacklisted, inactive or has the wrong listing type.
422
Invalid query/body. See error and details[].field/message.
429
Rate limited; wait for Retry-After before retrying.
503
Provider unavailable or timed out. This is not sold-out inventory.

Behavior & constraints

  • Affiliate API key or verified active affiliate session required. Approval, suspension, eligibility and blacklist are checked on every request. One request per account per second; honor Retry-After. Never cache these JSON responses.
  • Content excludes prices and booking capabilities. Availability returns exact bookable options, fresh prices and checkout links. API-key links include signed commission attribution; session preview links do not. Sold out is 200 with status sold_out; provider failure is 503, complete false.
  • Complete schemas and consumer migration: /travel-listings.schema.json and /travel-listings.md.
Request
cURL
curl 'https://api-preview.wikiup.app/api/travel/listings/hotel%3Aproperty_example/availability?checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0' \
  -H 'Authorization: Bearer <affiliate-api-key>'
Response · 200
JSON
{
  "listingId": "hotel:property_example",
  "status": "available",
  "options": [
    {
      "id": "room_example",
      "roomId": "room_example",
      "roomTypeId": null,
      "name": "Garden King",
      "capacity": 2,
      "availableCount": 1,
      "currency": "USD",
      "nightlyRate": 200,
      "staySubtotal": 600,
      "priceBasis": "accommodation_subtotal",
      "taxes": null,
      "fees": null,
      "finalTotal": null,
      "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&roomId=room_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN",
      "photos": [
        "https://images.example.com/hotel/original.jpg"
      ],
      "coverImage": {
        "id": "photo_example",
        "url": "https://images.example.com/hotel/original.jpg",
        "alt": "Example hotel courtyard",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/hotel/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "exterior",
          "title": "Exterior"
        }
      },
      "maxGuests": 2,
      "image": "https://images.example.com/hotel/original.jpg",
      "imageVariants": [
        {
          "url": "https://images.example.com/hotel/640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ]
    }
  ],
  "complete": true,
  "generatedAt": "2027-01-10T09:00:00-08:00"
}
Response JSON schema
No options match this stay
No options match this stay
JSON
{
  "listingId": "hotel:property_example",
  "status": "sold_out",
  "options": [],
  "complete": true,
  "generatedAt": "2027-01-10T09:00:00-08:00"
}
Validation error · HTTP 422
Validation error
JSON
{
  "error": "Invalid search criteria.",
  "details": [
    {
      "field": "checkOut",
      "message": "Check-out must follow check-in."
    }
  ]
}
Provider unavailable · HTTP 503
Provider unavailable
JSON
{
  "error": "Travel service temporarily unavailable.",
  "complete": false
}

Synthetic successful response. Photo URLs, IDs and booking tokens are examples, not live inventory. Ratings and address/contact additions await deployment; see their rollout notes. Required fields inside optional objects apply only when that object is present.

Deliver a currently public, versioned listing photograph without guest or affiliate authentication.

Behavior & constraints

  • Internal handler for /public/listing-images/{asset}/{version}/{file}. Use only returned image URLs. Success is immutable; failures are no-store. Private galleries and withdrawn photos are excluded.
Request
cURL
curl -I 'https://api-preview.wikiup.app/public/listing-images/ASSET/VERSION/640.webp'
Example response
HTTP
Image bytes; Content-Type: image/webp; Cache-Control: public, max-age=31536000, immutable

Deliver a currently public, versioned listing photograph without guest or affiliate authentication.

Behavior & constraints

  • Internal handler for /public/listing-images/{asset}/{version}/{file}. Use only returned image URLs. Success is immutable; failures are no-store. Private galleries and withdrawn photos are excluded.
Request
cURL
curl -I 'https://api-preview.wikiup.app/public/listing-images/ASSET/VERSION/640.webp'
Example response
HTTP
Image bytes; Content-Type: image/webp; Cache-Control: public, max-age=31536000, immutable

Listing partners: search live published inventory across a destination, parent region, or San Diego County.

Query parameters

destinationstringRequired

Stable destination/region ID from WikiupTravel.

checkInstringRequired

Arrival date in property-local YYYY-MM-DD. Stay must be 1–28 nights and within the supported two-year window.

checkOutstringRequired

Exclusive departure date in property-local YYYY-MM-DD; must follow checkIn.

adultsintegerOptional

Integer 1–20; default 2. Adults plus children must not exceed 20.

childrenintegerOptional

Integer 0–19; default 0. Adults plus children must not exceed 20.

petsintegerOptional

Integer 0–10; default 0. The booking engine enforces each room’s pet policy.

pageintegerOptional

One-based property page, 1–1000; default 1.

pageSizeintegerOptional

Properties per page, 1–12; default 12. Rental properties may produce multiple listing cards.

Response fields

contractVersion2Required

Response contract version; currently 2.

queryobjectRequired

Validated search inputs and defaults used to produce this response.

query.destinationstringRequired

Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography.

query.checkInstringRequired

Arrival calendar date in the property timezone, YYYY-MM-DD. format: date

query.checkOutstringRequired

Departure calendar date, YYYY-MM-DD; checkout is not an occupied night. format: date

query.adultsintegerRequired

Adult guest count; defaults to 2 in requests. minimum: 0

query.childrenintegerRequired

Child guest count; defaults to 0 in requests. minimum: 0

query.petsintegerRequired

Pet count; defaults to 0 in requests. minimum: 0

query.pageintegerRequired

One-based property page number. minimum: 0

query.pageSizeintegerRequired

Property count per page, not listing-card count; rental properties can produce multiple cards. minimum: 0

listingsArray<object>Required

Public display listings for this response. Catalog listings are unchecked; priced listings represent matching availability.

listings[]objectRequired

Response structure: Listing.

listings[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

listings[].type"hotel" | "vacation_rental"Required

Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit.

listings[].propertyIdstringRequired

Raw Wikiup property identifier.

listings[].namestringRequired

Public display name.

listings[].propertyNamestringRequired

Public property listing title, falling back to property name.

listings[].locationstringRequired

Saved city/state display label, not a street address or map position.

listings[].imagestring | nullRequired

Cover photo URL, or null if no public photo exists.

listings[].imageVariantsArray<object>Required

Prepared responsive sizes for the cover image.

listings[].imageVariants[]objectRequired

Response structure: ImageVariant.

listings[].imageVariants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

listings[].imageVariants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

listings[].imageVariants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

listings[].imageVariants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

listings[].maxGuestsintegerOptional

Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards. minimum: 0

listings[].availableRoomCountintegerOptional

Number of qualifying rooms across the hotel for these dates and party. minimum: 0

listings[].currencystringRequired

Three-letter currency code. All amounts are in major currency units.

listings[].nightlyRatenumber | nullRequired

Average accommodation rate per night for this requested stay, excluding taxes and fees. minimum: 0

listings[].staySubtotalnumber | nullRequired

Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees. minimum: 0

listings[].priceBasis"accommodation_subtotal"Required

Prices are accommodation subtotals, not final checkout totals.

listings[].taxesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

listings[].feesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

listings[].finalTotalnullRequired

Determined at checkout. Null must not be displayed as zero.

listings[].bookingUrlstringRequired

Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it. format: uri

listings[].priceLabel"From" | "Stay"Required

From for the lowest qualifying hotel option; Stay for a rental.

listings[].mapLocationobject | nullRequired

Exact approved public coordinate pair, or null. Never use town-center guesses.

listings[].mapLocation.latitudenumberRequired

Exact approved public latitude in decimal degrees. minimum: -90; maximum: 90

listings[].mapLocation.longitudenumberRequired

Exact approved public longitude in decimal degrees. minimum: -180; maximum: 180

listings[].timeZonestring | nullRequired

Validated property IANA time zone. Use for local timestamps; null means unknown.

resultsArray<object>Required

Per-property or per-request results. Inspect individual outcomes rather than treating every HTTP 200 as complete.

results[]objectRequired

One record in results.

results[].propertyobjectRequired

Public property projection for compatibility consumers.

results[].property.idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].property.namestringRequired

Public display name.

results[].property.type"hotel" | "vacation_rental"Optional

Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit.

results[].property.locationstringOptional

Saved city/state display label, not a street address or map position.

results[].property.coverImageobject | nullOptional

Public cover image metadata, or null when absent.

results[].property.coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].property.coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

results[].property.coverImage.altstringRequired

Image alternative text for accessible presentation.

results[].property.coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

results[].property.coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

results[].property.coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

results[].property.coverImage.variants[]objectRequired

Response structure: ImageVariant.

results[].property.coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

results[].property.coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

results[].property.coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

results[].property.coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

results[].property.coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

results[].property.coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].property.coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

results[].property.photosArray<string>Required

Public photo URLs for this inventory; may be empty.

results[].property.photos[]stringRequired

One value in the ordered collection. format: uri

results[].property.destinationobjectRequired

Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography.

results[].property.destination.idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].property.destination.namestringRequired

Public display name.

results[].property.destination.regionIdstringRequired

Qualified parent region ID, for example east-county-san-diego-ca, or the destination ID when no parent applies.

results[].property.mapLocationobject | nullOptional

Exact approved public coordinate pair, or null. Never use town-center guesses.

results[].property.mapLocation.latitudenumberRequired

Exact approved public latitude in decimal degrees. minimum: -90; maximum: 90

results[].property.mapLocation.longitudenumberRequired

Exact approved public longitude in decimal degrees. minimum: -180; maximum: 180

results[].property.timeZonestring | nullOptional

Property IANA timezone for date and time presentation; null means unknown.

results[].roomsArray<object>Required

Bookable room or pooled room-type options.

results[].rooms[]objectRequired

Response structure: LegacyRoom.

results[].rooms[].idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].rooms[].roomIdstring | nullRequired

Physical room identifier; null for a pooled room-type option.

results[].rooms[].roomTypeIdstring | nullRequired

Room-type identifier for pooled inventory; null for a named room.

results[].rooms[].namestringRequired

Public display name.

results[].rooms[].coverImageobject | nullOptional

Public cover image metadata, or null when absent.

results[].rooms[].coverImage.idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].rooms[].coverImage.urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

results[].rooms[].coverImage.altstringRequired

Image alternative text for accessible presentation.

results[].rooms[].coverImage.widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

results[].rooms[].coverImage.heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

results[].rooms[].coverImage.variantsArray<object>Required

Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url.

results[].rooms[].coverImage.variants[]objectRequired

Response structure: ImageVariant.

results[].rooms[].coverImage.variants[].urlstringRequired

Public versioned photo URL. Use the returned URL unchanged; it contains no API key. format: uri

results[].rooms[].coverImage.variants[].widthintegerRequired

Actual image width in pixels; do not assume the nominal thumbnail width. minimum: 1

results[].rooms[].coverImage.variants[].heightintegerRequired

Actual image height in pixels; preserve its aspect ratio. minimum: 1

results[].rooms[].coverImage.variants[].format"avif" | "webp" | "jpeg" | "png"Required

Encoded thumbnail image format.

results[].rooms[].coverImage.groupobject | nullRequired

Optional owner-defined photo group; null means ungrouped.

results[].rooms[].coverImage.group.idstringRequired

Stable identifier of this resource; preserve it unchanged.

results[].rooms[].coverImage.group.titlestringRequired

Display title supplied by Wikiup; group titles are Title Case. maxLength: 160

results[].rooms[].photosArray<string>Required

Public photo URLs for this inventory; may be empty.

results[].rooms[].photos[]stringRequired

One value in the ordered collection. format: uri

results[].rooms[].capacityintegerRequired

Maximum supported guests for this exact bookable option. minimum: 0

results[].rooms[].availableCountintegerRequired

Number of physical units assignable throughout the entire requested stay; not a hold. minimum: 0

results[].rooms[].currencystringRequired

Three-letter currency code. All amounts are in major currency units.

results[].rooms[].nightlyRatenumberRequired

Average accommodation rate per night for this requested stay, excluding taxes and fees. minimum: 0

results[].rooms[].staySubtotalnumberRequired

Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees. minimum: 0

results[].rooms[].priceBasis"accommodation_subtotal"Required

Prices are accommodation subtotals, not final checkout totals.

results[].rooms[].taxesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

results[].rooms[].feesnullRequired

Not quoted by this endpoint. Null means unknown until checkout, not zero.

results[].rooms[].finalTotalnullRequired

Determined at checkout. Null must not be displayed as zero.

results[].rooms[].bookingUrlstringRequired

Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it. format: uri

failuresArray<object>Required

Provider failures; never interpret these as sold-out inventory.

failures[]objectRequired

One record in failures.

failures[].propertyIdstringRequired

Raw Wikiup property identifier.

failures[].code"timeout" | "provider_unavailable"Required

Machine-readable provider failure code.

failures[].retryabletrueRequired

True when the failed provider request may be retried.

metaobjectRequired

Pagination and completion metadata.

meta.pageintegerRequired

One-based property page number. minimum: 0

meta.pageSizeintegerRequired

Property count per page, not listing-card count; rental properties can produce multiple cards. minimum: 0

meta.nextPageinteger | nullRequired

Next property page number, or null at the end. minimum: 1

meta.matchedPropertiesintegerRequired

Eligible properties matching geography before this page is evaluated. minimum: 0

meta.searchedPropertiesintegerRequired

Properties whose availability check succeeded on this page. minimum: 0

meta.soldOutPropertiesintegerRequired

Checked properties with no options matching dates, party and booking rules; not necessarily occupied. minimum: 0

meta.withdrawnPropertiesintegerRequired

Properties removed because eligibility changed while processing. minimum: 0

meta.partialbooleanRequired

True when provider failures make the current response incomplete.

meta.pageCompletebooleanRequired

True when this page has no provider failures; does not imply all pages were fetched.

meta.completebooleanRequired

Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search.

meta.generatedAtstringRequired

Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date. format: date-time

meta.paginationBasis"affiliate_properties" | "published_properties"Required

Pagination counts affiliate properties or owner-published properties according to key scope.

Error responses

401
Missing or invalid authentication.
403
Wrong credential scope, inactive affiliate or denied property access.
404
Direct listing is missing, blacklisted, inactive or has the wrong listing type.
422
Invalid query/body. See error and details[].field/message.
429
Rate limited; wait for Retry-After before retrying.
503
Provider unavailable or timed out. This is not sold-out inventory.

Behavior & constraints

  • Use a server-side affiliate key for attributed bookings, or travel_availability for search only, associated with a verified email account. Affiliate results include all active Wikiup inventory across owners except the affiliate blacklist; no owner opt-in is required. Preserve bookingUrl unchanged; see /affiliates.md. It can also access direct public listing content and availability, but cannot access owner or guest resources. Existing property keys are restricted by membership, permissions and selected property IDs.
  • No x-property-id header. Search-only and property-restricted keys retain owner publication requirements; affiliate keys do not. Responses contain public fields only.
  • At most 12 properties per page, 3 concurrent provider searches, 10-second search deadline, and one admitted request per account per second. Partial provider failures are distinct from sold-out properties. Follow meta.nextPage; never treat an incomplete page as an exhaustive search.
  • Prices are provider-calculated accommodation subtotals. Taxes, fees and finalTotal are null, determined at checkout. Currency follows the booking engine. Availability is not a hold.
  • See /#listing-partners for partner integration steps and /travel-availability.md for the complete contract and Hidden San Diego setup.
Request
cURL
curl 'https://api-preview.wikiup.app/api/travel/availability?destination=julian-ca&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&page=1&pageSize=12' \
  -H 'Authorization: Bearer <affiliate-api-key>'
Response · 200
JSON
{
  "contractVersion": 2,
  "query": {
    "destination": "julian-ca",
    "checkIn": "2027-02-09",
    "checkOut": "2027-02-12",
    "adults": 2,
    "children": 0,
    "pets": 0,
    "page": 1,
    "pageSize": 12
  },
  "listings": [
    {
      "id": "hotel:property_example",
      "type": "hotel",
      "propertyId": "property_example",
      "name": "Example Hotel",
      "propertyName": "Example Hotel",
      "location": "Julian, CA",
      "mapLocation": null,
      "timeZone": "America/Los_Angeles",
      "currency": "USD",
      "nightlyRate": 200,
      "staySubtotal": 600,
      "priceBasis": "accommodation_subtotal",
      "taxes": null,
      "fees": null,
      "finalTotal": null,
      "priceLabel": "From",
      "availableRoomCount": 1,
      "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN",
      "image": "https://images.example.com/hotel/original.jpg",
      "imageVariants": [
        {
          "url": "https://images.example.com/hotel/640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ]
    }
  ],
  "results": [
    {
      "property": {
        "id": "property_example",
        "name": "Example Hotel",
        "type": "hotel",
        "location": "Julian, CA",
        "mapLocation": null,
        "timeZone": "America/Los_Angeles",
        "coverImage": {
          "id": "photo_example",
          "url": "https://images.example.com/hotel/original.jpg",
          "alt": "Example hotel courtyard",
          "width": 1600,
          "height": 900,
          "variants": [
            {
              "url": "https://images.example.com/hotel/640.webp",
              "width": 640,
              "height": 360,
              "format": "webp"
            }
          ],
          "group": {
            "id": "exterior",
            "title": "Exterior"
          }
        },
        "photos": [
          "https://images.example.com/hotel/original.jpg"
        ],
        "destination": {
          "id": "julian-ca",
          "name": "Julian",
          "regionId": "east-county-san-diego-ca"
        }
      },
      "rooms": [
        {
          "id": "room_example",
          "roomId": "room_example",
          "roomTypeId": null,
          "name": "Garden King",
          "capacity": 2,
          "availableCount": 1,
          "currency": "USD",
          "nightlyRate": 200,
          "staySubtotal": 600,
          "priceBasis": "accommodation_subtotal",
          "taxes": null,
          "fees": null,
          "finalTotal": null,
          "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&roomId=room_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_A_VALID_TOKEN",
          "photos": [
            "https://images.example.com/hotel/original.jpg"
          ],
          "coverImage": {
            "id": "photo_example",
            "url": "https://images.example.com/hotel/original.jpg",
            "alt": "Example hotel courtyard",
            "width": 1600,
            "height": 900,
            "variants": [
              {
                "url": "https://images.example.com/hotel/640.webp",
                "width": 640,
                "height": 360,
                "format": "webp"
              }
            ],
            "group": {
              "id": "exterior",
              "title": "Exterior"
            }
          }
        }
      ]
    }
  ],
  "failures": [],
  "meta": {
    "page": 1,
    "pageSize": 12,
    "nextPage": null,
    "paginationBasis": "affiliate_properties",
    "matchedProperties": 1,
    "searchedProperties": 1,
    "soldOutProperties": 0,
    "withdrawnProperties": 0,
    "partial": false,
    "pageComplete": true,
    "complete": true,
    "generatedAt": "2027-01-10T09:00:00-08:00"
  }
}
Response JSON schema
Validation error · HTTP 422
Validation error
JSON
{
  "error": "Invalid search criteria.",
  "details": [
    {
      "field": "checkOut",
      "message": "Check-out must follow check-in."
    }
  ]
}
Provider unavailable · HTTP 503
Provider unavailable
JSON
{
  "error": "Travel service temporarily unavailable.",
  "complete": false
}

Synthetic successful response. Photo URLs, IDs and booking tokens are examples, not live inventory. Ratings and address/contact additions await deployment; see their rollout notes. Required fields inside optional objects apply only when that object is present.

Read owner-controlled travel publication and destination.

Behavior & constraints

  • Property owner only. Destination must be a leaf destination, not a region or county. Missing records return unpublished; no inventory is published automatically.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/properties/<property-id>/travel-listing' \
  -H 'Authorization: Bearer <owner-token>'
Example response
JSON
{
  "listing": {
    "destinationId": "julian-ca",
    "published": true
  }
}

Explicitly publish or unpublish a property in WikiupTravel.

Behavior & constraints

  • Property owner only. Destination must be a leaf destination, not a region or county. Missing records return unpublished; no inventory is published automatically.
Request
cURL
curl -X PUT 'https://api.wikiup.app/api/properties/<property-id>/travel-listing' \
  -H 'Authorization: Bearer <owner-token>' \
  -H 'Content-Type: application/json' \
  -d '{"published":true,"destinationId":"julian-ca"}'
Example response
JSON
{
  "listing": {
    "destinationId": "julian-ca",
    "published": true
  }
}

API Reference

Waitlist

Submits a public waitlist request for unavailable dates or a preferred room. Sends a branded acknowledgement; joining the waitlist does not reserve a room or charge the guest.

Availability widget's Join the waitlist form.

Body fields

propertyIdstringRequired

Property accepting the request.

namestringRequired

Guest name; 1–200 characters after trimming.

emailstringRequired

Valid email, at most 254 characters. Stored in lowercase; receives waitlist emails.

checkInstring · dateRequired

YYYY-MM-DD, today or later in the property's time zone.

checkOutstring · dateRequired

YYYY-MM-DD, strictly after checkIn.

guestsintegerOptional

1–50. Defaults to 2.

roomIdstring | nullOptional

Preferred active room at this property. null (default) accepts any room.

notesstring | nullOptional

Optional request, up to 4,000 characters; defaults to null.

Behavior & constraints

  • Repeated identical pending requests receive the same acknowledgement without creating a duplicate. A contact may have at most 20 pending requests at a property; additional requests return 429.
  • Unknown fields are rejected; a legacy phone field is accepted but discarded. A public request cannot attach a reservationId; authenticated guests use /api/guest-portal/reservation/waitlist for a room change.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/widget-waitlist' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"prop_123","name":"Alex Morgan","email":"guest@example.com","checkIn":"2027-06-11","checkOut":"2027-06-13","guests":2,"roomId":"room_123"}'
Response · 201
JSON
{
  "joined": true
}

Lists all waitlist entries and notification-processing tasks for the selected property. Entries are ordered by creation time, oldest first.

Console waitlist management screen.

Response fields

entries[].statusstring

Waitlist lifecycle state; changed by processing or close/reopen actions.

Allowed valueswaitingsendingnotifiedfailedclosed
tasks[].statusstring

Availability notification task state.

Allowed valuespendingcompletefailed

Behavior & constraints

  • Requires reservations.view. There are no pagination query parameters on this route.
Request
cURL
curl -X GET 'https://api.wikiup.app/api/waitlist' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: prop_123'
Example response
JSON
{
  "entries": [
    {
      "id": "wait_123",
      "propertyId": "prop_123",
      "name": "Alex Morgan",
      "email": "guest@example.com",
      "checkIn": "2027-06-11",
      "checkOut": "2027-06-13",
      "guests": 2,
      "roomId": "room_123",
      "reservationId": null,
      "notes": null,
      "status": "waiting",
      "createdAt": "2026-10-22T12:00:00.000Z",
      "updatedAt": "2026-10-22T12:00:00.000Z"
    }
  ],
  "tasks": []
}

Creates a waitlist request on behalf of a guest, optionally tied to an existing reservation for a room-change request. Sends the guest an acknowledgement email.

Body fields

namestringRequired

Guest name; 1–200 characters after trimming.

emailstringRequired

Valid email, at most 254 characters. Stored in lowercase; receives waitlist emails.

checkInstring · dateRequired

YYYY-MM-DD, today or later in the property's time zone.

checkOutstring · dateRequired

YYYY-MM-DD, strictly after checkIn.

guestsintegerOptional

1–50. Defaults to 2.

roomIdstring | nullOptional

Preferred active room at this property. null (default) accepts any room.

notesstring | nullOptional

Optional request, up to 4,000 characters; defaults to null.

reservationIdstring | nullOptional

Optional upcoming reservation at the property. The contact email must match its guest; roomId must differ from the currently booked room.

Behavior & constraints

  • Requires reservations.manage. Dates must start today or later in the property time zone. Success persists the request even if the acknowledgement email fails.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/waitlist' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: prop_123' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alex Morgan","email":"guest@example.com","checkIn":"2027-06-11","checkOut":"2027-06-13","guests":2,"roomId":"room_123"}'
Response · 201
JSON
{
  "entry": {
    "id": "wait_123",
    "propertyId": "prop_123",
    "name": "Alex Morgan",
    "email": "guest@example.com",
    "checkIn": "2027-06-11",
    "checkOut": "2027-06-13",
    "guests": 2,
    "roomId": "room_123",
    "reservationId": null,
    "notes": null,
    "status": "waiting",
    "createdAt": "2026-10-22T12:00:00.000Z",
    "updatedAt": "2026-10-22T12:00:00.000Z"
  }
}

Edits a waiting request or closes/reopens it. Uses optimistic concurrency to prevent overwriting another innkeeper's change.

Path parameters

idstringRequired

Waitlist entry ID from GET /api/waitlist.

Body fields

expectedUpdatedAtstringRequired

Exact updatedAt returned for this entry. Stale values return 409; reload before retrying.

actionstringOptional

Supply action or entry, never both.

Allowed valuesclosereopen
entryobjectOptional

Complete waitlist input with name, email, checkIn, checkOut and optional guests/roomId/reservationId/notes, as in POST /api/waitlist. Partial patches inside entry are not supported.

Behavior & constraints

  • Requires reservations.manage. Only waiting entries can be edited; reopen other states first. An in-flight notification blocks editing for up to 15 minutes. Editing dates/room triggers another availability check.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/waitlist/wait_123' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: prop_123' \
  -H 'Content-Type: application/json' \
  -d '{"expectedUpdatedAt":"2026-10-22T12:00:00.000Z","action":"close"}'
Example response
JSON
{
  "entry": {
    "id": "wait_123",
    "propertyId": "prop_123",
    "name": "Alex Morgan",
    "email": "guest@example.com",
    "checkIn": "2027-06-11",
    "checkOut": "2027-06-13",
    "guests": 2,
    "roomId": "room_123",
    "reservationId": null,
    "notes": null,
    "status": "closed",
    "createdAt": "2026-10-22T12:00:00.000Z",
    "updatedAt": "2026-10-22T12:00:00.000Z"
  }
}

Processes pending availability notification tasks for the selected property. This can send emails to matching waitlisted guests.

Console waitlist refresh and retry controls.

Behavior & constraints

  • Requires reservations.manage. No body is required. A successful response acknowledges processing; reload GET /api/waitlist to inspect individual entry and task outcomes.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/waitlist/process' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: prop_123'
Example response
JSON
{
  "ok": true
}

Permanently removes waitlist entries whose check-in date is before today in the property's time zone, regardless of notification status.

Behavior & constraints

  • Requires reservations.manage. No body is required. Requests starting today are retained; the response reports how many entries were actually deleted.
Request
cURL
curl -X POST 'https://api.wikiup.app/api/waitlist/cleanup' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: prop_123'
Example response
JSON
{
  "deletedCount": 2
}

API Reference

Widgets & website

Load resolved data for first-party direct widget rendering.

Path parameters

widgetstringRequired

faqs, overview, gallery, availability, booking, addons, payment, giftcard, confirmation, checkin, cancellation, modification, guestportal or chat.

Query parameters

propertyIdstringOptional

Property ID, with the same resolution rules as the hosted route.

parentOriginstringOptional

Origin of the first-party host, used by existing property resolution.

Behavior & constraints

  • Uses the same loader, defaults, token validation and public-data filtering as /widgets/{widget}; chat reuses /chat. Responses are private, no-store. No request body. The existing HTML and iframe SDK routes remain available.
  • props contains the existing resolved page props for the requested widget. Optional properties are omitted; existing nullable properties remain null. Booking, payment and guest portal credentials retain their existing requirements.
Request
cURL
curl 'https://api.wikiup.app/api/widgets/gallery/render?propertyId=property_123'
Example response
JSON
{
  "widget": "gallery",
  "props": {
    "widget": "gallery",
    "property": {
      "slug": "example-inn",
      "name": "Example Inn"
    },
    "galleryLayout": "bento"
  }
}

Resolved widget page props; example shows representative property fields.

Read the saved appearance and copy used by the property's hosted widgets. Requires widgets.manage.

Widget Studio edits this persisted configuration; the API's hosted widgets load it, and the public site embeds those widgets.

Path parameters

idstringRequired

Property ID.

Behavior & constraints

  • Returns the webpage object directly, or null when no saved configuration exists.
  • Hosted UI is rendered at /widgets/{widget}, not /api/widgets. Widget names: overview, gallery, availability, booking, addons, payment, giftcard, confirmation, checkin, cancellation, modification, guestportal.
  • Per-embed query options can override supported saved settings for that render without changing this record. Use Widget Studio to preview the final configuration.
Request
cURL
curl 'https://api.wikiup.app/api/properties/property_123/webpage' \
  -H 'Authorization: Bearer <access-token>'
Example response
JSON
{
  "id": "property_123",
  "propertyId": "property_123",
  "heroTitle": "Your stay starts here",
  "heroLayout": "split",
  "availabilityLayout": "card",
  "galleryLayout": "bento"
}

Merge and save hosted-widget appearance and copy, creating the configuration if needed. Requires widgets.manage.

Widget Studio edits this persisted configuration; the API's hosted widgets load it, and the public site embeds those widgets.

Path parameters

idstringRequired

Property ID.

Body fields

galleryGroupPhotosboolean | nullOptional

Group gallery photos using their existing labels. Defaults to false; null restores the default. Omitted PATCH preserves the saved value.

galleryShowCaptionsboolean | nullOptional

Show captions in gallery layouts. Defaults to true; null restores the default. Image dialogs always show available captions, regardless of this flag.

galleryBentoGapinteger | nullOptional

Bento Grid gap in pixels, from 0 to 64. Zero removes gaps. Null/unset uses responsive 14px/16px/18px spacing. Omitted PATCH retains the saved value.

borderWidthstringOptional

Enabled widget border thickness, 0px–12px; defaults to 1px. Omitted PATCH preserves the saved value. Null is rejected.

galleryFontSizestring | nullOptional

Gallery caption size in px, rem, em or percent. Null/unset inherits website paragraph font size.

galleryTextColorstring | nullOptional

Six-digit hex caption color. Null/unset inherits website primary text color.

galleryFontFamilystring | nullOptional

Gallery caption font family. Null/unset inherits website font family.

galleryFontStylestring | nullOptional

Gallery caption style. Null/unset inherits website typography.

Allowed valuesnormalbolditalicbold-italic
heroLayoutstring | nullOptional

Hero composition. Unsupported values render as split.

Allowed valuessplitstackededitorialoverlay
availabilityLayoutstring | nullOptional

Availability search layout. Unsupported values render as card.

Allowed valuescardvertical
galleryLayoutstring | nullOptional

Gallery composition. Unsupported values render as vertical.

Allowed valuesbentothumbnailverticaltwo-columndynamic-columns
galleryImageScalenumber | nullOptional

Image scale percentage. The renderer rounds and clamps this to 60–140, with 70 as the default.

checkinRoomStepsPlacementinteger | nullOptional

Nonnegative insertion position for room-specific instructions among property check-in steps.

fontFamilystring | nullOptional

Font-family value shared by hosted widgets.

heroEyebrowstring | nullOptional

Saved copy for the corresponding hosted widget or message section.

heroTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

heroBodystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

cancellationTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

cancellationBodystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

modificationTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

modificationBodystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

confirmationTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

confirmationMessagestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

checkinTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

checkinBodystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

checkinReminderSubjectstring | nullOptional

Saved copy for the corresponding hosted widget or message section.

checkinReminderMessagestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

calendarEventTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

calendarEventDescriptionstring | nullOptional

Saved copy for the corresponding hosted widget or message section.

aboutTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

aboutBodystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

bookingTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

bookingBodystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

bookingCancellationReschedulePolicystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

contactTitlestring | nullOptional

Saved copy for the corresponding hosted widget or message section.

contactBodystring | nullOptional

Saved copy for the corresponding hosted widget or message section.

metaDescriptionstring | nullOptional

Public-site search metadata. Empty values fall back to property content.

seoTitlestring | nullOptional

Public-site search metadata. Empty values fall back to property content.

seoDescriptionstring | nullOptional

Public-site search metadata. Empty values fall back to property content.

pageBackgroundColorstring | nullOptional

CSS color value for this widget theme role.

panelBackgroundColorstring | nullOptional

CSS color value for this widget theme role.

textPrimaryColorstring | nullOptional

CSS color value for this widget theme role.

textMutedColorstring | nullOptional

CSS color value for this widget theme role.

textHighlightColorstring | nullOptional

CSS color value for this widget theme role.

buttonBackgroundColorstring | nullOptional

CSS color value for this widget theme role.

buttonTextColorstring | nullOptional

CSS color value for this widget theme role.

inputBackgroundColorstring | nullOptional

CSS color value for this widget theme role.

inputTextColorstring | nullOptional

CSS color value for this widget theme role.

borderColorstring | nullOptional

CSS color value for this widget theme role.

galleryFrameColorstring | nullOptional

CSS color value for this widget theme role.

galleryFrameWidthstring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

paragraphFontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

smallTextFontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

labelFontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

buttonFontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

h1FontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

h2FontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

h3FontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

h4FontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

h5FontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

h6FontSizestring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

borderRadiusstring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

panelBorderRadiusstring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

buttonRadiusstring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

photoRadiusstring | nullOptional

CSS length, for example 16px or 1rem, used by the corresponding widget style.

heroShowPhoneboolean | nullOptional

Visibility/behavior switch for the named hosted-widget feature.

heroShowEmailboolean | nullOptional

Visibility/behavior switch for the named hosted-widget feature.

heroShowAddressboolean | nullOptional

Visibility/behavior switch for the named hosted-widget feature.

overviewHideSearchBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

availabilityHideWidgetBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

availabilityHideSearchBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

availabilityHideRoomCardBordersboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

galleryHideWidgetBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

galleryHideItemBordersboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

bookingHideWidgetBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

bookingHideSummaryBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

bookingHideGuestDetailsBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

bookingHideSectionBordersboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

paymentHideWidgetBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

paymentHideEstimateBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

paymentHidePanelBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

cancellationHideWidgetBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

cancellationHidePanelBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

modificationHideWidgetBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

modificationHidePanelBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

confirmationHideWidgetBorderboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

confirmationHideStayCardBordersboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

confirmationHideDetailPanelBordersboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

confirmationHidePanelBordersboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

sendCheckinReminderEmailboolean | nullOptional

Whether the configured check-in reminder email is enabled.

includeCalendarInviteboolean | nullOptional

Whether to offer/include the calendar invite in the configured check-in flow.

hideBordersboolean | nullOptional

Whether to hide this widget border; omitted values use renderer defaults.

availabilityRoomBordersOnlyboolean | nullOptional

Visibility/behavior switch for the named hosted-widget feature.

Behavior & constraints

  • Returns {message, webpage}, with 201 on first creation and 200 on update. Unknown keys are stripped by validation; id and propertyId are assigned from the existing record/path.
  • Hosted UI is rendered at /widgets/{widget}, not /api/widgets. Widget names: overview, gallery, availability, booking, addons, payment, giftcard, confirmation, checkin, cancellation, modification, guestportal.
  • Per-embed query options can override supported saved settings for that render without changing this record. Use Widget Studio to preview the final configuration.
Request
cURL
curl -X PATCH 'https://api.wikiup.app/api/properties/property_123/webpage' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"heroTitle":"Your stay starts here","heroLayout":"split","availabilityLayout":"card","galleryLayout":"bento"}'
Example response
JSON
{
  "message": "Webpage copy updated.",
  "webpage": {
    "id": "property_123",
    "propertyId": "property_123",
    "heroTitle": "Your stay starts here",
    "heroLayout": "split",
    "availabilityLayout": "card",
    "galleryLayout": "bento"
  }
}

Return the current placeholder dashboard-component collection. Requires widgets.manage.

This administrative route is distinct from the hosted booking widgets rendered at /widgets/{widget}.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Behavior & constraints

  • Currently always returns []. It does not list available hosted widget types or saved Widget Studio configuration.
  • The handler advertises PUT but does not implement persistence: PUT returns 405. Save hosted widget appearance at PATCH /api/properties/{id}/webpage instead.
Request
cURL
curl 'https://api.wikiup.app/api/widgets' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
[]

Build the arrivals, in-house, and departures board for a date in the property's time zone. Requires reservations.view.

The console Today board and iOS dashboard request these reservations, including room, details, and check-in guide progress.

Request headers

x-property-idstringRequired

Property context. It must identify a property the authenticated user can access.

Query parameters

datestringOptional

Exact board date in YYYY-MM-DD. Takes precedence over daysFromToday.

daysFromTodayintegerOptional

Day offset from today in the property's time zone. Defaults to 0; negative offsets request past dates.

Response fields

reservations[].todayLanestring

Operational board lane. Arrival-day checked-in guests move to checkedin only on the property's current day; same-day departures appear as departure.

Allowed valuesarrivalcheckedindeparture

Behavior & constraints

  • Returns {reservations:[...]}. Canceled reservations and blockouts are excluded; stays spanning the requested date and same-day departures are included.
  • Use date for deterministic reports and daysFromToday for relative dashboard navigation. Dates refer to the property's local day, not the client's device day.
Request
cURL
curl 'https://api.wikiup.app/api/widgets/today?date=2026-10-23' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'x-property-id: property_123'
Example response
JSON
{
  "reservations": [
    {
      "id": "reservation_123",
      "propertyId": "property_123",
      "roomId": "room_123",
      "type": "reservation",
      "start": "2026-10-23",
      "end": "2026-10-25",
      "status": "upcoming",
      "todayLane": "arrival",
      "room": {
        "id": "room_123",
        "name": "Garden Suite"
      },
      "details": {
        "adultsCount": 2,
        "earlyCheckIn": true,
        "eta": "13:00"
      },
      "checkinGuideProgress": null
    }
  ]
}

Resolve public property identity, contact details, an image, postal address, SEO copy, and indicative nightly price range for a property or host.

The public site's property-seo loader uses this response to produce page metadata and structured hotel data.

Query parameters

propertyIdstringOptional

Known property ID. Supply this or a recognized host to resolve the property.

hoststringOptional

Recognized property hostname or URL, for example inn.example.com.

Response fields

priceRangestring | null

Indicative rounded base-rate range across Active rooms, such as $150-$220 per night. It is not a date-specific quote.

Behavior & constraints

  • Returns 404 when no property can be resolved. Optional values are null when unavailable.
  • SEO title and description fall back through saved webpage copy to property content. The image prefers the first hero image, then the main gallery image, then the logo.
  • Use an availability/pricing endpoint for actual stay prices, taxes, discounts, and room availability.
Request
cURL
curl 'https://api.wikiup.app/api/public-site-metadata?propertyId=property_123'
Example response
JSON
{
  "propertyId": "property_123",
  "name": "Cedar Ridge Inn",
  "seoTitle": "Cedar Ridge Inn",
  "metaDescription": "A quiet inn in Julian.",
  "description": "A quiet inn in Julian.",
  "phone": "+17605550100",
  "email": "stay@example.com",
  "imageUrl": "/api/web-assets/properties/property_123/hero.jpg",
  "priceRange": "$150-$220 per night",
  "url": "https://inn.example.com",
  "address": {
    "streetAddress": "100 Main Street",
    "addressLocality": "Julian",
    "addressRegion": "CA",
    "postalCode": "92036",
    "addressCountry": "US",
    "formatted": "100 Main Street, Julian, CA, 92036, US"
  }
}

API Reference

Internal jobs

Run a bounded preview inventory delivery tick using an authenticated internal scheduler request.

Request headers

X-Wikiup-Job-TimestampstringRequired

Unix time in milliseconds, within two minutes of the server clock.

X-Wikiup-Job-SignaturestringRequired

Hex HMAC-SHA256 signature over timestamp, POST, and the fixed route path separated by newlines.

Behavior & constraints

  • Preview only. Requires a timestamp-bound HMAC-SHA256 signature from the configured scheduler. User sessions and property API keys are rejected. No request body. Dispatches at most one property and four batches; durable progress survives later ticks. Production returns 403, missing configuration 503, invalid signatures 401. Operational holds return 409.
Request
cURL
curl -X POST 'https://api-preview.wikiup.app/api/internal/channel-inventory/deliver' \
  -H 'X-Wikiup-Job-Timestamp: <timestamp-ms>' \
  -H 'X-Wikiup-Job-Signature: <service-signature>'
Example response
JSON
{
  "results": []
}

API Reference

Operator controls

Read channel production availability (Wikiup operator only).

Behavior & constraints

  • Requires an allowlisted, verified Wikiup operator session. Property ownership and API keys do not grant operator access.
  • Preview forwards to the fixed production API using the operator session; production reads the authoritative release records. Responses are not cached. All channels default to disabled. Production catalog results include only enabled channels.
Request
cURL
curl https://api-preview.wikiup.app/api/channel-management/releases \
  -H 'Authorization: Bearer <operator-session>'
Example response
JSON
{
  "releases": []
}

Validate and enable or disable a production channel (Wikiup operator only).

Body fields

codestringRequired

Exact channel code.

namestringRequired

Channel display name.

productionEnabledbooleanRequired

Whether to present this channel in production.

validationNotesstringOptional

Required validation evidence when enabling.

checklistobjectOptional

All eight validation checks must be true when enabling.

Behavior & constraints

  • The preview console exposes this operator control under Add channel → Production availability. Deploy the production API first. No production database credentials are needed in preview.
  • Enable requires code, name, productionEnabled:true, validationNotes of at least 10 characters, and every checklist item true: connection, mapping, activation, reservationCreate, reservationModify, reservationCancel, reconnect, providerValidation. This is an explicit operator attestation; mock tests alone do not certify provider-specific behavior.
  • Disable uses productionEnabled:false and hides the channel from new connections. Existing connections and reservations remain. This control does not bypass production billing/certification restrictions on channel-management mutations.
Request
cURL
curl -X POST https://api-preview.wikiup.app/api/channel-management/releases \
  -H 'Authorization: Bearer <operator-session>' \
  -H 'Content-Type: application/json' \
  -d '{"code":"Expedia","name":"Expedia","productionEnabled":false}'
Example response
JSON
{
  "release": {
    "code": "Expedia",
    "name": "Expedia",
    "productionEnabled": false
  }
}