> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spaportal.cz/llms.txt
> Use this file to discover all available pages before exploring further.

# Price period

> A range of nights with the same package prices: prices per guest and per room, and the promotions that apply.

A price period is a range of nights in which a package has the same prices.
Use periods for a price table on a package page, for example "10 to 11 January:
from EUR 523.60 per guest for 7 nights".

Request the [visit type detail](https://docs.spaportal.cz/api/v2/reference/visit-types/get-a-visit-type.md)
with `expand=priceFromPeriods`. The package's `priceFromPeriods` compares all
its hotels, and each `hotelListings[]` entry has the periods of that hotel.
With `hotelId`, the detail returns only that hotel's listing, and the
package's periods still compare all hotels. The list endpoint does not return
periods.

Each period prices the package's shortest stay as if every night of the stay
had the prices and promotions of that period. Free rooms and permitted
arrival days are not checked, and the stay does not have to fit into the
period: a sold-out room can set the lowest price, and a one-night period
can show a price for seven nights. When the guest chooses dates, test them
against the [stay rules](https://docs.spaportal.cz/api/visit-types.md#testing-a-stay-against-its-rules)
and check that a room is free.

## Fields and night bounds

| Field | Meaning |
| - | - |
| `from` | First night of the period. |
| `to` | Last night of the period, inclusive. |
| `activePromotionIds` | Promotions that apply in the period to at least one room with a price, in the order of the package's `promotions`. |
| `priceFrom` | Prices by currency, or `null` when no room has a price for the period. |

A night is identified by the date it starts on: `to: "2027-01-11"` includes
the night of 11 January, with checkout on 12 January. Periods are sorted by
date and do not overlap. Nights outside the package's validity or its price
list have no period, so the list can have gaps. Periods have no id.

## Where periods start and end

Periods cover the nights on which the package is valid and its price list
has a season, including past nights. A new period starts where a season
starts or ends, or where a promotion starts or ends for a room with a price.
Two neighboring periods can therefore have the same prices, for example when
a promotion changes only the price of a more expensive room.

The package's periods combine all its hotels: a new period at one hotel also
starts a new period of the package. Disabled room types are ignored: they set
no prices and start no periods.

Periods also end with each [validity](https://docs.spaportal.cz/api/objects/visit-type.md#validity)
period of the package. With `toAppliesTo: "departure"`, the last night is
the night before `to`; with `toAppliesTo: "arrival"`, it is the night of
`to`.

## Price metrics

A non-null `priceFrom` has one or both currencies, `CZK` and `EUR`. Each
currency has three prices:

| Metric | Meaning |
| - | - |
| `perPersonPerNight` | Lowest price per guest per night. |
| `perPersonPerStay` | Price per guest for the whole stay, in the same room as `perPersonPerNight`. |
| `perStay` | Lowest price of a whole room for the whole stay. It can come from a different room or hotel. |

Every metric has these fields:

| Field | Meaning |
| - | - |
| `amount` | Price after promotions, as [`Money`](https://docs.spaportal.cz/api/currencies). Display it directly. |
| `original` | Price of the same room before promotions, or `null` when promotions do not lower the rounded price. |
| `nights` | Length of the priced stay: the package's minimum or fixed number of nights, not the length of the period. |
| `occupancy` | Standard occupancy of the room the price comes from. |
| `hotel` | Hotel of that room: `id` and localized `name`. |
| `roomTypeId` | Room type the price comes from. |
| `appliedPromotionIds` | Promotions included in this price, in the order of the package's `promotions`. |

Prices assume a room at its standard occupancy and use the same nightly
prices and discounts as a booking. Overlapping promotions combine as
described in [Prices](https://docs.spaportal.cz/api/prices.md#promotions).

Per-person amounts are rounded separately. A room at EUR 100 per night for
three guests gives EUR 33.33 per guest per night and EUR 233.33 per guest for
seven nights. Take each amount from the API instead of multiplying rounded
values.

For a price per guest, display `perPersonPerStay.amount` with its `nights`.
For a room price, display `perStay.amount` with its `nights` and
`occupancy`.

## Promotions in a period

Look up promotion ids in the package's [`promotions`](https://docs.spaportal.cz/api/objects/promotion).
`activePromotionIds` lists the promotions that apply in the period, and
`appliedPromotionIds` lists the promotions included in one price. A promotion
can be active without lowering the displayed price, for example when it
discounts only a more expensive room.

Show `original` struck through next to the `amount` of the same metric, and
do not apply the promotions to `amount` again.
[Building package pages](https://docs.spaportal.cz/guides/visit-types.md#displaying-discounts) shows how
to display a saving.

## Past periods and empty values

Past periods use today's price list and promotions, so they do not show what
past bookings paid. With `expand=priceFromPeriods`, the detail also returns
ended promotions, so every id in a past period can be looked up.

Periods are returned for every package, including packages booked on request
and unavailable packages. An ended package has `validity: []` and
`priceFrom: null`, and its periods still show its past prices.

| Value | Meaning |
| - | - |
| Field missing | The detail was requested without `expand=priceFromPeriods`, or the response is a list. |
| `priceFromPeriods: null` | SpaPortal cannot calculate the periods for this package. Do not show a price table. |
| `priceFromPeriods: []` | The package has no price list for the nights of its validity. Do not show a price table. |
| A period with `priceFrom: null` | The period exists, but none of its rooms has a price. Show the row without a price. |

## Fields


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.