Create a quote

POST/api/v1/quote

Asks the PMS for the current price of one stay and checks that the stay can be sold. The response has the full price breakdown, the cancellation terms, and a signed quoteToken that you send with the reservation. The token is valid for 15 minutes.

Query parameters

Parameter	Type	Description
`displayCurrency`	string	ISO 4217 currency for every amount in the response.

Request body

Field	Required	Type	Description
`listingID`	Yes	UUID	OnSeason listing ID.
`checkInDate`	Yes	date	Check-in date, `YYYY-MM-DD`. Not in the past.
`checkOutDate`	Yes	date	Check-out date, `YYYY-MM-DD`. After check-in.
`guests`	Yes	number	Total guests. Minimum `1`.
`guestCountInfo`	No	object	Counts by type: `adults`, `children`, `infants`, and `pets`.
`unitID`	No	UUID	Unit to quote, for `MULTI_UNIT` and `COMPLEX` listings.
`roomType`	No	string	Room type for OnSeason to pick a free unit from. Ignored when you send `unitID`.

Example

curl --request POST "https://zepl-staging.calry.app/api/v1/quote?displayCurrency=EUR" \
  --header "x-calry-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "listingID": "80e0e6d4-48cf-4ca7-8c85-6e8d7e9d969a",
    "checkInDate": "2026-12-05",
    "checkOutDate": "2026-12-08",
    "guests": 4,
    "guestCountInfo": { "adults": 3, "children": 1, "infants": 0, "pets": 0 }
  }'

{
  "quoteId": "q_abcdefghijklmnopqrstuv",
  "quoteExpiresAt": "2026-11-10T10:15:00.000Z",
  "listingID": "80e0e6d4-48cf-4ca7-8c85-6e8d7e9d969a",
  "checkInDate": "2026-12-05",
  "checkOutDate": "2026-12-08",
  "guests": 4,
  "currency": "EUR",
  "totalPrice": 486,
  "priceBeforeTaxes": 436,
  "components": {
    "basePrice": {
      "amount": 396,
      "breakdown": [
        { "name": "Nightly rate", "description": "2026-12-05", "price": 132, "type": "nightly" },
        { "name": "Nightly rate", "description": "2026-12-06", "price": 132, "type": "nightly" },
        { "name": "Nightly rate", "description": "2026-12-07", "price": 132, "type": "nightly" }
      ]
    },
    "fees": {
      "amount": 40,
      "breakdown": [{ "name": "Cleaning fee", "description": "Cleaning fee", "price": 40, "type": "fee" }]
    },
    "taxes": {
      "amount": 50,
      "breakdown": [{ "name": "Taxes", "description": "Taxes", "price": 50, "type": "tax" }]
    },
    "discounts": { "amount": 0, "breakdown": [] }
  },
  "priceModifications": {
    "defaultDiscount": { "percentage": 0, "value": 0 },
    "markup": { "percentage": 10, "value": 36 }
  },
  "deposit": 0,
  "payAtProperty": [
    {
      "name": "Tourist tax",
      "description": "Payable on arrival per person per night",
      "price": 2.6,
      "currency": "EUR",
      "unit": "person_day"
    }
  ],
  "originalTotalPrice": 450,
  "originalBasePrice": {
    "amount": 360,
    "breakdown": [
      { "name": "Nightly rate", "description": "2026-12-05", "price": 120, "type": "nightly" },
      { "name": "Nightly rate", "description": "2026-12-06", "price": 120, "type": "nightly" },
      { "name": "Nightly rate", "description": "2026-12-07", "price": 120, "type": "nightly" }
    ]
  },
  "cancellationPolicy": {
    "policyID": "2f8d6b1a-9c3e-4d7f-8a1b-5e6c7d8f9a0b",
    "name": "Strict",
    "version": 1,
    "source": "TENANT",
    "salesChannel": "acme",
    "timeZone": "Europe/Paris",
    "fixedAt": "2026-11-10T10:00:00.000Z",
    "refundable": true,
    "refundableTag": "RFN",
    "freeCancellationUntil": "2026-11-21T14:00:00.000Z",
    "penalties": [
      { "from": "2026-11-21T14:00:00.000Z", "percentage": 50, "amount": 243, "currency": "EUR" },
      { "from": "2026-11-28T14:00:00.000Z", "percentage": 100, "amount": 486, "currency": "EUR" }
    ],
    "description": "Full refund if cancelled before 2026-11-21 15:00 (Europe/Paris). 50% refund (243.00 EUR) if cancelled before 2026-11-28 15:00 (Europe/Paris). No refund after that."
  },
  "quoteToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "quoteTokenExpiresAt": "2026-11-10T10:15:00.000Z"
}

The token is shortened. Send the whole token you receive.

Response

Field	Type	Description
`listingID`	UUID	Listing quoted.
`checkInDate`, `checkOutDate`	string	Dates quoted.
`guests`	number	Guests quoted.
`currency`	string	Currency of every amount in the response, except `payAtProperty` items, which carry their own.
`totalPrice`	number	Price of the stay with markup, fees, taxes, and discounts. Book at this price.
`priceBeforeTaxes`	number	`totalPrice` without taxes.
`components.basePrice`	price component	Accommodation price.
`components.fees`	price component	Fees, when present.
`components.taxes`	price component	Taxes, when present.
`components.discounts`	price component	PMS discounts, when present. Amounts can be negative.
`priceModifications`	object	Default discount and channel markup, each with `percentage` and `value`. Already in the prices above.
`deposit`	number	Deposit the PMS requires, when it applies.
`payAtProperty`	array	Mandatory costs the guest pays on site. Not in `totalPrice` and not charged at booking. See below.
`originalTotalPrice`	number	Total before OnSeason's price modifications. For information only.
`originalBasePrice`	price component	Accommodation price before OnSeason's price modifications. For information only.
`quoteMetadata`	object	PMS-specific `quoteId` and `ratePlanId`, when the PMS returns them. The token carries them.
`cancellationPolicy`	object	The cancellation terms for this stay, fixed now. Booking with the token keeps them.
`quoteToken`	string	Signed token for Create a reservation. Opaque.
`quoteTokenExpiresAt`	date-time	When the token expires, 15 minutes after the quote.
`quoteId`	string	OnSeason's ID for this quote. Include it in support requests.
`quoteExpiresAt`	date-time	When OnSeason stops keeping this quote.

PMSs name their price lines differently. Treat names and type values you don't recognize as valid lines.

Pay-at-property charge

Field	Type	Description
`id`	string	The PMS's code for the charge, when it has one.
`name`	string	Name to show the guest, such as `Local tax`.
`description`	string	The PMS's wording of when and how the charge is paid, when it has one.
`price`	number	Price per `unit`, in `currency`.
`currency`	string	Currency the property charges in. Can differ from the quote currency.
`unit`	enum	What `price` is per: `stay`, `day`, `week`, `person`, `person_day`, `usage` (metered, such as electricity), or `other` (read `description`).

What the token binds

The token binds the listing, unit, dates, guest count, currency, prices, and cancellation terms to your API key.
A reservation whose listingID, dates, guests, or unitID differs from the quote is rejected.
The token is not a hold on the dates and not an idempotency key.
After 15 minutes, quote again. An expired token is rejected.

Status codes

Status	Meaning
`201`	Quote created.
`400`	The request is invalid, the party is too large, the check-in is too close for the property, or the stay is not available.
`401`	The API key is missing or invalid.
`403`	The listing is not enabled for your channel, or the API key is not allowed to create quotes.
`404`	The listing or unit was not found.