Raw schema
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"price_guarantee",
"date_change",
"goodwill_refund",
"checkin_request"
]
},
"letter_language": {
"type": "string",
"enum": [
"en",
"ko",
"ja",
"zh"
],
"description": "Language of the text: en (default), ko, ja or zh. Usually the language the booking site or hotel reads."
},
"hotel_name": {
"type": "string"
},
"city": {
"type": "string"
},
"check_in": {
"type": "string",
"description": "YYYY-MM-DD."
},
"check_out": {
"type": "string",
"description": "YYYY-MM-DD."
},
"booked_on": {
"type": "string",
"enum": [
"booking",
"agoda",
"trip",
"expedia",
"hotels",
"other"
],
"description": "Booking site. Required for price_guarantee; omit for a direct hotel booking."
},
"room_type": {
"type": "string"
},
"adults": {
"type": "integer",
"description": "Default 2."
},
"cancellation_policy": {
"type": "string",
"enum": [
"free_cancellation",
"non_refundable"
]
},
"breakfast": {
"type": "boolean",
"description": "Breakfast included in the booking."
},
"paid_total": {
"type": "number",
"description": "Total paid, taxes included. Required for price_guarantee."
},
"paid_currency": {
"type": "string",
"description": "ISO currency of paid_total."
},
"booked_date": {
"type": "string",
"description": "YYYY-MM-DD."
},
"lower_price_site": {
"type": "string",
"enum": [
"booking",
"agoda",
"trip",
"expedia",
"hotels",
"other"
],
"description": "Required for price_guarantee."
},
"lower_price_site_other": {
"type": "string"
},
"lower_total": {
"type": "number",
"description": "Required for price_guarantee."
},
"lower_currency": {
"type": "string"
},
"lower_seen_at": {
"type": "string",
"description": "When the lower price was seen, e.g. 2026-10-02 14:30."
},
"lower_url": {
"type": "string",
"description": "Link to the lower offer."
},
"new_check_in": {
"type": "string",
"description": "date_change: requested new check-in, YYYY-MM-DD. Omit to ask which dates are possible."
},
"new_check_out": {
"type": "string",
"description": "date_change: requested new check-out, YYYY-MM-DD."
},
"reason": {
"type": "string",
"enum": [
"illness",
"flight",
"visa",
"family",
"disaster",
"other"
],
"description": "goodwill_refund: why the stay cannot go ahead."
},
"perks": {
"type": "array",
"items": {
"type": "string",
"enum": [
"upgrade",
"late",
"breakfast"
]
},
"description": "checkin_request: what to ask for."
},
"tracking_id": {
"type": "integer",
"description": "Optional HotelRefund tracking for the same stay."
}
},
"required": [
"kind",
"hotel_name",
"check_in",
"check_out"
]
}