--- updatedAt: 2026-08-10T14:22:21.000Z agentTools: projectIndex: https://developers.cloudbeds.com/llms.txt --- # Preview how a folio adjustment (tax/fee/rate/room-revenue) would affect Smart Policy scheduled payments. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Cloudbeds API v2", "description": "

Welcome to the documentation for Cloudbeds API Version v2! If you are looking to learn how to use the Cloudbeds API to access guest information, reservations, or similar data for your Cloudbeds customers, then you've come to the right place.

In this document you will find all the API methods we provide along with explanations for parameters and response examples.

If you have questions about different implementation steps (e.g. how to implement OAuth 2.0), please refer to our Integrations Portal.

Be sure to subscribe to the monthly Cloudbeds API announcement mailing list to receive information on new additions and improvements to the Cloudbeds API and related developer tools.

Endpoint: https://api.cloudbeds.com/{method}

HTTPS: Our API requires HTTPS. We'll respond with an appropriate error if you're not using it.

Request Format: HTTP GET, POST and PUT (Content-Type: application/x-www-form-urlencoded)

Response Format: JSON

Response Header: X-Request-ID is added to response headers in all calls to help accelerate support and troubleshooting.

Run in Postman use this link to access our Public collection in Postman.

", "version": "v2" }, "servers": [ { "url": "https://api.cloudbeds.com/", "description": "Cloudbeds API v2" } ], "paths": { "/smart-policies/v1/payments/preview-adjustment": { "post": { "tags": [ "Smart Policies" ], "summary": "Preview how a folio adjustment (tax/fee/rate/room-revenue) would affect Smart Policy scheduled payments.", "operationId": "AdjustmentPreviewController::preview", "parameters": [ { "name": "x-property-id", "in": "header", "description": "A numeric, comma-separated string representing the property IDs, sent in the header.", "required": true, "schema": { "type": "string", "example": "1,2,3" } } ], "requestBody": { "description": "Adjustment preview input.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAdjustmentRequestSchema" } } } }, "responses": { "200": { "description": "Adjustment preview result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAdjustmentResponseSchema" } } } }, "400": { "description": "Bad request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponseSchema" } } } }, "403": { "description": "Forbidden response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponseSchema" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponseSchema" } } } } }, "security": [ { "default": [ "read:rate" ] } ] } } }, "components": { "schemas": { "BadRequestErrorItemSchema": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "BadRequestErrorListSchema": { "type": "array", "items": { "$ref": "#/components/schemas/BadRequestErrorItemSchema" } }, "BadRequestResponseSchema": { "required": [ "message" ], "properties": { "message": { "type": "string" }, "errors": { "oneOf": [ { "$ref": "#/components/schemas/BadRequestErrorListSchema" } ], "nullable": true, "description": "The list of errors" }, "code": { "description": "Error code identifying the type of error", "type": "string", "example": "INVALID_REQUEST", "nullable": true } }, "type": "object" }, "ForbiddenResponseSchema": { "properties": { "message": { "type": "string" } }, "type": "object" }, "InternalServerErrorResponseSchema": { "required": [ "message" ], "properties": { "message": { "type": "string" }, "code": { "description": "Error code identifying the type of error", "type": "string", "example": "PAYMENT_VOID_FAILED", "nullable": true } }, "type": "object" }, "MoneySchema": { "description": "Money representation with amount in smallest currency unit and ISO 4217 currency code", "required": [ "amount", "currencyCode" ], "properties": { "amount": { "description": "Amount in the smallest representable units of the currency (e.g., cents for USD). For example, USD $124.39 would be \"12439\".", "type": "string", "example": "12439" }, "currencyCode": { "description": "ISO 4217 currency code", "type": "string", "example": "USD" } }, "type": "object" }, "PreviewAdjustmentInputSchema": { "required": [ "target", "token", "amount" ], "properties": { "target": { "description": "The type of adjustment to preview.", "type": "string", "enum": [ "TAX", "FEE", "RATE", "ROOM_REVENUE" ] }, "token": { "description": "Folio adjustment id token, exactly as the save receives it (e.g. 'tax_42', 'fee_7', 'rate', 'roomRevenue_manual').", "type": "string", "example": "tax_42" }, "amount": { "oneOf": [ { "$ref": "#/components/schemas/SmartPolicyMoneyInputSchema" } ], "nullable": true, "description": "Adjustment amount (positive magnitude); the charge is REDUCED by this." }, "bookingRoomId": { "description": "Booking room id the adjustment targets (rate / room-revenue).", "type": "string", "example": "555", "nullable": true }, "rateSourceId": { "description": "Rate source id — required for RATE adjustments to resolve the applicable taxes/fees.", "type": "string", "example": "777", "nullable": true }, "isRootSource": { "description": "Whether the rate source is a root source (RATE adjustments).", "type": "boolean", "nullable": true }, "isHotelCollectBooking": { "description": "Whether the booking is hotel-collect (RATE adjustments).", "type": "boolean", "nullable": true } }, "type": "object" }, "PreviewAdjustmentRequestSchema": { "required": [ "reservationId", "adjustment" ], "properties": { "reservationId": { "description": "Reservation ID to preview the adjustment for.", "type": "string", "example": "12345" }, "adjustment": { "oneOf": [ { "$ref": "#/components/schemas/PreviewAdjustmentInputSchema" } ], "nullable": true } }, "type": "object" }, "SmartPolicyMoneyInputSchema": { "description": "Money input as per the REST API Modeling Specification: amount in the smallest representable units\nof the currency, paired with an ISO 4217 currency code.", "required": [ "amount", "currencyCode" ], "properties": { "amount": { "description": "Amount in the smallest representable units of the currency (e.g., cents for USD).", "type": "string", "example": "500" }, "currencyCode": { "description": "ISO 4217 currency code.", "type": "string", "example": "EUR" } }, "type": "object" }, "PreviewAdjustmentResponseSchema": { "properties": { "resultType": { "description": "The outcome of the adjustment preview.", "type": "string", "enum": [ "SCHEDULED_PAYMENT_REDUCED", "SCHEDULED_PAYMENT_CANCELLED", "REFUND_REQUIRED", "NO_SCHEDULE_CHANGE", "NO_SMART_POLICY" ], "example": "SCHEDULED_PAYMENT_REDUCED" }, "newReservationTotal": { "$ref": "#/components/schemas/MoneySchema" }, "alreadyPaid": { "$ref": "#/components/schemas/MoneySchema" }, "refundRequired": { "$ref": "#/components/schemas/MoneySchema" }, "scheduledPayments": { "type": "array", "items": { "$ref": "#/components/schemas/PreviewScheduledPaymentSchema" } } }, "type": "object" }, "PreviewScheduledPaymentSchema": { "properties": { "id": { "type": "string", "example": "1001" }, "originalAmount": { "$ref": "#/components/schemas/MoneySchema" }, "newAmount": { "$ref": "#/components/schemas/MoneySchema" }, "status": { "description": "Status of the scheduled payment after the adjustment.", "type": "string", "enum": [ "REDUCED", "CANCELLED", "UNCHANGED" ], "example": "REDUCED" } }, "type": "object" } }, "securitySchemes": { "default": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.cloudbeds.com/auth/oauth/authorize", "tokenUrl": "https://api.cloudbeds.com/auth/oauth/token", "scopes": { "read:addon": "Read Addon information", "read:doorLockKey": "Read DoorLock keys and settings", "write:doorLockKey": "Write DoorLock keys and settings", "delete:doorLockKey": "Delete DoorLock keys and settings", "read:housekeeping": "Read Housekeeping inspections", "read:marketsegment": "Read Market Segmentation groups and segments", "write:marketsegment": "Write Market Segmentation groups and segments", "delete:marketsegment": "Delete Market Segmentation groups and segments", "write:importTask": "Create new data imports", "read:importTask": "Read data imports", "hotel:read": "Read Hotel information", "hotel:write": "Write Hotel information", "hotel:delete": "Delete Hotel information", "write:appError": "Write AppError information", "read:agePolicy": "Read Age Policy information", "write:agePolicy": "Write Age Policy information", "delete:agePolicy": "Delete Age Policy information", "write:allotmentBlocks": "Write AllotmentBlock information", "read:allotmentBlocks": "Read AllotmentBlock information", "delete:allotmentBlocks": "Delete AllotmentBlock information", "read:aiAvailability": "Read availability and pricing for AI agents" } } } } } }, "tags": [ { "name": "Smart Policies", "description": "Smart Policies" } ] } ```