invoices.cancel
**DESTRUCTIVE**: Mark an invoice as cancelled. The PDF is preserved as an audit record. Once cancelled, the invoice cannot be resent. Use `invoices.reissue` to create a corrected replacement. Requires _confirm: true.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
reason | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
status | literal | yes | One of: cancelled |
cancelledAt | string | yes |
invoices.create_request
Mint a guest-facing invoice-request link for a reservation: creates a submission row (status pending, workflow offen) with a CSPRNG token and returns { submissionId, token, path } where path is the public form URL (/invoice-request/{token}) to send the guest. Throws 'reservation_not_found' if the reservation is not in this tenant.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
submissionId | string | yes | |
token | string | yes | |
path | string | yes |
invoices.get
Fetch a single Foyer-native invoice by UUID with joined reservation, address, tax-id and line-items. Throws 'invoice_not_found' if the row is missing or belongs to another tenant. Read-only.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
Output fields
An object keyed by string. Each value is any.
invoices.list
List Foyer-native invoices (operator inbox + history). All filters are optional: status (draft|created|sent|cancelled|reissued), reservationId (UUID), from/to (YYYY-MM-DD, matched against createdAt), limit (1-500, default 100), offset (default 0). Ordered by createdAt desc. Read-only.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
status | enum | no | One of: draft, created, sent, cancelled, reissued |
reservationId | string | no | |
from | string | no | |
to | string | no | |
limit | integer | no | |
offset | integer | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
invoices | array | yes |
invoices.list_requests
List invoice requests (Anfragen): every invoice-eligible booking joined with its latest submission, showing the operator workflow status (offen|in_bearbeitung|versandbereit|erledigt, default offen) and completeness badges (hasAddress / hasTaxId / hasInvoice). Optional filters: workflowStatus, needsInvoice (bookings with no invoice yet), search (guest name/email/reservation code), limit (1-200, default 100), offset. Read-only.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
workflowStatus | enum | no | One of: offen, in_bearbeitung, versandbereit, erledigt |
needsInvoice | boolean | no | |
search | string | no | |
limit | integer | no | |
offset | integer | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
requests | array | yes |
invoices.rechnungsdatenErneutSenden
Invoices: rechnungsdaten erneut senden. Mutation — changes data. See the input schema for argument details.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
eingereiht | boolean | yes |
invoices.reissue
**DESTRUCTIVE**: Mark an existing invoice as `reissued` and create a fresh draft for the same reservation, with a new sequential number and a `parent_invoice_id` link back to the original. The new draft starts without a PDF (placeholder file refs). Requires _confirm: true.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
weg | enum | yes | One of: stay, lokal |
fileName | string · nullable | yes | |
id | string · nullable | yes | |
number | integer · nullable | yes | |
parentInvoiceId | string · nullable | yes |
invoices.remove_request_billing
Remove billing parts from a reservation's invoice request (command-center 'Löschen'): set tax=true to soft-delete the tax-id (is_removed — none shows, survives the daily re-sync), email=true to hard-delete the billing email. Addresses have no delete. Returns the resulting billing. Mutating action — requires _confirm: true.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
tax | boolean | no | |
email | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
address | any · nullable | yes | |
taxId | any · nullable | yes | |
email | string · nullable | yes |
invoices.request_billing
Collected billing data for a reservation's invoice request: the latest billing address (name/company, lines, postal code, city, country, isBusiness) and tax-id (value + kind: ust_idnr|steuernummer). Both nullable when the guest hasn't provided them. Read-only.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
address | any · nullable | yes | |
taxId | any · nullable | yes | |
email | string · nullable | yes |
invoices.request_stats
Invoice-request pipeline counts for the Anfragen tabs: total + per workflow status (offen, in_bearbeitung, versandbereit, erledigt) + needsInvoice (eligible bookings with no invoice yet). Read-only.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
total | number | yes | |
offen | number | yes | |
inBearbeitung | number | yes | |
versandbereit | number | yes | |
erledigt | number | yes | |
needsInvoice | number | yes |
invoices.send
Email the invoice to the guest. This is a real send over the configured channel. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
toEmail | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
via | enum | yes | One of: gmail, brevo, postmark |
messageId | string | yes | |
sentAt | string · nullable | yes |
invoices.send_smtp
**IRREVERSIBLE**: send a Foyer-native invoice PDF to the guest via email. Uses Postmark BYOK if the tenant has configured a token, else falls back to the Gmail SMTP relay. Marks the invoice as 'sent' on success. Once the remote MTA accepts the message there is no way to recall it. Mutating action — requires _confirm: true.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
toEmail | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
via | enum | yes | One of: gmail, brevo, postmark |
messageId | string | yes | |
sentAt | string · nullable | yes |
invoices.setRequestStatus
Invoices: set request status. Mutation — changes data. See the input schema for argument details.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
workflowStatus | enum | yes | One of: offen, in_bearbeitung, versandbereit, erledigt |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
submissionId | string | yes | |
workflowStatus | enum | yes | One of: offen, in_bearbeitung, versandbereit, erledigt |
invoices.stats
Counters for the operator dashboard stat-strip: total + per-status (draft, created, sent, cancelled, reissued) for the caller's tenant. Read-only.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
totalCount | number | yes | |
draftCount | number | yes | |
createdCount | number | yes | |
sentCount | number | yes | |
cancelledCount | number | yes | |
reissuedCount | number | yes |
invoices.submitForm
Invoices: submit form. Mutation — changes data. See the input schema for argument details.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
firstName | string | yes | |
lastName | string | yes | |
email | string | yes | |
isBusiness | boolean | no | Default: false |
company | string | no | |
line1 | string | yes | |
line2 | string | no | |
postalCode | string | yes | |
city | string | yes | |
country | string | no | |
taxIdValue | string | no | |
taxIdKind | enum | no | One of: ust_idnr, steuernummer |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
submitCount | integer | yes |
invoices.updateRequestBilling
Invoices: update request billing. Mutation — changes data. See the input schema for argument details.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
address | object · nullable | no | |
address.name | string | yes | |
address.line1 | string · nullable | no | |
address.line2 | string · nullable | no | |
address.postalCode | string · nullable | no | |
address.city | string · nullable | no | |
address.country | string · nullable | no | |
address.isBusiness | boolean | no | |
taxId | object · nullable | no | |
taxId.value | string | yes | |
taxId.kind | enum | yes | One of: ust_idnr, steuernummer |
email | string · nullable | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
address | object · nullable | yes | |
address.name | string | yes | |
address.line1 | string · nullable | yes | |
address.line2 | string · nullable | yes | |
address.postalCode | string · nullable | yes | |
address.city | string · nullable | yes | |
address.country | string · nullable | yes | |
address.isBusiness | boolean | yes | |
address.legacyId | string · nullable | yes | |
address.anStayUebertragenAt | string · nullable | yes | |
address.anStayFehler | string · nullable | yes | |
taxId | object · nullable | yes | |
taxId.value | string | yes | |
taxId.kind | string | yes | |
taxId.legacyId | string · nullable | yes | |
taxId.anStayUebertragenAt | string · nullable | yes | |
taxId.anStayFehler | string · nullable | yes | |
email | string · nullable | yes |
invoices.update_address
Update the billing address on a Foyer-native invoice. Inserts a new invoice_addresses row (append-only — old rows stay for audit) and repoints invoices.address_id at it. Use to correct typos / fix incomplete guest submissions. Mutating action — requires _confirm: true.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
address | object | yes | |
address.name | string | yes | |
address.line1 | string | no | |
address.line2 | string | no | |
address.postalCode | string | no | |
address.city | string | no | |
address.country | string | no | |
address.isBusiness | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
invoices.update_email
Set or replace the billing email for a reservation. Inserts a new invoice_emails row (append-only) — send-time logic resolves the latest email by reservation, so this cascades to all future invoices for that stay. Mutating action — requires _confirm: true.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
email | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
invoices.update_tax_id
Set or replace the tax ID on a Foyer-native invoice. Inserts a new invoice_tax_ids row (append-only — old rows stay for audit) and repoints invoices.tax_id_id at it. `kind` distinguishes USt-IdNr (EU VAT) from Steuernummer (DE local). Mutating action — requires _confirm: true.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
value | string | yes | |
kind | enum | yes | One of: ust_idnr, steuernummer |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |