diff --git a/connector-api/SUMMARY.md b/connector-api/SUMMARY.md index 1852aa40..9e881e0e 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/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 new file mode 100644 index 00000000..662267d2 --- /dev/null +++ b/connector-api/use-cases/allowances.md @@ -0,0 +1,177 @@ +# Allowances + +## Overview + +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. + +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 **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 + +## 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 — 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 + +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. +{% endhint %} + +## Retrieving allowance-related order items + +Use [`Get all order items`](../operations/orderitems.md#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, for example, `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`](../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`) | + +## 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: + +* the original charge +* the allowance product that funded it + +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 which consumed the item. + +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. + +### "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`](../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 `Property`'s retained revenue from unused allowance. + +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 amount was not fully consumed. +* `AllowanceProfitType` — the type of profit entry, which can be one of: + * `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. + +### "How to" use cases (breakage and profits) + +| "How to" use case | API operations | +| --- | --- | +| 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 %} + +## 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. + +## Testing your integration + +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: + +* 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 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 [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 cf35edb7..fc53f182 100644 --- a/open-api/glossary.md +++ b/open-api/glossary.md @@ -37,6 +37,16 @@ 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. + ## ARI ARI is a general hospitality industry term and stands for [Availability], [Rates][Rate] and [Inventory]. @@ -81,6 +91,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 +607,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 +618,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