Conversation
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.
| | "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`) | | ||
|
|
There was a problem hiding this comment.
This "How to" table uses the || ... table syntax, which adds an unintended empty first column. Use the standard | ... | table formatting to ensure consistent rendering.
| 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. | ||
|
|
There was a problem hiding this comment.
This section introduces profits as being generated when there is unspent credit remaining, but then lists AllowanceLoss / AllowanceContraLoss as possible AllowanceProfitType values. Either explain when loss entries are produced (so readers know when to expect them), or scope the list/section to breakage-only to match the described scenario.
| | "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`) | | ||
|
|
There was a problem hiding this comment.
This "How to" table uses the || ... table syntax, which adds an extra empty column and is inconsistent with other docs tables. Reformat to the standard single-pipe markdown table style.
| # Allowances Extended Use Cases | ||
|
|
||
| ## Overview |
There was a problem hiding this comment.
This page is a new use-case doc, but it isn't referenced from connector-api/SUMMARY.md (and won't appear in the left-nav in GitBook builds). Add an entry for it under the appropriate "Use cases" section so it's discoverable.
| @@ -0,0 +1,171 @@ | |||
| # Allowances Extended Use Cases | |||
There was a problem hiding this comment.
The H1 line appears to include a UTF-8 BOM / zero-width character before # (shown as �/ in some editors). This can break heading parsing and TOC generation in some markdown renderers; remove the BOM so the line starts exactly with #.
| # Allowances Extended Use Cases | |
| # Allowances Extended Use Cases |
|
|
||
| * 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).
| * by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` | |
| * by time period using `CreatedUtc`, `UpdatedUtc`, `ConsumedUtc`, `CanceledUtc`, or `ClosedUtc` |
There was a problem hiding this comment.
suggestion: Let's treat it as a list of examples
| * by time period using `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` | |
| * by time period using, for example, `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` |
| | "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`) | |
There was a problem hiding this comment.
This "How to" table uses the || ... table syntax, which creates an extra empty column and can render incorrectly. Please switch it to the standard markdown table format used elsewhere in the Connector API use cases.
| | "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`) | | ||
|
|
There was a problem hiding this comment.
This "How to" table uses the || ... table syntax (empty first column). Reformat to the standard | ... | table format used across the Connector API use-case pages so it renders consistently.
| | "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`) | | ||
|
|
There was a problem hiding this comment.
This "How to" table uses the || ... table syntax, which introduces an unintended empty column and may not render as expected in GitBook. Use the standard single-pipe markdown table format consistent with other pages under connector-api/use-cases/.
| 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. |
There was a problem hiding this comment.
Internal links in this page use absolute https://docs.mews.com/connector-api/... URLs. The rest of the Connector API docs use relative links (e.g. ../operations/orders.md#add-order), which makes local previews and branch builds work reliably. Consider switching these to relative links throughout this page.
|
|
||
| ## Allowance <a href="#Allowance" id="Allowance"></a> | ||
|
|
||
| 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]. |
There was a problem hiding this comment.
There is an extra double space between [Property] and adds.
| 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]. |
| 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.
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.
|
|
||
| ## 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]. |
There was a problem hiding this comment.
There is an extra double space between [Property] and adds.
| 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]. |
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.
| 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. | | ||
|
|
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. |
There was a problem hiding this comment.
suggestion: Link to Allowance
| 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. |
| 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.
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 | |||
There was a problem hiding this comment.
issue: Rename just to Allowances (I suspect this title is carried over from Confluence page?)
| # Allowances Extended Use Cases | |
| # Allowances |
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` |
There was a problem hiding this comment.
suggestion: Let's treat it as a list of examples
| * 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. |
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.
| 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**. |
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