From 4ef2a739ed4cd290415b24ad2c55565a27b18701 Mon Sep 17 00:00:00 2001 From: Denys Shylov Date: Wed, 15 Apr 2026 16:46:44 +0200 Subject: [PATCH 1/5] Add allowances use cases docs --- connector-api/use-cases/allowances.md | 171 ++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 connector-api/use-cases/allowances.md diff --git a/connector-api/use-cases/allowances.md b/connector-api/use-cases/allowances.md new file mode 100644 index 00000000..4d1bff6b --- /dev/null +++ b/connector-api/use-cases/allowances.md @@ -0,0 +1,171 @@ +# Allowances Extended Use Cases + +## Overview + +Allowances are packaged credits that hotels attach to rates, giving guests a spending allowance they can use on-property — for example, a food & beverage credit, spa credit, or minibar allowance. + +Instead of discounting the room rate, hotels offer added value: the guest perceives a better deal, while the hotel protects its ADR and captures incremental non-room revenue. + +Any unspent credit (called **breakage**) is retained by the hotel as additional revenue. + +Integrations — such as point-of-sale (POS) systems, accounting systems, and kiosk or self-service applications — can use the Connector API to: + +* post charges that are automatically offset against a guest's allowance +* retrieve allowance-related order items for billing, reconciliation, and balance reporting + +## Key concepts + +There are several types of order item specific to allowances. Understanding these is essential for working with allowance data through the API. + +### Allowance-related order item types + +| Order item type | What it represents | +| --- | --- | +| `ProductOrder` (with `ProductType = Allowance`) | The allowance product itself — the credit posted to the guest's bill when the allowance is activated. | +| `AllowanceDiscount` | A discount automatically applied to a qualifying charge. This offsets the original charge amount up to the remaining allowance balance. | +| `AllowanceBreakage` | Unspent credit retained by the hotel as revenue when the allowance expires or the guest checks out. | +| `AllowanceContraBreakage` | The accounting balance entry for breakage — ensures double-entry accounting integrity. | + +### Automatic discounting + +When a charge is posted to a guest who has an active allowance, and the charge's accounting category matches the allowance's permitted consumption categories, the system automatically creates an `AllowanceDiscount` item to offset the charge. + +No additional API call is needed to trigger the discount. + +## Posting charges against an allowance + +External systems such as POS integrations can post charges to a guest's profile using [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order). + +If the guest has an active allowance and the charge falls within the allowance's permitted consumption categories (matched by `AccountingCategoryId`), the system will automatically generate an `AllowanceDiscount` order item that offsets the charge — up to the remaining allowance balance. + +Both `ProductOrders` (for products already configured in Mews) and `Items` (for custom items not configured in Mews) are supported. + +In both cases, the `AccountingCategoryId` on the item determines whether the charge qualifies for allowance discounting. + +### Linking orders to reservations + +Specify parameter `LinkedReservationId` when using [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) to link the order to the guest's reservation. + +This is especially important for allowances because it ensures the charge and the resulting allowance discount are associated with the correct reservation and its billing automation rules. + +### "How to" use cases (posting charges) + +| "How to" use case | API operations | +| --- | --- | +| How to post a charge that triggers an allowance discount | [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) | +| How to post a custom item against an allowance | [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) (use `Items` with `AccountingCategoryId`) | +| How to post an existing Mews product against an allowance | [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) (use `ProductOrders`) | + +## Partial consumption + +If the charge amount exceeds the remaining allowance balance, the discount is applied only up to the remaining balance. The guest is responsible for the remainder. + +For example, if a guest has €30 remaining on their F&B allowance and a €45 dinner charge is posted, an `AllowanceDiscount` of €30 is created and the guest owes €15. + +## Charges that do not qualify + +If the posted item's accounting category is not in the allowance's permitted consumption list, no discount is generated. + +The charge is posted normally to the guest's bill. + +## Retrieving allowance-related order items + +Use [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) to retrieve order items related to allowances. + +You can filter: + +* by reservation using `ServiceOrderIds` +* by bill using `BillIds` +* by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` +* by item type using `Types` + +### "How to" use cases (retrieving items) + +| "How to" use case | API operations | +| --- | --- | +| How to get all order items for a reservation (including allowance items) | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `ServiceOrderIds`) | +| How to get allowance discount items | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `Types` filter with `AllowanceDiscount`) | +| How to get breakage items | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `Types` filter with `AllowanceBreakage`) | +| How to get all allowance-related items on a bill | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `BillIds`) | +| How to get allowance items over a period | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `ClosedUtc` or `ConsumedUtc`) | + +## Working with allowance discounts + +When you retrieve order items of type `AllowanceDiscount`, the item's `Data` field contains additional information that links the discount back to both: + +* the original charge +* the allowance product that funded it + +Specifically, an [`Order item`](https://docs.mews.com/connector-api/operations/orderitems#order-item) with `Data.Discriminator` set to `AllowanceDiscount` will have: + +* `DiscountedOrderItemId` — the unique identifier of the original charge item that was discounted. +* `AllowanceProductOrderItemId` — the unique identifier of the allowance product order item whose credit was consumed. + +You can use [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) with the `OrderItemIds` filter to fetch the details of either: + +* the original charge, or +* the allowance product. + +### "How to" use cases (discount links) + +| "How to" use case | API operations | +| --- | --- | +| How to find the original charge for an allowance discount | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `DiscountedOrderItemId`) | +| How to find which allowance funded a discount | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId`) | + +Discount amounts are negative. An `AllowanceDiscount` order item carries a negative `Amount`, which offsets the positive amount of the original charge on the guest's bill. + +## Working with breakage and profits + +When a guest checks out or an allowance expires with unspent credit remaining, the system generates breakage items. These represent the hotel's retained revenue from unused allowance credit. + +An [`Order item`](https://docs.mews.com/connector-api/operations/orderitems#order-item) with `Data.Discriminator` set to `AllowanceProfits` will have: + +* `AllowanceProductOrderItemId` — the unique identifier of the allowance product whose credit was not fully consumed. +* `AllowanceProfitType` — the type of profit entry, which can be one of: + * `AllowanceBreakage` — the profit from unspent allowance credit. + * `AllowanceContraBreakage` — the accounting balance entry for the breakage. + * `AllowanceLoss` — the loss from the allowance product. + * `AllowanceContraLoss` — the accounting balance entry for the loss. + +### "How to" use cases (breakage and profits) + +| "How to" use case | API operations | +| --- | --- | +| How to get breakage items for reconciliation | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `Types` with `AllowanceBreakage`) | +| How to find which allowance generated a breakage item | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId` from the breakage item's `Data`) | + +Breakage and contra-breakage always occur in pairs. For every `AllowanceBreakage` item, there is a corresponding `AllowanceContraBreakage` item to maintain double-entry accounting balance. Accounting integrations should expect and reconcile both. + +## Identifying allowance products + +To identify whether an order item is an allowance product (as opposed to a regular product), check the item's `Data` field. + +An order item with: + +* `Data.Discriminator` set to `Product`, and +* `Data.Product.ProductType` set to `Allowance` + +is an **allowance product** — the credit itself, as opposed to a charge or discount. + +### "How to" use cases (identifying products) + +| "How to" use case | API operations | +| --- | --- | +| How to identify allowance product items among order items | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | + +## Testing your integration + +Ensure you follow the general [`Usage guidelines`](https://docs.mews.com/connector-api/guidelines) for testing integrations. + +When testing an integration that works with allowances, verify the following scenarios: + +* Post a charge with an accounting category that matches the allowance's permitted consumption — confirm an `AllowanceDiscount` item is automatically created. +* Post a charge with an accounting category that does not match — confirm no discount is created. +* Post a charge that exceeds the remaining allowance balance — confirm the discount is capped at the remaining balance. +* Post a charge of amount 0 — confirm no discount is created. +* Retrieve order items for a reservation and confirm you can identify all allowance-related item types (`AllowanceDiscount`, `AllowanceBreakage`, `AllowanceContraBreakage`). +* Confirm that breakage items are created after checkout when allowance credit remains unspent. +* Reconcile the sum of allowance product amount, discount amounts, and breakage amounts — they should balance to zero. + +To cross-check allowance financial data, you can use the **Mews Accounting Report** and the **Bills and Invoices Report** in Mews Operations. From 87a695d0c541eba5d66052570a20cee5df2c6c7c Mon Sep 17 00:00:00 2001 From: Denys Shylov Date: Mon, 20 Apr 2026 17:16:59 +0200 Subject: [PATCH 2/5] Fix some comments and update with glossary --- connector-api/SUMMARY.md | 1 + connector-api/use-cases/allowances.md | 66 +++++++++++++-------------- open-api/glossary.md | 30 ++++++++++++ 3 files changed, 64 insertions(+), 33 deletions(-) diff --git a/connector-api/SUMMARY.md b/connector-api/SUMMARY.md index 0f2c73ea..1ff3fa21 100644 --- a/connector-api/SUMMARY.md +++ b/connector-api/SUMMARY.md @@ -18,6 +18,7 @@ * [Use cases](use-cases/README.md) * ['How to' use cases](use-cases/how-to.md) * [Accounting](use-cases/accounting.md) + * [Allowances](use-cases/allowances.md) * [Customer loyalty](use-cases/loyalty.md) * [Customer management](use-cases/customer-management.md) * [Customer messaging](use-cases/messaging.md) diff --git a/connector-api/use-cases/allowances.md b/connector-api/use-cases/allowances.md index 4d1bff6b..60e35fe6 100644 --- a/connector-api/use-cases/allowances.md +++ b/connector-api/use-cases/allowances.md @@ -2,11 +2,11 @@ ## Overview -Allowances are packaged credits that hotels attach to rates, giving guests a spending allowance they can use on-property — for example, a food & beverage credit, spa credit, or minibar allowance. +An Allowance is a packaged spending benefit that a [Property] attaches to a [Rate], giving guests a pre-defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room [Rate], the [Property] adds value while protecting its [ADR]. -Instead of discounting the room rate, hotels offer added value: the guest perceives a better deal, while the hotel protects its ADR and captures incremental non-room revenue. +From an accounting perspective, the allowance represents a liability the [Property] assumes at activation: the property has committed to absorbing qualifying charges on the guest's behalf, up to the specified amount. When an allowance is activated for a [Reservation], the system posts an allowance [Product] order item (a `ProductOrder` with `ProductType = Allowance`) to the guest's [Bill]. When a qualifying charge is subsequently posted — one whose [Accounting Category] matches the allowance's permitted consumption categories — the system automatically creates an `AllowanceDiscount` order item that offsets the charge up to the remaining allowance balance. No additional API call is needed to trigger the discount. -Any unspent credit (called **breakage**) is retained by the hotel as additional revenue. +Any unspent allowance is retained by the [Property] as additional revenue, which is known as [Breakage]. Integrations — such as point-of-sale (POS) systems, accounting systems, and kiosk or self-service applications — can use the Connector API to: @@ -21,10 +21,10 @@ There are several types of order item specific to allowances. Understanding thes | Order item type | What it represents | | --- | --- | -| `ProductOrder` (with `ProductType = Allowance`) | The allowance product itself — the credit posted to the guest's bill when the allowance is activated. | -| `AllowanceDiscount` | A discount automatically applied to a qualifying charge. This offsets the original charge amount up to the remaining allowance balance. | -| `AllowanceBreakage` | Unspent credit retained by the hotel as revenue when the allowance expires or the guest checks out. | -| `AllowanceContraBreakage` | The accounting balance entry for breakage — ensures double-entry accounting integrity. | +| `ProductOrder` (with `ProductType = Allowance`) | The allowance product — the liability posted to the guest's bill when the allowance is activated. | +| `AllowanceDiscount` | A discount automatically applied to a qualifying charge, offsetting the charge up to the remaining allowance balance. | +| `AllowanceBreakage` | Unspent allowance retained by the [Property] as revenue at checkout. See [Breakage]. | +| `AllowanceContraBreakage` | The accounting contra entry for breakage, ensuring double-entry accounting integrity. | ### Automatic discounting @@ -34,7 +34,7 @@ No additional API call is needed to trigger the discount. ## Posting charges against an allowance -External systems such as POS integrations can post charges to a guest's profile using [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order). +External systems such as POS integrations can post charges to a guest's profile using [`Add order`](../operations/orders.md#add-order). If the guest has an active allowance and the charge falls within the allowance's permitted consumption categories (matched by `AccountingCategoryId`), the system will automatically generate an `AllowanceDiscount` order item that offsets the charge — up to the remaining allowance balance. @@ -44,7 +44,7 @@ In both cases, the `AccountingCategoryId` on the item determines whether the cha ### Linking orders to reservations -Specify parameter `LinkedReservationId` when using [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) to link the order to the guest's reservation. +Specify parameter `LinkedReservationId` when using [`Add order`](../operations/orders.md#add-order) to link the order to the guest's reservation. This is especially important for allowances because it ensures the charge and the resulting allowance discount are associated with the correct reservation and its billing automation rules. @@ -52,9 +52,9 @@ This is especially important for allowances because it ensures the charge and th | "How to" use case | API operations | | --- | --- | -| How to post a charge that triggers an allowance discount | [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) | -| How to post a custom item against an allowance | [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) (use `Items` with `AccountingCategoryId`) | -| How to post an existing Mews product against an allowance | [`Add order`](https://docs.mews.com/connector-api/operations/orders#add-order) (use `ProductOrders`) | +| How to post a charge that triggers an allowance discount | [`Add order`](../operations/orders.md#add-order) | +| How to post a custom item against an allowance | [`Add order`](../operations/orders.md#add-order) (use `Items` with `AccountingCategoryId`) | +| How to post an existing Mews product against an allowance | [`Add order`](../operations/orders.md#add-order) (use `ProductOrders`) | ## Partial consumption @@ -70,7 +70,7 @@ The charge is posted normally to the guest's bill. ## Retrieving allowance-related order items -Use [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) to retrieve order items related to allowances. +Use [`Get all order items`](../operations/orderitems.md#get-all-order-items) to retrieve order items related to allowances. You can filter: @@ -83,11 +83,11 @@ You can filter: | "How to" use case | API operations | | --- | --- | -| How to get all order items for a reservation (including allowance items) | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `ServiceOrderIds`) | -| How to get allowance discount items | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `Types` filter with `AllowanceDiscount`) | -| How to get breakage items | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `Types` filter with `AllowanceBreakage`) | -| How to get all allowance-related items on a bill | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `BillIds`) | -| How to get allowance items over a period | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `ClosedUtc` or `ConsumedUtc`) | +| How to get all order items for a reservation (including allowance items) | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `ServiceOrderIds`) | +| How to get allowance discount items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` filter with `AllowanceDiscount`) | +| How to get breakage items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` filter with `AllowanceBreakage`) | +| How to get all allowance-related items on a bill | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `BillIds`) | +| How to get allowance items over a period | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `ClosedUtc` or `ConsumedUtc`) | ## Working with allowance discounts @@ -96,12 +96,12 @@ When you retrieve order items of type `AllowanceDiscount`, the item's `Data` fie * the original charge * the allowance product that funded it -Specifically, an [`Order item`](https://docs.mews.com/connector-api/operations/orderitems#order-item) with `Data.Discriminator` set to `AllowanceDiscount` will have: +Specifically, an [`Order item`](../operations/orderitems.md#order-item) with `Data.Discriminator` set to `AllowanceDiscount` will have: * `DiscountedOrderItemId` — the unique identifier of the original charge item that was discounted. -* `AllowanceProductOrderItemId` — the unique identifier of the allowance product order item whose credit was consumed. +* `AllowanceProductOrderItemId` — the unique identifier of the allowance product order item which consumed the item. -You can use [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) with the `OrderItemIds` filter to fetch the details of either: +You can use [`Get all order items`](../operations/orderitems.md#get-all-order-items) with the `OrderItemIds` filter to fetch the details of either: * the original charge, or * the allowance product. @@ -110,20 +110,20 @@ You can use [`Get all order items`](https://docs.mews.com/connector-api/operatio | "How to" use case | API operations | | --- | --- | -| How to find the original charge for an allowance discount | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `DiscountedOrderItemId`) | -| How to find which allowance funded a discount | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId`) | +| How to find the original charge for an allowance discount | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `DiscountedOrderItemId`) | +| How to find which allowance funded a discount | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId`) | Discount amounts are negative. An `AllowanceDiscount` order item carries a negative `Amount`, which offsets the positive amount of the original charge on the guest's bill. ## Working with breakage and profits -When a guest checks out or an allowance expires with unspent credit remaining, the system generates breakage items. These represent the hotel's retained revenue from unused allowance credit. +When a guest checks out or an allowance expires with unspent allowance remaining, the system generates breakage items. These represent the hotel's retained revenue from unused allowance. -An [`Order item`](https://docs.mews.com/connector-api/operations/orderitems#order-item) with `Data.Discriminator` set to `AllowanceProfits` will have: +An [`Order item`](../operations/orderitems.md#order-item) with `Data.Discriminator` set to `AllowanceProfits` will have: -* `AllowanceProductOrderItemId` — the unique identifier of the allowance product whose credit was not fully consumed. +* `AllowanceProductOrderItemId` — the unique identifier of the allowance product whose amount was not fully consumed. * `AllowanceProfitType` — the type of profit entry, which can be one of: - * `AllowanceBreakage` — the profit from unspent allowance credit. + * `AllowanceBreakage` — the profit from unspent allowance amount. * `AllowanceContraBreakage` — the accounting balance entry for the breakage. * `AllowanceLoss` — the loss from the allowance product. * `AllowanceContraLoss` — the accounting balance entry for the loss. @@ -132,8 +132,8 @@ An [`Order item`](https://docs.mews.com/connector-api/operations/orderitems#orde | "How to" use case | API operations | | --- | --- | -| How to get breakage items for reconciliation | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `Types` with `AllowanceBreakage`) | -| How to find which allowance generated a breakage item | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId` from the breakage item's `Data`) | +| How to get breakage items for reconciliation | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` with `AllowanceBreakage`) | +| How to find which allowance generated a breakage item | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId` from the breakage item's `Data`) | Breakage and contra-breakage always occur in pairs. For every `AllowanceBreakage` item, there is a corresponding `AllowanceContraBreakage` item to maintain double-entry accounting balance. Accounting integrations should expect and reconcile both. @@ -146,17 +146,17 @@ An order item with: * `Data.Discriminator` set to `Product`, and * `Data.Product.ProductType` set to `Allowance` -is an **allowance product** — the credit itself, as opposed to a charge or discount. +is an **allowance product** — the allowance amount itself, as opposed to a charge or discount. ### "How to" use cases (identifying products) | "How to" use case | API operations | | --- | --- | -| How to identify allowance product items among order items | [`Get all order items`](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | +| How to identify allowance product items among order items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | ## Testing your integration -Ensure you follow the general [`Usage guidelines`](https://docs.mews.com/connector-api/guidelines) for testing integrations. +Ensure you follow the general [`Usage guidelines`](../guidelines/README.md) for testing integrations. When testing an integration that works with allowances, verify the following scenarios: @@ -165,7 +165,7 @@ When testing an integration that works with allowances, verify the following sce * Post a charge that exceeds the remaining allowance balance — confirm the discount is capped at the remaining balance. * Post a charge of amount 0 — confirm no discount is created. * Retrieve order items for a reservation and confirm you can identify all allowance-related item types (`AllowanceDiscount`, `AllowanceBreakage`, `AllowanceContraBreakage`). -* Confirm that breakage items are created after checkout when allowance credit remains unspent. +* Confirm that breakage items are created after checkout when allowance amount remains unspent. * Reconcile the sum of allowance product amount, discount amounts, and breakage amounts — they should balance to zero. To cross-check allowance financial data, you can use the **Mews Accounting Report** and the **Bills and Invoices Report** in Mews Operations. diff --git a/open-api/glossary.md b/open-api/glossary.md index cf35edb7..fbb405a0 100644 --- a/open-api/glossary.md +++ b/open-api/glossary.md @@ -37,6 +37,27 @@ Additional Services are [Services][Service] that cannot be purchased when a [Res All [Order] items and [Payment] items are types of Accounting Item. [Order] items are consumed items, [Payment] items are payments or invoices. +## ADR + +ADR stands for Average Daily Rate, a standard hospitality industry metric expressing the average revenue earned per occupied [Space] per day. Hotels use ADR as a measure of pricing performance — for example, when offering an [Allowance] instead of discounting the room [Rate], the hotel can protect its ADR while still providing added value to the guest. + +## Allowance + +An Allowance is a packaged spending benefit that a [Property] attaches to a [Rate], giving guests a pre-defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room [Rate], the [Property] adds value while protecting its [ADR]. + +From an accounting perspective, the allowance represents a liability the [Property] assumes at activation: the property has committed to absorbing qualifying charges on the guest's behalf, up to the specified amount. When an allowance is activated for a [Reservation], the system posts an allowance [Product] order item (a `ProductOrder` with `ProductType = Allowance`) to the guest's [Bill]. When a qualifying charge is subsequently posted — one whose [Accounting Category] matches the allowance's permitted consumption categories — the system automatically creates an `AllowanceDiscount` order item that offsets the charge up to the remaining allowance balance. No additional API call is needed to trigger the discount. + +Any unspent allowance is retained by the [Property] as additional revenue, which is known as [Breakage]. + +The following order item types are specific to allowances: + +| Order item type | What it represents | +| --- | --- | +| `ProductOrder` (with `ProductType = Allowance`) | The allowance product — the liability posted to the guest's bill when the allowance is activated. | +| `AllowanceDiscount` | A discount automatically applied to a qualifying charge, offsetting the charge up to the remaining allowance balance. | +| `AllowanceBreakage` | Unspent allowance retained by the [Property] as revenue at checkout. See [Breakage]. | +| `AllowanceContraBreakage` | The accounting contra entry for breakage, ensuring double-entry accounting integrity. | + ## ARI ARI is a general hospitality industry term and stands for [Availability], [Rates][Rate] and [Inventory]. @@ -81,6 +102,12 @@ Booking Engine implies the part of a booking website or app through which users The **Mews Booking Engine API** is one of the main APIs within the [Mews Open API][Open API]. It can be used by custom Booking Engines to enable users to check availability and make reservations directly in Mews. +## Breakage + +Breakage is the unspent allowance that is retained by the [Property] as revenue when the allowance expires or the guest checks out. It represents the portion of the allowance that the guest did not consume during their stay. + +In the [Connector API], breakage is represented by an `AllowanceBreakage` order item. For every `AllowanceBreakage` item there is a corresponding `AllowanceContraBreakage` item, which maintains double-entry accounting balance. Accounting integrations should expect and reconcile both items. + ## Business Segment Business Segments, Channel Manager Segments, or just Segments, are used to classify [Reservations][Reservation] by attributes relevant to a [Property]'s operations, such as traveler type or whether the [Reservation] is group or individual. They allow the [Property] to gather information from reports to identify trends and to target customers more effectively. See [Create, modify or delete a segment](https://help.mews.com/s/article/create-modify-or-delete-a-segment?language=en_US&Language=en_US). @@ -591,6 +618,8 @@ A Voucher is a coupon or token that gives [Customers][Customer] or [Companies][C [Accounting Category]: #AccountingCategory [Additional Services]: #AdditionalServices [Accounting Item]: #AccountingItem +[ADR]: #ADR +[Allowance]: #Allowance [ARI]: #ARI [Availability]: #Availability [Availability Block]: #AvailabilityBlock @@ -600,6 +629,7 @@ A Voucher is a coupon or token that gives [Customers][Customer] or [Companies][C [Booking]: #Booking [Booking Engine]: #BookingEngine [Booking Engine API]: #BookingEngineAPI +[Breakage]: #Breakage [Business Segment]: #BusinessSegment [Cashier]: #Cashier [Chain]: #Chain From bc5b41fb99fa35d0da816eb4becb195300887eb1 Mon Sep 17 00:00:00 2001 From: Denys Shylov Date: Mon, 20 Apr 2026 17:18:15 +0200 Subject: [PATCH 3/5] Fix encoding --- connector-api/use-cases/allowances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connector-api/use-cases/allowances.md b/connector-api/use-cases/allowances.md index 60e35fe6..77c084b4 100644 --- a/connector-api/use-cases/allowances.md +++ b/connector-api/use-cases/allowances.md @@ -1,4 +1,4 @@ -# Allowances Extended Use Cases +# Allowances Extended Use Cases ## Overview From e43854d0f992179bcbcd319919ebcc447d25bfe1 Mon Sep 17 00:00:00 2001 From: Denys Shylov Date: Mon, 27 Apr 2026 15:23:26 +0200 Subject: [PATCH 4/5] Review fixes and readme and how to updates --- connector-api/use-cases/README.md | 1 + connector-api/use-cases/allowances.md | 112 ++++++++++++++------------ connector-api/use-cases/how-to.md | 19 ++++- open-api/glossary.md | 13 +-- 4 files changed, 79 insertions(+), 66 deletions(-) diff --git a/connector-api/use-cases/README.md b/connector-api/use-cases/README.md index 4ddaaae3..a9a5a7dd 100644 --- a/connector-api/use-cases/README.md +++ b/connector-api/use-cases/README.md @@ -10,6 +10,7 @@ Even if you are integrating a different type of system, it serves as a good star ## Business use cases * [Accounting](accounting.md) +* [Allowances](allowances.md) * [Customer loyalty](loyalty.md) * [Customer management](customer-management.md) * [Events](events.md) diff --git a/connector-api/use-cases/allowances.md b/connector-api/use-cases/allowances.md index 77c084b4..662267d2 100644 --- a/connector-api/use-cases/allowances.md +++ b/connector-api/use-cases/allowances.md @@ -1,14 +1,14 @@ -# Allowances Extended Use Cases +# Allowances ## Overview -An Allowance is a packaged spending benefit that a [Property] attaches to a [Rate], giving guests a pre-defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room [Rate], the [Property] adds value while protecting its [ADR]. +An `Allowance` is a packaged spending benefit that a `Property` attaches to a `Rate`, giving guests a defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room `Rate`, the `Property` adds value while protecting its Average Daily Rate (ADR). -From an accounting perspective, the allowance represents a liability the [Property] assumes at activation: the property has committed to absorbing qualifying charges on the guest's behalf, up to the specified amount. When an allowance is activated for a [Reservation], the system posts an allowance [Product] order item (a `ProductOrder` with `ProductType = Allowance`) to the guest's [Bill]. When a qualifying charge is subsequently posted — one whose [Accounting Category] matches the allowance's permitted consumption categories — the system automatically creates an `AllowanceDiscount` order item that offsets the charge up to the remaining allowance balance. No additional API call is needed to trigger the discount. +From an accounting perspective, the allowance represents a liability the `Property` assumes at activation: the `Property` has committed to absorbing qualifying charges on the guest's behalf, up to the specified amount. When an allowance is activated for a `Reservation`, the system posts an allowance product order item (a `ProductOrder` with `ProductType = Allowance`) to the guest's `Bill`. When a qualifying charge is subsequently posted — one whose `Accounting Category` matches the allowance's permitted consumption categories — the system automatically creates an `AllowanceDiscount` order item that offsets the charge up to the remaining allowance balance. -Any unspent allowance is retained by the [Property] as additional revenue, which is known as [Breakage]. +Any unspent allowance is retained by the `Property` as additional revenue, which is known as `Breakage`. -Integrations — such as point-of-sale (POS) systems, accounting systems, and kiosk or self-service applications — can use the Connector API to: +Integrations — such as point-of-sale (POS) systems, accounting systems, and kiosk or self-service applications — can use the **Mews Connector API** to: * post charges that are automatically offset against a guest's allowance * retrieve allowance-related order items for billing, reconciliation, and balance reporting @@ -23,50 +23,16 @@ There are several types of order item specific to allowances. Understanding thes | --- | --- | | `ProductOrder` (with `ProductType = Allowance`) | The allowance product — the liability posted to the guest's bill when the allowance is activated. | | `AllowanceDiscount` | A discount automatically applied to a qualifying charge, offsetting the charge up to the remaining allowance balance. | -| `AllowanceBreakage` | Unspent allowance retained by the [Property] as revenue at checkout. See [Breakage]. | +| `AllowanceBreakage` | Unspent allowance retained by the `Property` as revenue at checkout. See `Breakage`. | | `AllowanceContraBreakage` | The accounting contra entry for breakage, ensuring double-entry accounting integrity. | ### Automatic discounting When a charge is posted to a guest who has an active allowance, and the charge's accounting category matches the allowance's permitted consumption categories, the system automatically creates an `AllowanceDiscount` item to offset the charge. +{% hint style="info" %} No additional API call is needed to trigger the discount. - -## Posting charges against an allowance - -External systems such as POS integrations can post charges to a guest's profile using [`Add order`](../operations/orders.md#add-order). - -If the guest has an active allowance and the charge falls within the allowance's permitted consumption categories (matched by `AccountingCategoryId`), the system will automatically generate an `AllowanceDiscount` order item that offsets the charge — up to the remaining allowance balance. - -Both `ProductOrders` (for products already configured in Mews) and `Items` (for custom items not configured in Mews) are supported. - -In both cases, the `AccountingCategoryId` on the item determines whether the charge qualifies for allowance discounting. - -### Linking orders to reservations - -Specify parameter `LinkedReservationId` when using [`Add order`](../operations/orders.md#add-order) to link the order to the guest's reservation. - -This is especially important for allowances because it ensures the charge and the resulting allowance discount are associated with the correct reservation and its billing automation rules. - -### "How to" use cases (posting charges) - -| "How to" use case | API operations | -| --- | --- | -| How to post a charge that triggers an allowance discount | [`Add order`](../operations/orders.md#add-order) | -| How to post a custom item against an allowance | [`Add order`](../operations/orders.md#add-order) (use `Items` with `AccountingCategoryId`) | -| How to post an existing Mews product against an allowance | [`Add order`](../operations/orders.md#add-order) (use `ProductOrders`) | - -## Partial consumption - -If the charge amount exceeds the remaining allowance balance, the discount is applied only up to the remaining balance. The guest is responsible for the remainder. - -For example, if a guest has €30 remaining on their F&B allowance and a €45 dinner charge is posted, an `AllowanceDiscount` of €30 is created and the guest owes €15. - -## Charges that do not qualify - -If the posted item's accounting category is not in the allowance's permitted consumption list, no discount is generated. - -The charge is posted normally to the guest's bill. +{% endhint %} ## Retrieving allowance-related order items @@ -76,7 +42,7 @@ You can filter: * by reservation using `ServiceOrderIds` * by bill using `BillIds` -* by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` +* by time period using, for example, `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` * by item type using `Types` ### "How to" use cases (retrieving items) @@ -89,6 +55,23 @@ You can filter: | How to get all allowance-related items on a bill | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `BillIds`) | | How to get allowance items over a period | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `ClosedUtc` or `ConsumedUtc`) | +## Identifying allowance products + +To identify whether an order item is an allowance product (as opposed to a regular product), check the item's `Data` field. + +An order item with: + +* `Data.Discriminator` set to `Product`, and +* `Data.Product.ProductType` set to `Allowance` + +is an **allowance product** — the allowance amount itself, as opposed to a charge or discount. + +### "How to" use cases (identifying products) + +| "How to" use case | API operations | +| --- | --- | +| How to identify allowance product items among order items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | + ## Working with allowance discounts When you retrieve order items of type `AllowanceDiscount`, the item's `Data` field contains additional information that links the discount back to both: @@ -113,11 +96,13 @@ You can use [`Get all order items`](../operations/orderitems.md#get-all-order-it | How to find the original charge for an allowance discount | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `DiscountedOrderItemId`) | | How to find which allowance funded a discount | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId`) | +{% hint style="info" %} Discount amounts are negative. An `AllowanceDiscount` order item carries a negative `Amount`, which offsets the positive amount of the original charge on the guest's bill. +{% endhint %} ## Working with breakage and profits -When a guest checks out or an allowance expires with unspent allowance remaining, the system generates breakage items. These represent the hotel's retained revenue from unused allowance. +When a guest checks out or an allowance expires with unspent allowance remaining, the system generates breakage items. These represent the `Property`'s retained revenue from unused allowance. An [`Order item`](../operations/orderitems.md#order-item) with `Data.Discriminator` set to `AllowanceProfits` will have: @@ -135,24 +120,45 @@ An [`Order item`](../operations/orderitems.md#order-item) with `Data.Discriminat | How to get breakage items for reconciliation | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` with `AllowanceBreakage`) | | How to find which allowance generated a breakage item | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId` from the breakage item's `Data`) | +{% hint style="info" %} Breakage and contra-breakage always occur in pairs. For every `AllowanceBreakage` item, there is a corresponding `AllowanceContraBreakage` item to maintain double-entry accounting balance. Accounting integrations should expect and reconcile both. +{% endhint %} -## Identifying allowance products +## Posting charges against an allowance -To identify whether an order item is an allowance product (as opposed to a regular product), check the item's `Data` field. +External systems such as POS integrations can post charges to a guest's profile using [`Add order`](../operations/orders.md#add-order). -An order item with: +If the guest has an active allowance and the charge falls within the allowance's permitted consumption categories (matched by `AccountingCategoryId`), the system will automatically generate an `AllowanceDiscount` order item that offsets the charge — up to the remaining allowance balance. -* `Data.Discriminator` set to `Product`, and -* `Data.Product.ProductType` set to `Allowance` +Both `ProductOrders` (for products already configured in Mews) and `Items` (for custom items not configured in Mews) are supported. -is an **allowance product** — the allowance amount itself, as opposed to a charge or discount. +In both cases, the `AccountingCategoryId` on the item determines whether the charge qualifies for allowance discounting. -### "How to" use cases (identifying products) +### Linking orders to reservations + +Specify parameter `LinkedReservationId` when using [`Add order`](../operations/orders.md#add-order) to link the order to the guest's reservation. + +This is especially important for allowances because it ensures the charge and the resulting allowance discount are associated with the correct reservation and its billing automation rules. + +### "How to" use cases (posting charges) | "How to" use case | API operations | | --- | --- | -| How to identify allowance product items among order items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | +| How to post a charge that triggers an allowance discount | [`Add order`](../operations/orders.md#add-order) | +| How to post a custom item against an allowance | [`Add order`](../operations/orders.md#add-order) (use `Items` with `AccountingCategoryId`) | +| How to post an existing Mews product against an allowance | [`Add order`](../operations/orders.md#add-order) (use `ProductOrders`) | + +## Partial consumption + +If the charge amount exceeds the remaining allowance balance, the discount is applied only up to the remaining balance. The guest is responsible for the remainder. + +For example, if a guest has €30 remaining on their F&B allowance and a €45 dinner charge is posted, an `AllowanceDiscount` of €30 is created and the guest owes €15. + +## Charges that do not qualify + +If the posted item's accounting category is not in the allowance's permitted consumption list, no discount is generated. + +The charge is posted normally to the guest's bill. ## Testing your integration @@ -168,4 +174,4 @@ When testing an integration that works with allowances, verify the following sce * Confirm that breakage items are created after checkout when allowance amount remains unspent. * Reconcile the sum of allowance product amount, discount amounts, and breakage amounts — they should balance to zero. -To cross-check allowance financial data, you can use the **Mews Accounting Report** and the **Bills and Invoices Report** in Mews Operations. +To cross-check allowance financial data, you can use the [Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US) and the [Bills and Invoices Report](https://help.mews.com/s/article/bills-and-invoices-report?language=en_US) in **Mews Operations**. diff --git a/connector-api/use-cases/how-to.md b/connector-api/use-cases/how-to.md index 57f220fd..ad5ebe9f 100644 --- a/connector-api/use-cases/how-to.md +++ b/connector-api/use-cases/how-to.md @@ -45,6 +45,23 @@ This page summarises all of our 'how to' use cases, together with the main use c | How to record an alternative external payment | [Add alternative payment](../operations/payments.md#add-alternative-payment) | [Kiosk](kiosk.md) | | How to post end-of-day accounting items | [Add outlet bill](../operations/outletbills.md#add-outlet-bills) | [Point of sale](point-of-sale.md) | +## Allowances + +|
'How to' use case
|
API Operations
|
Use cases
| +| :------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | +| How to get all order items for a reservation (including allowance items) | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `ServiceOrderIds`) | [Allowances](allowances.md) | +| How to get allowance discount items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` with `AllowanceDiscount`) | [Allowances](allowances.md) | +| How to get breakage items for reconciliation | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` with `AllowanceBreakage`) | [Allowances](allowances.md) | +| How to get all allowance-related items on a bill | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `BillIds`) | [Allowances](allowances.md) | +| How to get allowance items over a period | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `ClosedUtc` or `ConsumedUtc`) | [Allowances](allowances.md) | +| How to identify allowance product items among order items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | [Allowances](allowances.md) | +| How to find the original charge for an allowance discount | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `DiscountedOrderItemId`) | [Allowances](allowances.md) | +| How to find which allowance funded a discount | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId`) | [Allowances](allowances.md) | +| How to find which allowance generated a breakage item | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId` from breakage item's `Data`) | [Allowances](allowances.md) | +| How to post a charge that triggers an allowance discount | [`Add order`](../operations/orders.md#add-order) | [Allowances](allowances.md) | +| How to post a custom item against an allowance | [`Add order`](../operations/orders.md#add-order) (use `Items` with `AccountingCategoryId`) | [Allowances](allowances.md) | +| How to post an existing Mews product against an allowance | [`Add order`](../operations/orders.md#add-order) (use `ProductOrders`) | [Allowances](allowances.md) | + ## Enterprises & Resources |
'How to' use case
|
API Operations
|
Use cases
| @@ -141,7 +158,7 @@ This page summarises all of our 'how to' use cases, together with the main use c | How to add a product order item to a customer profile | [Add order](../operations/orders.md#add-order) | [Events](events.md) | | How to add a product order to a guest profile | [Add order](../operations/orders.md#add-order) | [Upsell](upsell.md) | | How to post a charge to a customer profile | [Add order](../operations/orders.md#add-order) | [Point of sale](point-of-sale.md) | -| How to link an order to a reservation | [Add order](../operations/orders.md#add-order) (use `LinkedReservationId`) | [Events](events.md), [Kiosk](kiosk.md), [Guest technology](guest-technology.md), [Upsell](upsell.md), [Point of sale](point-of-sale.md) | +| How to link an order to a reservation | [Add order](../operations/orders.md#add-order) (use `LinkedReservationId`) | [Events](events.md), [Kiosk](kiosk.md), [Guest technology](guest-technology.md), [Upsell](upsell.md), [Point of sale](point-of-sale.md), [Allowances](allowances.md) | ## Availability Blocks diff --git a/open-api/glossary.md b/open-api/glossary.md index fbb405a0..2461d115 100644 --- a/open-api/glossary.md +++ b/open-api/glossary.md @@ -47,17 +47,6 @@ An Allowance is a packaged spending benefit that a [Property] attaches to a [Rat From an accounting perspective, the allowance represents a liability the [Property] assumes at activation: the property has committed to absorbing qualifying charges on the guest's behalf, up to the specified amount. When an allowance is activated for a [Reservation], the system posts an allowance [Product] order item (a `ProductOrder` with `ProductType = Allowance`) to the guest's [Bill]. When a qualifying charge is subsequently posted — one whose [Accounting Category] matches the allowance's permitted consumption categories — the system automatically creates an `AllowanceDiscount` order item that offsets the charge up to the remaining allowance balance. No additional API call is needed to trigger the discount. -Any unspent allowance is retained by the [Property] as additional revenue, which is known as [Breakage]. - -The following order item types are specific to allowances: - -| Order item type | What it represents | -| --- | --- | -| `ProductOrder` (with `ProductType = Allowance`) | The allowance product — the liability posted to the guest's bill when the allowance is activated. | -| `AllowanceDiscount` | A discount automatically applied to a qualifying charge, offsetting the charge up to the remaining allowance balance. | -| `AllowanceBreakage` | Unspent allowance retained by the [Property] as revenue at checkout. See [Breakage]. | -| `AllowanceContraBreakage` | The accounting contra entry for breakage, ensuring double-entry accounting integrity. | - ## ARI ARI is a general hospitality industry term and stands for [Availability], [Rates][Rate] and [Inventory]. @@ -104,7 +93,7 @@ The **Mews Booking Engine API** is one of the main APIs within the [Mews Open AP ## Breakage -Breakage is the unspent allowance that is retained by the [Property] as revenue when the allowance expires or the guest checks out. It represents the portion of the allowance that the guest did not consume during their stay. +Breakage is the unspent [Allowance] that is retained by the [Property] as revenue when the allowance expires or the guest checks out. It represents the portion of the allowance that the guest did not consume during their stay. In the [Connector API], breakage is represented by an `AllowanceBreakage` order item. For every `AllowanceBreakage` item there is a corresponding `AllowanceContraBreakage` item, which maintains double-entry accounting balance. Accounting integrations should expect and reconcile both items. From 5013ab7735a8d913e8bb6de64ab333f6ce77ef4c Mon Sep 17 00:00:00 2001 From: Denys Shylov Date: Mon, 27 Apr 2026 15:30:32 +0200 Subject: [PATCH 5/5] Remove extra space --- open-api/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/open-api/glossary.md b/open-api/glossary.md index 2461d115..fc53f182 100644 --- a/open-api/glossary.md +++ b/open-api/glossary.md @@ -43,7 +43,7 @@ ADR stands for Average Daily Rate, a standard hospitality industry metric expres ## Allowance -An Allowance is a packaged spending benefit that a [Property] attaches to a [Rate], giving guests a pre-defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room [Rate], the [Property] adds value while protecting its [ADR]. +An Allowance is a packaged spending benefit that a [Property] attaches to a [Rate], giving guests a pre-defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room [Rate], the [Property] adds value while protecting its [ADR]. From an accounting perspective, the allowance represents a liability the [Property] assumes at activation: the property has committed to absorbing qualifying charges on the guest's behalf, up to the specified amount. When an allowance is activated for a [Reservation], the system posts an allowance [Product] order item (a `ProductOrder` with `ProductType = Allowance`) to the guest's [Bill]. When a qualifying charge is subsequently posted — one whose [Accounting Category] matches the allowance's permitted consumption categories — the system automatically creates an `AllowanceDiscount` order item that offsets the charge up to the remaining allowance balance. No additional API call is needed to trigger the discount.