Add allowances use cases docs#45
Open
DenysShylov wants to merge 6 commits intomainfrom
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new Connector API use-case documentation page describing how allowances work end-to-end (posting charges that consume allowances, retrieving related order items, and interpreting discounts/breakage/profit items) as part of the GA documentation push.
Changes:
- Introduces a new “Allowances Extended Use Cases” page under
connector-api/use-cases/. - Documents allowance-related order item types, posting flows via Add order, and retrieval via Get all order items.
- Adds testing/reconciliation guidance for allowance scenarios.
|
|
||
| * by reservation using `ServiceOrderIds` | ||
| * by bill using `BillIds` | ||
| * by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` |
There was a problem hiding this comment.
The time-period filters list omits ConsumedUtc (and CanceledUtc), but Get all order items supports these and later in this page you reference ConsumedUtc. To avoid confusion, align the list with the actual available filters (Created/Updated/Consumed/Canceled/Closed).
Suggested change
| * by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` | |
| * by time period using `CreatedUtc`, `UpdatedUtc`, `ConsumedUtc`, `CanceledUtc`, or `ClosedUtc` |
Member
There was a problem hiding this comment.
suggestion: Let's treat it as a list of examples
Suggested change
| * by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` | |
| * by time period using, for example, `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` |
Comment on lines
+5
to
+9
| 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]. |
There was a problem hiding this comment.
This page uses reference-style links like [Property], [Rate], [ADR], etc., but there are no link reference definitions in this document, so these will render as literal bracketed text (or broken links) in Markdown/GitBook. Convert them to normal text, or add explicit links (e.g., to the Open API glossary), or define the references at the bottom of the page.
Member
There was a problem hiding this comment.
Yeah, just wanted to highlight that. I assume it was brought over from Glossary? Just remove those links for now and I will later adjust the use case page for links to glossary.
jnv
requested changes
Apr 23, 2026
Member
jnv
left a comment
jnv
left a comment
There was a problem hiding this comment.
I think it goes in good direction. Beside my comments, please also:
- Update the README in use-cases directory https://docs.mews.com/connector-api/use-cases
- Update list of How to use cases in how-to.md: https://docs.mews.com/connector-api/use-cases/how-to
- Check your added files against contribution guidelines (or even AGENTS.md) – feed it to Copilot or Claude and it should catch some obvious style and tone issues.
Comment on lines
+52
to
+60
| 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. | | ||
|
|
Member
There was a problem hiding this comment.
issue: This explanation goes too deep into the specific implementation and should be left out of the glossary (it's appropriate in the use case doc).
|
|
||
| ## Breakage <a href="#Breakage" id="Breakage"></a> | ||
|
|
||
| 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. |
Member
There was a problem hiding this comment.
suggestion: Link to Allowance
Suggested change
| 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. |
Comment on lines
+5
to
+9
| 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]. |
Member
There was a problem hiding this comment.
Yeah, just wanted to highlight that. I assume it was brought over from Glossary? Just remove those links for now and I will later adjust the use case page for links to glossary.
| @@ -0,0 +1,171 @@ | |||
| # Allowances Extended Use Cases | |||
Member
There was a problem hiding this comment.
issue: Rename just to Allowances (I suspect this title is carried over from Confluence page?)
Suggested change
| # Allowances Extended Use Cases | |
| # Allowances |
Member
There was a problem hiding this comment.
suggestion: beside Copilot comments, I'd suggest reordering the individual use case sections in the order of understand -> read -> interpret -> post -> test. The assumption is that users will most likely run into Allowance when fetching data, while posting the allowances & co. will affect only a subset of those users.
Here's my proposal for reordering the sections:
- Overview
understand:
2. Key concepts
read:
3. Retrieving allowance-related order items
4. Identifying allowance products (read)
interpret:
5. Working with allowance discounts (interpret)
6. Working with breakage and profits (interpret)
post:
7. Posting charges against an allowance
8. Partial consumption /edge case/
9. Charges that do not qualify /edge case/
test:
10. Testing your integration
|
|
||
| * by reservation using `ServiceOrderIds` | ||
| * by bill using `BillIds` | ||
| * by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` |
Member
There was a problem hiding this comment.
suggestion: Let's treat it as a list of examples
Suggested change
| * by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` | |
| * by time period using, for example, `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` |
| * 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. |
Member
There was a problem hiding this comment.
issue: Bold should be used for product names (check contribution guidelines). But, you can link to help articles.
Suggested change
| 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**. |
DenysShylov
commented
Apr 27, 2026
Contributor
Author
DenysShylov
left a comment
DenysShylov
left a comment
There was a problem hiding this comment.
Fixed all the comments, validated with claude so some extra quotes and formatting updated. The thing I am confused a bit is {% hint style="info" %}, in the "compiled" md view it is still the same syntax, hope it will look better on the page.
| | --- | --- | | ||
| | 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`) | |
There was a problem hiding this comment.
This row suggests filtering Types with only AllowanceBreakage, but breakage and contra-breakage occur in pairs. For reconciliation you likely need both AllowanceBreakage and AllowanceContraBreakage (and/or explicitly state that the contra item must also be fetched separately).
Suggested change
| | How to get breakage items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` filter with `AllowanceBreakage`) | | |
| | How to get breakage items | [`Get all order items`](../operations/orderitems.md#get-all-order-items) (use `Types` filter with `AllowanceBreakage` and `AllowanceContraBreakage`) | |
Comment on lines
+118
to
+125
| | "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 %} |
There was a problem hiding this comment.
For “breakage items for reconciliation”, the filter guidance uses only Types = AllowanceBreakage. Since the docs below state breakage and contra-breakage always occur in pairs, this should include AllowanceContraBreakage as well (or clarify how to retrieve/reconcile the contra entry).
Comment on lines
+50
to
+58
| | <div style="width:350px">'How to' use case</div> | <div style="width:200px">API Operations</div> | <div style="width:150px">Use cases</div> | | ||
| | :------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | | ||
| | 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) | |
There was a problem hiding this comment.
This “breakage items for reconciliation” entry suggests filtering Types with only AllowanceBreakage, but reconciliation typically needs the paired AllowanceContraBreakage item too. Consider including both types (or clarifying that both should be retrieved/reconciled).
Suggested change
| | <div style="width:350px">'How to' use case</div> | <div style="width:200px">API Operations</div> | <div style="width:150px">Use cases</div> | | |
| | :------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | | |
| | 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) | | |
| | <div style="width:350px">'How to' use case</div> | <div style="width:200px">API Operations</div> | <div style="width:150px">Use cases</div> | | |
| | :------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | | |
| | 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` and `AllowanceContraBreakage`) | [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) | |
Comment on lines
+5
to
+10
| 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`. | ||
|
|
There was a problem hiding this comment.
This page uses inline code formatting for domain concepts (e.g., Property, Rate, Reservation, Bill, Breakage). In other Connector API use-case pages, backticks are generally reserved for API field names / enum values (e.g., AccountingEditableHistoryInterval in connector-api/use-cases/accounting.md:13), while domain terms are plain text. Consider removing backticks from non-API terms to match the existing documentation style and improve readability.
Comment on lines
+46
to
+48
| 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. |
There was a problem hiding this comment.
In the new Allowance glossary entry, there’s a double space in “the [Property] adds …” and later “the property has committed …” drops the capitalization/linking used elsewhere. Please remove the extra space and keep this consistent as “[Property] has committed …”.
Suggested change
| 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. | |
| 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: [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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
https://mews.atlassian.net/browse/RMS-7630
Add allowances use cases docs. We are going GA, it's time to add docs in use cases.
Checklist
SUMMARY.mdupdated if new pages addedAPI