GUguesty
Invoice Items

Create invoice item

Changed on

Adds an invoice item to the reservation's folio and returns the updated folio.

Use this when you need to add a one-off charge (for example an additional fee, cleaning fee, or tax) to an existing reservation. The folio is recalculated after the item is added.

Common 400 causes: invalid or missing body fields; secondIdentifier required for normalType AFE and forbidden otherwise; isUpsellFee only allowed when normalType is AFE; on multi-stay reservations stayIndex is required and must be in range (cleaning fee CF only on stay 0); a once-only normal type already exists on the reservation (or stay); invalid realization dates.

post/invoice-items/reservation/{reservationId}

Request

  • Base URL
    https://open-api.guesty.com/v1
  • URL
    https://open-api.guesty.com/v1/invoice-items/reservation/{reservationId}
  • Auth
    API key in header authorization

Path parameters

reservationIdstring required
Example:64a1f2c3e4b0a1b2c3d4e5f6

Reservation ID (for example 64a1f2c3e4b0a1b2c3d4e5f6).

Request body

titlestring required

Title of the invoice item

amountnumber required

Amount to charge for the invoice item, in the reservation currency (ISO 4217, for example USD or EUR). There is no separate currency field — the server uses the reservation folio currency.

descriptionstring

Description of the invoice item

secondIdentifier'ACTIVITIES' | 'ADDITIONAL_BED' | 'ADDITIONAL_CHARGE' | 'AIR_CONDITIONING' | 'BABY_BED' | 'BEVERAGE' | 'BOOKING_FEE' | 'BREAKFAST' | 'BUSINESS_CENTER' | 'CAR_RENTAL' | 'CHEF' | 'CLEANING' | 'CLUB_CARD' | 'COMMISSION_CHARGE' | 'COMMUNITY' | 'CONCIERGE' | 'CREDIT_CARD_PROCESSING_FEE' | 'DAMAGE_CHARGE' | 'DAMAGE_WAIVER' | 'DEPOSIT' | 'DIRECT_SERVICE' | 'DOCK_FEE' | 'EARLY_CHECK_IN' | 'EARLY_CHECKOUT' | 'ELECTRICITY' | 'EQUIPMENT_RENTAL' | 'FLIGHTS' | 'FOOD' | 'GIFT_BASKET' | 'GOLF_CART_RENTAL' | 'GUEST_SERVICE' | 'GUESTY_BASIC_TRAVEL_COVERAGE' | 'GUESTY_EXTENDED_TRAVEL_COVERAGE' | 'GUESTY_SHIELD' | 'HEATING' | 'HOMEOWNERS_ASSOCIATION' | 'HOT_TUB' | 'HOUSEKEEPING' | 'INSURANCE' | 'PROPERTY_INSURANCE' | 'INTERNET' | 'LATE_CHECK_IN' | 'LATE_CHECKOUT' | 'LAUNDRY' | 'LINENS' | 'MANAGEMENT' | 'MEAL' | 'MEET_AND_GREET' | 'MINIBAR' | 'MISCELLANEOUS' | 'OIL' | 'PARKING' | 'PAYMENT_FEE' | 'PET' | 'POOL' | 'POOL_HEATING' | 'RESERVATION_FEE' | 'RESORT' | 'SERVICE' | 'SHIPPING' | 'SPA' | 'TOILETRIES' | 'TOTAL_PAYOUT_BASED' | 'TOUR' | 'TOWELS' | 'TRANSFER' | 'TRANSPORTATION' | 'UTILITY_FEE' | 'VALET' | 'VIP_SERVICES' | 'WATER' | 'WELLNESS' | 'WIFI' | 'WOOD'

When normalType AFE (Additional Fee) is selected, secondIdentifier is required, else it's forbidden. Second identifier is the type of the additional fee

normalType'CF' | 'CFE' | 'PCM' | 'LT' | 'CT' | 'VAT' | 'GST' | 'TT' | 'TAX' | 'ST' | 'COT' | 'OCT' | 'TOT' | 'HSHAT' | 'HST' | 'MAT' | 'AFE' required

Invoice item type identifier. Read more about valid enums <a href="https://open-api-docs.guesty.com/docs/valid-enumerations">here</a>

stayIndexinteger

Which stay this charge belongs to when a guest changes units during one reservation (0 = first stay, 1 = second, and so on).

  • Single-stay (folio has no mid-stay perStayTotals): omit stayIndex. If sent, it is ignored and not stored.
  • Multi-stay (folio has perStayTotals): stayIndex is required. Omitting it returns 400 (Stay index is required when perStayTotals is present). An index outside the stay count returns 400.
  • Cleaning fee (CF) on multi-stay: only stayIndex 0 is allowed; any other stay returns 400 (Cleaning fee can only be added to the first stay (stayIndex 0)).
  • Discovery: read Guest Folio overview perStayTotals (each element’s stayIndex) to see whether the reservation is multi-stay and which indexes are valid; existing lines also expose stayIndex on GET /guest-folio/invoice-items when present.
isUpsellFeeboolean

When true, marks this invoice item as an upsell fee (sold after booking). Only allowed when normalType is AFE; any other normal type returns 400.

Example request

{
  "title": "Extra cleaning",
  "amount": 100,
  "description": "Late checkout fee for the guest",
  "secondIdentifier": "CLEANING",
  "normalType": "AFE",
  "realizationDates": [
    {
      "date": "2026-01-15",
      "from": "2026-01-15",
      "to": "2026-01-20"
    }
  ]
}

Response

The updated folio with the new invoice item

Changes

  • 3122b8618183Revision changes
    • breaking

      the request property's minItems was increased to 1

    • breaking

      the // request property format changed from no format to date

    • breaking

      the // request property format changed from no format to date

    • breaking

      the // request property format changed from no format to date

    • breaking

      the request property type changed from number to integer

    • breaking

      removed the media type application/json for the response with the status

    • breaking

      removed the success response with the status

    • warning

      the request property's min was set to 0.00

    • info

      added the new TOTAL_PAYOUT_BASED enum value to the request property

    • info

      added the non-success response with the status