> For the complete documentation index, see [llms.txt](https://docs.mews.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mews.com/connector-api/use-cases/accounting.md).

# Accounting

Accounting systems are created to record and process accounting transactions for internal and external review and auditing. Accounting systems include core modules such as accounts payable, accounts receivable, general ledger, and billing. Additional non-core modules could include reconciliation, inventory, a document approval system, expense tracking, reporting and electronic payment processing for added value.

## Initial configuration

An Accounting integration must first retrieve all configured accounting categories, i.e. all the IDs and codes required to ensure that revenue, payments and costs are correctly assigned to their designated accounting categories. Accounting categories should be created by the property in co-operation with their accountants.

| 'How to' use case                | API Operations                                                                                                   |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| How to get accounting categories | [Get all accounting categories](/connector-api/operations/accountingcategories.md#get-all-accounting-categories) |

To ensure accuracy, only data that is no longer editable by the property can be retrieved by the integration. This is determined by a period of time called the Editable History Window, which is the length of time after a bill or invoice has been closed during which it can still be amended. In fact there are two values, one for Accounting purposes and one for Operational purposes, so take the longest of the two values to ensure the data cannot be changed. Use API operation [Get configuration](/connector-api/operations/configuration.md#get-configuration) to fetch the configuration for your enterprise or property. This will include two fields representing the two windows, `AccountingEditableHistoryInterval` and `OperationalEditableHistoryInterval`.

| 'How to' use case                  | API Operations                                                                    |
| ---------------------------------- | --------------------------------------------------------------------------------- |
| How to get editable history window | [Get configuration](/connector-api/operations/configuration.md#get-configuration) |

> **Editable History Window**: For a full description and links to further information, see the [Mews Glossary for Open API users](/getting-started/glossary.md).

## Periodic update

An Accounting integration should fetch accounting items and outlet items at regular intervals, at least daily. In both cases, if `Currency` is specified, the cost of the items will be converted to that currency. The integration should also fetch all bills and invoices that must be paid and reconciled within the accounting software. These can be filtered by a specific customer, by date of creation, consumption or payment, or, in the case of invoices, by due date.

| 'How to' use case                                  | API Operations                                                                                                                                                 |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How to get accounting items consumed over a period | [Get all payments](/connector-api/operations/payments.md#get-all-payments), [Get all order items](/connector-api/operations/orderitems.md#get-all-order-items) |
| How to get order items consumed over a period      | [Get all order items](/connector-api/operations/orderitems.md#get-all-order-items)                                                                             |
| How to get payment items paid over a period        | [Get all payments](/connector-api/operations/payments.md#get-all-payments)                                                                                     |
| How to get outlet items consumed over a period     | [Get all outlet items](/connector-api/operations/outletitems.md#get-all-outlet-items)                                                                          |
| How to get bills and invoices                      | [Get all bills](/connector-api/operations/bills.md#get-all-bills)                                                                                              |

## Accounting items and reservations

It is important to understand that in Mews, accounting items are posted directly to the guest profile instead of being attached to a specific reservation. Products created under the 'Stay' service (i.e. accommodation) are used to create stay packages, while products related to any other service are used for all other postings. Only Stay products can be related back to a specific reservation, by matching their `OrderId` with the unique identifier of the relevant reservation. If products are created under any other service configured at the property, they are not related to the reservation. To retrieve a complete list of revenue items for a specific reservation, use [Get all order items](/connector-api/operations/orderitems.md#get-all-order-items) and pass the Reservation ID as parameter `ServiceOrderId` (A reservation is a type of Service Order).

| 'How to' use case                                    | API Operations                                                                     |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
| How to get a list of revenue items for a reservation | [Get all order items](/connector-api/operations/orderitems.md#get-all-order-items) |

> **Accounting item states**: Accounting items will always be assigned one of four [accounting item states](/connector-api/operations/accountingitems.md#accounting-item-state) (`Open`, `Closed`, `Inactive`, `Canceled`).

## Payout reconciliation

Payments recorded in Mews are settled by a payment service provider and paid out to the property's bank account in batches, so a single bank deposit usually covers many payments, less commissions and fees. An accounting integration that needs to tie the property's bank statement back to Mews data can retrieve those payouts and the transactions that compose them.

Start by retrieving the payouts for the period, which gives you one record per payout with its state, amount, currency, date and, where configured, the descriptor that appears on the bank statement. Then retrieve the constituent transactions for the payouts you need to break down. Each transaction states its type, the related payment where there is one, and any invoice references, which is what lets you post the individual amounts against the right bills.

| 'How to' use case                                | API Operations                                                                                  |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| How to get payouts over a period                 | [Get all payouts](/connector-api/operations/payouts.md#get-all-payouts)                         |
| How to break a payout down into its transactions | [Get all payout transactions](/connector-api/operations/payouts.md#get-all-payout-transactions) |

{% hint style="warning" %}

### Amounts are signed

A payout amount is signed from the perspective of the property's merchant balance, so a payout sending funds to the bank account is negative and a reversing entry is positive. Transaction amounts are signed the same way: a refunded charge is a negative `Charge` and a reversed commission a positive `MerchantCommission`. Take the sign into account rather than assuming a fixed direction.
{% endhint %}

{% hint style="info" %}

### Transaction dates

A payout transaction's `CreatedUtc` is the date of the underlying charge, not of the payout, so it can fall outside the interval used to filter payouts.
{% endhint %}

### Payment-level and account-level transactions

A payout transaction either belongs to a single payment or is a movement on the property's merchant balance as a whole. `PaymentId` is set accordingly:

| Type                       | Level   | `PaymentId` |
| -------------------------- | ------- | ----------- |
| `Charge`                   | Payment | Always set  |
| `MerchantCommission`       | Payment | Always set  |
| `CommissionAdjustment`     | Payment | Always set  |
| `PlatformFee`              | Account | Never set   |
| `ReserveAdjustment`        | Account | Never set   |
| `BalanceTopUp`             | Account | Never set   |
| `RollingBalanceAdjustment` | Account | Never set   |

Payment-level transactions reconcile against guest revenue and the fees charged on it. Account-level transactions are not guest revenue – for example, a Mews invoice settled from the balance, a change to the reserve, or funds added to the balance. Which accounts each type is posted to is a decision for the property and their accountant. New transaction types can be added, so base the split on whether `PaymentId` is set rather than on this list.

### Correlating transactions with payments

Group a payout's transactions by `PaymentId` to get the net amount each payment contributed to the payout. For example:

| `Type`               | `Amount` | `PaymentId`                            |
| -------------------- | -------- | -------------------------------------- |
| `Charge`             | 200.00   | `c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f` |
| `MerchantCommission` | -8.80    | `c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f` |
| `PlatformFee`        | -15.00   | –                                      |

The payment contributed 191.20. The `PlatformFee` belongs to the payout as a whole, not to the payment, so per-payment sums do not add up to the payout amount when account-level transactions are present. Include all of a payout's transactions to reconcile its full amount.

### Balance transactions

Payouts only cover money that has already been paid out. To see everything on the property's Mews Payments balance, including charges, refunds and fees that no payout has settled yet, use [Get all balance transactions](/connector-api/operations/balancetransactions.md#get-all-balance-transactions). It returns the same transactions as the payout operations, plus the unsettled ones, and each transaction states whether it is settled and which payout settled it.

| 'How to' use case                                 | API Operations                                                                                                                                   |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| How to get all balance transactions over a period | [Get all balance transactions](/connector-api/operations/balancetransactions.md#get-all-balance-transactions) (use `CreatedUtc` or `SettledUtc`) |
| How to get the transactions not yet paid out      | [Get all balance transactions](/connector-api/operations/balancetransactions.md#get-all-balance-transactions) (use `States` with `Unsettled`)    |
| How to follow a payment through to its payout     | [Get all balance transactions](/connector-api/operations/balancetransactions.md#get-all-balance-transactions) (use `PaymentIds`)                 |

Filtering by `PayoutIds` returns the same transactions as [Get all payout transactions](/connector-api/operations/payouts.md#get-all-payout-transactions) for those payouts, plus those of any payout merged into them. The `Payout` balance transaction itself carries the same `Id` and `Amount` as the payout returned by [Get all payouts](/connector-api/operations/payouts.md#get-all-payouts), including the sign: a payout that sends funds to the bank account is negative in both, see [Amounts are signed](#amounts-are-signed).

{% hint style="info" %}

#### Booked and settled dates

A balance transaction is booked when Mews records it, and settled when a payout includes it. Choose the date filter by what you post:

* `CreatedUtc` returns every transaction booked in the interval, settled or not. An unsettled transaction has no `PayoutId` or `SettledUtc` yet, and gains both when a payout settles it, so its `UpdatedUtc` changes. Use it for a daily audit trail, and read the unsettled transactions again later to pick up their payout.
* `SettledUtc` returns only transactions settled in the interval, each with the `PayoutId` of the payout that settled it. The exception is a `Payout` transaction that was not merged into another payout: it is the payout itself, so its `PayoutId` is null and its own `Id` identifies the payout. Use it when an accounting entry must not change after you post it.

`SettledUtc` is when the payout was recorded in Mews, not when the funds reached the bank account.
{% endhint %}

#### Payouts merged into another payout

Occasionally a payout is merged into a later payout. The later payout then settles both: its transactions and those of the merged payout all report it as `PayoutId` and share its `SettledUtc`, and filtering by its id returns both sets. The merged payout still appears as a `Payout` balance transaction whose `PayoutId` is the later payout, but filtering by the merged payout's id returns nothing, because every `PayoutId` refers to a payout that [Get all payouts](/connector-api/operations/payouts.md#get-all-payouts) returns.

#### Identifiers

`PaymentId` is set on balance transactions exactly as on payout transactions, see [Payment-level and account-level transactions](#payment-level-and-account-level-transactions). `GatewayIdentifier` is the payment service provider's own identifier, where Mews has one, such as the provider's payout identifier on a `Payout`. It is not set on charges, so match charges through `PaymentId`.

## Working with rebates

If an accounting item is a rebate item, then the ID for the original order item which is rebated will be stored in the item data. Specifically, an [Order item](/connector-api/operations/orderitems.md#order-item) with `Data` `Discriminator` set to "Rebate" will have `Data` `Rebate` set to the value of the `RebatedItemId`. You can then use [Get all order items](/connector-api/operations/orderitems.md#get-all-order-items) with the `OrderItemIds` filter parameter set to this ID to fetch the details about the item. Note that a rebate item can rebate another rebate item, so it may be necessary to recursively call [Get all order items](/connector-api/operations/orderitems.md#get-all-order-items) to find the original order item in the chain.

| 'How to' use case                                     | API Operations                                                                     |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
| How to find the original order item for a rebate item | [Get all order items](/connector-api/operations/orderitems.md#get-all-order-items) |

> **How can I tell if an entire Bill has been rebated?** Rebates are on an individual item-by-item basis, so if every individual order item on a Bill has been rebated then this is equivalent to the entire Bill being rebated.

## Testing your integration

Please follow our general [Usage guidelines](/connector-api/guidelines.md) for testing integrations. When testing an Accounting integration, you can cross-check whether you are correctly requesting all of the accounting information via the API by matching your data with the Mews Accounting Report. For reconciliation of all bills and invoices, you can use the Bills and Invoices Report. You can easily create export schedules to a specific target and in a desired format for both of these reports.

Before assisting any new enterprise client with connecting to your accounting integration, it's recommended that you check that they have first completed their configuration, to ensure a smoother onboarding experience.

## Additional help for working with the demo environment

> **Help Guides**:
>
> * [Creating an accounting category](https://help.mews.com/s/article/create-an-accounting-category?language=en_US)
> * [Set up a bookable service](https://help.mews.com/s/article/set-up-a-bookable-service?language=en_US)
> * [The Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US)
> * [The Bills and Invoices Report](https://help.mews.com/s/article/bills-and-invoices-report?language=en_US)
> * [Scheduling report exports](https://help.mews.com/s/article/schedule-report-exports?language=en_US)
> * [How can I connect my accounting integration?](https://help.mews.com/s/article/how-can-i-connect-my-accounting-integration?language=en_US)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mews.com/connector-api/use-cases/accounting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.