Connector API: document Get sell limit state

connector-api/SUMMARY.md

@@ -13,6 +13,7 @@
 * [Concepts](concepts/README.md)
   * [Multi-property](concepts/multi-property.md)
   * [Restrictions](concepts/restrictions.md)
+  * [Sell limits](concepts/sell-limits.md)
   * [Taxation](concepts/taxation.md)
   * [Time units](concepts/time-units.md)
 * [Use cases](use-cases/README.md)
@@ -103,6 +104,7 @@
   * [Restrictions](operations/restrictions.md)
   * [Routing rules](operations/routingrules.md)
   * [Rules](operations/rules.md)
+  * [Sell limits](operations/selllimits.md)
   * [Service order notes](operations/serviceordernotes.md)
   * [Service overbooking limits](operations/serviceoverbookinglimits.md)
   * [Services](operations/services.md)

connector-api/changelog/README.md

@@ -1,6 +1,18 @@
 # Changelog
 
 {% updates format="full" %}
+{% update date="2026-09-15" %}
+
+## Sell limit state available through the Connector API
+
+- [Get sell limit state](../operations/selllimits.md#get-sell-limit-state) (restricted operation):
+  - New operation returning the sell limit state of a daily service per rate, resource category and time unit: the effective limit, the number of spaces already sold against it, and the number still available. This lets an integration apply the same constraint that Mews Operations applies when a reservation is created.
+  - The response is a time series: `TimeUnitStartsUtc` appears once, and each rate and resource category pair carries `Limits`, `Sold` and `Available` as arrays indexed against it.
+  - A null element in `Limits` means no sell limit is configured for that combination, which is different from a configured limit of `0`. `Available` can be negative when a configured limit is lower than the number of spaces already sold.
+  - Where limits are configured at more than one level, for example on both a rate and its rate group, the response reports the one that actually constrains the sale. See [Sell limits](../concepts/sell-limits.md) for the full evaluation rules.
+  - Enabled per integration partner; contact Mews to opt in.
+
+{% endupdate %}
 {% update date="2026-09-10" %}
 
 ## Payout operations

connector-api/concepts/sell-limits.md

@@ -0,0 +1,90 @@
+# Sell limits
+
+An explanation of how sell limit state is evaluated, for consumers of [Get sell limit state].
+
+## What are sell limits?
+
+A sell limit is a daily cap on how many spaces may be sold on a given rate. Properties use them to control consumption of a particular rate rather than of the inventory as a whole. For example:
+
+- Cap a discounted corporate rate at 10 spaces per night, while the rest of the inventory stays open at public rates
+- Cap a promotional rate during a high demand period so it cannot absorb the whole property
+
+A sell limit is a separate constraint from availability and from restrictions. When a limit is reached, the affected rate closes for that day even though physical inventory remains.
+
+{% hint style="info" %}
+
+### Additional help on sell limits
+
+- [Search all Help articles related to sell limits](https://help.mews.com/s/global-search/sell%20limits?language=en_US)
+
+{% endhint %}
+
+## Sell limits in the API
+
+To read sell limit state, use [Get sell limit state]. The operation is read only. Sell limits are configured in **Mews Operations**; there is no API operation to set or clear them.
+
+Sell limits apply only to services whose time unit period is `Day`. Requesting state for any other service returns an error. For more information, see [Time units].
+
+## What the operation returns
+
+The operation returns a time series rather than one record per combination. The time axis appears once, as `TimeUnitStartsUtc`, and each rate and resource category pair appears once, carrying three arrays indexed against that axis.
+
+| Property | Meaning |
+| :-- | :-- |
+| `TimeUnitStartsUtc` | The time units covered by the request, in ascending order. |
+| `Limits` | The effective sell limit for each time unit, or null for a time unit where no sell limit is configured. |
+| `Sold` | The number of spaces already sold against the limit, for each time unit. |
+| `Available` | `Limits` minus `Sold`, element by element, or null where no sell limit is configured. |
+
+`Limits`, `Sold` and `Available` always have exactly as many elements as `TimeUnitStartsUtc`, in the same order, so the value for a given day is at the same index in all three. Read the index of the day from `TimeUnitStartsUtc` once and reuse it.
+
+{% hint style="info" %}
+
+### Reading one day's state
+
+To get the state of a rate and resource category on a given day, find that day's position in `TimeUnitStartsUtc`, then read that position from `Limits`, `Sold` and `Available`.
+
+{% endhint %}
+
+### No limit, and a limit of zero, are different states
+
+A null element in `Limits` means the property has not configured a sell limit for that combination and time unit, so nothing constrains the sale. A `0` means the property has configured a cap of zero, which closes the rate for that day. Treat them as distinct: a client that reads null as zero will stop selling rates that are in fact open.
+
+`Sold` is still reported where `Limits` is null, so a client can see consumption on rates that are currently uncapped.
+
+### `Available` can be negative
+
+A property can lower a sell limit below the number of spaces already sold. When that happens the corresponding `Available` element is negative. Treat any value of `0` or below as closed.
+
+## Which limit is reported
+
+A property can configure a limit on a rate, on the rate group that contains it, on a specific resource category, or across all resource categories. These combine, and more than one can apply to a single sale.
+
+The operation reports the combination that actually constrains the sale, which is the one leaving the least availability. A rate limit of 9 alongside a rate group limit of 2 is reported as a limit of 2, because the rate group is what closes the rate first. This matches what **Mews Operations** enforces when a reservation is created, so a client does not need to reimplement the precedence rule.
+
+Items where the resource category is null describe the limit that applies across all resource categories. Items with a resource category describe the limit for that category. Request the categories you care about, and the across-all-categories item is returned alongside them, first.
+
+The applicable level can differ from one day to the next. On a day where the binding cap sits at a broader level than one resource category, every resource category under that cap reports the same shared numbers. Do not sum `Available` across resource categories: two categories each reporting `2` from one shared rate-level cap of `2` have `2` between them, not `4`. Summing them is the oversell this operation exists to prevent.
+
+## Which reservations count as sold
+
+`Sold` counts confirmed, started, processed and optional reservations for each time unit. It does not count:
+
+- inquired reservations
+- availability blocks that share the rate with the sell limit, or reservations picked up from within such a block
+
+Availability blocks are a contractual allocation agreed separately, so they do not consume sell limit availability.
+
+## Sell limits are consumed per night of stay
+
+A sell limit is consumed on each night of a stay, not on the departure date. A one night reservation arriving on 1 November consumes the limit for 1 November only; 2 November is unaffected and can still be sold at the same rate.
+
+## Related pages
+
+- [Get sell limit state] - the operation reference
+- [Restrictions] - the other mechanism that can close a rate, with its own set of rules
+- [Time units] - why sell limits apply only to daily services
+
+[Get sell limit state]: ../operations/selllimits.md#get-sell-limit-state
+[Restrictions]: restrictions.md
+[Time units]: time-units.md

connector-api/use-cases/revenue-management.md

@@ -80,6 +80,16 @@ To retrieve information about restrictions, use [Get all restrictions](../operat
 
 > **Important:** For more information about restrictions, including the algorithms used when setting and clearing restrictions, and the scope of restrictions affected by API operations, see [Concepts > Restrictions](../concepts/restrictions.md).
 
+## Sell limits
+
+Sell limits are daily caps on how many spaces may be sold on a given rate, applied separately from availability and from restrictions. To read their current state, use [Get sell limit state](../operations/selllimits.md#get-sell-limit-state). It returns, per rate and resource category, the effective limit, the number of spaces already sold against it, and the number still available, as arrays indexed against the requested days, so an integration can apply the same constraint that Mews applies when a reservation is created. The operation is read only; sell limits are configured in Mews Operations.
+
+| <div style="width:350px">'How to' use case</div> | API Operations                                                            |
+| :----------------------------------------------- | :------------------------------------------------------------------------ |
+| How to get sell limit state for a rate and date range | [Get sell limit state](../operations/selllimits.md#get-sell-limit-state) |
+
+> **Important:** A null element in `Limits` means no sell limit is configured for that day, which is different from a configured limit of `0`. `Available` can be negative when a limit is lower than the number of spaces already sold, so treat any value of `0` or below as closed. Sell limits apply only to services with a daily time unit, and are consumed per night of stay rather than on the departure date. For the full evaluation rules, including which limit is reported when a rate and its rate group are both capped, see [Concepts > Sell limits](../concepts/sell-limits.md).
+
 ## Occupancy
 
 When calculating occupancy, it is important to take the hierarchy of resources into account. For example, if there is a reservation against a dormitory (or dorm), then not only is the dormitory occupied but also the beds which are child resources of the dormitory. And vice versa, if a bed in a dorm is occupied, then the dorm is also occupied.