Create invoice item

post

https://open-api.guesty.com/v1/invoice-items/reservation/{reservationId}

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

reservationId

string

required

Reservation ID (for example 64a1f2c3e4b0a1b2c3d4e5f6).

Body Params

title

string

required

Title of the invoice item

amount

number

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.

description

string

Description of the invoice item

secondIdentifier

string

enum

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

normalType

string

enum

required

Invoice item type identifier. Read more about valid enums here

realizationDates

array of objects

length between 1 and 1

The date in which the invoice item fee is to be realized. If not provided, the system sets a default based on the earliest available date.

realizationDates

date

The date in which the invoice item fee is to be realized. Provide if you want to set a single date for the realization date. Allowed only if "from" and "to" are not provided.

from

date

The start date of the realization date range. Provide if you want to set a range for the realization dates, If you provide the "from" date, you must provide the "to" date.

date

The end date of the realization date range. Provide if you want to set a range for the realization dates, If you provide the "to" date, you must provide the "from" date.

stayIndex

integer

≥ 0

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.

isUpsellFee

boolean

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.

Responses

201

The updated folio with the new invoice item

400

The request is invalid. Common causes: invalid or missing body fields; secondIdentifier required for normalType AFE and forbidden otherwise; isUpsellFee only when normalType is AFE; multi-stay stayIndex missing/out of range or cleaning fee not on stay 0; once-only normal type already present; invalid realization dates.

403

Permission denied. The caller lacks financials access to the reservation's listing (validatePermissions returns 403 with message "Permission denied.").

Language

Credentials

Header

Loading…

Response

Click Try It! to start a request and see the response here!