--- title: "Get invoice items" method: GET path: "/guest-folio/invoice-items" tags: ["Guest Folio"] --- # Get invoice items `GET /guest-folio/invoice-items` ## Request - Base URL: `https://open-api.guesty.com/v1` - URL: `https://open-api.guesty.com/v1/guest-folio/invoice-items` - Auth: API key in header `authorization` Retrieves invoice items for one or more reservations. **Field selection** You must specify at least one field to return via the `fields` query parameter. `id` is always included on every invoice item and `reservationId` and `currency` are always included at the result level — none of these need to be listed in `fields`. Use the exact enum values listed — any unrecognized field name results in a 400 error. Nested fields must be requested using their full dot-notation path. The parent name alone (e.g. `adjustments`) is not a valid selection; you must specify the leaf fields you need (e.g. `adjustments.amount`, `adjustments.type`). A field listed in `fields` may still be absent from a given invoice item when no value is stored for that item. For example, `description`, `logs`, and `realizationDates` are omitted rather than returned as `null` when not set. Scalar arrays such as `adjustments` and `nightsBreakdown` may be omitted or empty depending on the item type and data. See each field's description for details on when it may be absent. **Response structure** Each result groups all invoice items for one reservation under a `reservationId` key and includes the reservation `currency`. The `invoiceItems` array contains one entry per invoice item on that reservation, with only the requested fields populated. An empty `invoiceItems` array means the reservation exists but has no invoice items. Results order and invoice item ordering within the array is not guaranteed. **Currency and monetary amounts** All monetary fields (`totalPrice`, `nightsSubtotal`, `adjustments.amount`, `nightsBreakdown.basePrice`, etc.) are in the ISO 4217 currency returned in the top-level `currency` field for that reservation. Values are returned with full precision as stored; no additional rounding is applied by this endpoint. Tax treatment follows the channel and reservation configuration and is reflected in the stored amounts. Monetary fields on the same invoice item do not necessarily reconcile arithmetically. For example, `totalPrice` is the final stored amount after all adjustments, while `nightsSubtotal` is the sum of per-night prices before adjustments — these will differ whenever adjustments exist. Tax treatment, deductions (`isDeducted`, `isDeductedV2`), and account-level configuration each affect stored amounts independently. Treat each field as the authoritative figure for its own semantic rather than attempting to derive one field's value from another. **Partial success** A reservation ID is placed in `notFound` when the reservation does not exist. The response always returns HTTP 200. Found records appear in `results`; unavailable IDs are listed in `notFound`. **Batching** A maximum of **200 reservation IDs** can be submitted per request. For larger datasets, split reservation IDs into batches of up to 200 and call this endpoint once per batch. **Example usage** Fetch the line item type, total price, and per-night breakdown for two reservations: ``` GET /v1/guest-folio/invoice-items?reservationIds=64a1f2c3e4b0a1b2c3d4e5f6,64a1f2c3e4b0a1b2c3d4e5f7&fields=normalType,totalPrice,nightsBreakdown.date,nightsBreakdown.basePrice ``` ## Query parameters - `reservationIds` string[], required - `fields` string[], required ## Response `200` Invoice items grouped by reservation for each reservation ID that was found. Results order is not guaranteed. Each result contains only the fields requested via `fields`, plus `id` on every invoice item, and `reservationId`/`currency` at the group level. Reservation IDs that were not found are listed in `notFound`. - object - `results` object[], required: One entry per reservation ID that was found. Results are returned in the same order as the input `reservationIds`. Each entry contains `reservationId`, `currency`, and the `invoiceItems` array (empty when no items exist for that reservation). - `reservationId` string, required: The reservation ID these invoice items belong to. Always returned regardless of the fields requested. - `currency` string, required: ISO 4217 currency code for all monetary amounts on this reservation (e.g. `USD`, `EUR`, `GBP`). Monetary fields (`totalPrice`, `nightsSubtotal`, `adjustments.amount`, `nightsBreakdown.basePrice`, etc.) are stored and returned in this currency with full precision as stored; no additional rounding is applied by this endpoint. Always returned regardless of the fields requested. - `invoiceItems` object[], required: All invoice items for this reservation. Each item contains only the fields that were requested via the `fields` query parameter, plus `id` which is always included. An empty array means the reservation has no invoice items. - `id` string, required: Unique identifier for this invoice item on the reservation folio. Always returned on every invoice item, regardless of the fields requested. - `normalType` 'AF' | 'AFO' | 'AFED' | 'ARC' | 'LOSD' | 'GCD' | 'CO' | 'PRO' | 'CF' | 'PCM' | 'CM' | 'TAXD' | 'LT' | 'CT' | 'TT' | 'GST' | 'VAT' | 'TTH' | 'LGT' | 'HT' | 'TAF' | 'TRT' | 'AFE' | 'PF' | 'CFE' | 'RT' | 'ST' | 'COT' | 'OCT' | 'TOT' | 'HSHAT' | 'HST' | 'MAT' | 'SDC' | 'TAX' | 'MARF' | 'MAR' | 'AFWD' | 'AFD' | 'AFA' | 'EPF' | 'ADF' | 'OTHER' | 'OT': Code for the type of charge on the guest folio. Treat this schema’s `enum` as the source of truth for codes returned by this endpoint — it includes `ADF` and `OT`. Do not rely on the Valid Enumerations guide’s Invoice Items table for completeness (that guide may omit `ADF` / `OT` and may link deprecated invoice-items v1 docs). Common examples: `AF` (accommodation fare), `CF` (cleaning fee), `CT` (city tax), `AFE` (additional fee), `MARF` (markup on fees). You may also see: - `AFD` — accommodation fare discount - `AFA` — accommodation fare adjustment - `EPF` — extra person fee - `ADF` — additional discount line - `OTHER` — other non-tax charge - `OT` — other tax (not the same as `OTHER`, which is not a tax; also not the same as `TAX`, another code used for an other/generic tax) See the enum for the full list of possible codes. - `origin` 'MANUAL' | 'AUTOMATIC' | 'CHANNEL': Indicates how this line item was created. `MANUAL` — entered by a user. `AUTOMATIC` — generated by Guesty business logic. `CHANNEL` — received from the booking channel (e.g. Airbnb, Booking.com). - `title` string: Display name for this line item as shown on the guest folio. - `description` string: Additional notes or details for this line item. - `secondIdentifier` string: Sub-type for line items that have multiple variants. For example, an additional fee (`AFE`) may have a sub-type of `INTERNET` or `PARKING`. - `totalPrice` number: Final total amount for this line item, including all nightly amounts and any adjustments. Stored and returned in the reservation currency (see parent `currency` field) with full precision as stored; no additional rounding is applied by this endpoint. - `nightsSubtotal` number: Total of the nightly amounts before any adjustments are applied. Stored and returned in the reservation currency with full precision as stored. - `isDeducted` boolean: Whether this line item is deducted from the accommodation fare. When true, this item's amount was reduced from the accommodation fare. - `isDeductedV2` boolean: Whether this item's amount was reduced from the accommodation fare under the updated deduction logic (v2). - `stayIndex` integer: Zero-based index identifying which stay segment this item belongs to. Relevant for mid-stay reservations where the guest changes units during their stay. - `listingId` string: ID of the listing (property unit) this line item is associated with. - `realizationDates` object[]: Date range over which this line item is financially recognized for accounting purposes. Each entry defines a period with a start date and an optional end date. Omitted when no realization dates are configured for this item. Use dot notation to request individual sub-fields: `realizationDates.date`, `realizationDates.to`. - `date` string, date: Start date of the realization period, in YYYY-MM-DD format. - `to` string, date: End date of the realization period, in YYYY-MM-DD format. Absent for single-date realizations. - `markupBreakdown` object[]: Markup breakdown for line items of type `MARF` (markup on fees). Each entry describes one fee that this markup was applied to, including the fee type and the markup amount. Only present on items of type `MARF`; omitted on all other item types even when requested. Use dot notation to request individual sub-fields: `markupBreakdown.invoiceItemId`, `markupBreakdown.amount`, etc. - `invoiceItemId` string: ID of the fee invoice item this markup entry is calculated on. - `normalType` string: Line item type code of the fee this markup is applied to (e.g. `AFE` for additional fee, `CF` for cleaning fee). - `secondIdentifier` string: Sub-type of the fee this markup is applied to. - `amount` number: The markup amount applied to this fee. Stored and returned in the reservation currency with full precision as stored. - `logs` object: Audit log timestamps and authorship for this line item. Omitted when no audit log data is stored for this item. Use dot notation to request individual sub-fields: `logs.createdAt`, `logs.updatedAt`, `logs.createdBy`, `logs.updatedBy`. - `createdAt` string, date-time: Timestamp when this invoice item was created, in ISO 8601 format. - `updatedAt` string, date-time: Timestamp of the last update to this invoice item, in ISO 8601 format. - `createdBy` string: The user or system that created this invoice item. - `updatedBy` string: The user or system that last updated this invoice item. - `nightsBreakdown` object[]: Per-night price breakdown for this line item, showing the base price for each night of the stay. Omitted when the item has no stored nightly breakdown (e.g. flat-fee items with a single total and no per-night prices). Use dot notation to request individual sub-fields: `nightsBreakdown.date`, `nightsBreakdown.basePrice`. - `date` string, date: The calendar date for this nightly price entry, in YYYY-MM-DD format. - `basePrice` number: The base price amount for this specific night. Stored and returned in the reservation currency (see parent `currency` field) with full precision as stored; no additional rounding is applied by this endpoint. - `adjustments` object[]: Price adjustments applied to this line item beyond the base channel price. Each entry describes one adjustment with its amount, type, creator, and an optional per-night breakdown. Returned as an empty array `[]` when the item has no adjustments. Omitted entirely when `adjustments.*` fields are not included in the `fields` request parameter. Use dot notation to request individual sub-fields: `adjustments.amount`, `adjustments.type`, `adjustments.nightsBreakdown.date`, etc. - `amount` number: Total adjustment amount. Negative values represent reductions. Stored and returned in the reservation currency (see parent `currency` field) with full precision as stored; no additional rounding is applied by this endpoint. - `creationMethod` 'MANUAL' | 'AUTO_CALCULATED': How this adjustment was created. - `type` 'NIGHTLY_RATE' | 'TOTAL_AMOUNT': Adjustment type. `TOTAL_AMOUNT` adds a flat amount on top of the line item total. `NIGHTLY_RATE` is created when a reservation change affects an item whose nightly amounts are already locked by accounting — the difference is spread across individual nights rather than changing the original nightly prices. - `userName` string: The user or system that created this adjustment. - `createdAt` string, date-time: Timestamp when this adjustment was created, in ISO 8601 format. - `description` string: Human-readable reason or label for this adjustment. - `nightsBreakdown` object[]: Per-night breakdown of this adjustment. Present when `type` is `NIGHTLY_RATE`; each entry shows the adjustment amount for one night. Omitted on `TOTAL_AMOUNT` adjustments. - `date` string, date: The calendar date for this nightly adjustment entry, in YYYY-MM-DD format. - `basePrice` number: The adjustment amount applied to this specific night. Stored and returned in the reservation currency with full precision as stored. - `notFound` string[], required: Reservation IDs from the request for which no data was found. The request returns HTTP 200 even when some or all IDs are not found. ## Other responses - `400`: The request is invalid. Common causes: missing or empty `reservationIds`, more than 200 reservation IDs submitted, missing or empty `fields`, or an unrecognized field name in `fields`. ## Changes - **2026-11-03** `3122b8618183`: 1 info - endpoint added [Operation history](https://skmtc.dev/guesty/apis/guesty-open-api/changes/guest-folio/invoice-items/get.md) --- [API](https://skmtc.dev/guesty/apis/guesty-open-api.md) - [All operations](https://skmtc.dev/guesty/apis/guesty-open-api/llms.txt) - [OpenAPI document](https://skmtc.dev/guesty/apis/guesty-open-api/revisions/3122b8618183?raw)