Issue invoice
const url = 'https://api.aerandil.com/v1/actions/hospitality.action.issue_invoice/apply';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","params":{"issued_on":"2026-04-15","note":"example","recipient_address_override":{"city":"example","country":"example","line1":"example","line2":"example","postal_code":"example","region":"example"},"recipient_kind":"person","recipient_name_override":"example","recipient_tax_identifier_override":"example"},"return_modified":false,"target":{"id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","object_type":"hospitality.folio"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.aerandil.com/v1/actions/hospitality.action.issue_invoice/apply \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "issued_on": "2026-04-15", "note": "example", "recipient_address_override": { "city": "example", "country": "example", "line1": "example", "line2": "example", "postal_code": "example", "region": "example" }, "recipient_kind": "person", "recipient_name_override": "example", "recipient_tax_identifier_override": "example" }, "return_modified": false, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "hospitality.folio" } }'Turn a sealed folio into the numbered document its recipient keeps — a tax invoice, or a credit note when the target is a rebate folio whose original was invoiced. Allocates the next value from the property’s series inside this transaction (dense: a failed issue releases the number rather than burning it), snapshots the issuer and the recipient onto the document so a later profile edit cannot rewrite it, copies every charge as a printed line, and derives the per-rate tax bands from the charges’ own tax_application rows. Accepts two folio states. A closed folio at zero balance is the settled stay: nothing is due. An open folio already transferred to a company’s A/R account (settle_folio_to_ar marks and links it but moves no money) is the billed stay: the balance becomes amount_due, the folio’s due_at becomes due_on, and issuing SEALS the folio as it goes — which is the only place this verb writes folio state, and why a company’s document can be issued at all. Refuses an open folio with no A/R transfer, a void or house folio, a folio whose uncredited invoice already exists, a folio with no charges, a property with no billing_identity, a recipient that cannot be resolved, and — above the property’s simplified-invoice threshold — a recipient without a name, city, postcode and country. Below that threshold the recipient’s details may be omitted (UK £250 under reg 16A, Germany €250 under §33 UStDV), but never for a company: the point of their document is input-tax recovery. preview_invoice answers all of the above without allocating anything, so the desk can disable its own button and say why.
Effects: create hospitality.invoice; link hospitality.link.invoice_for_folio; link hospitality.link.invoice_credits_invoice; link hospitality.link.invoice_billed_to_person; link hospitality.link.invoice_billed_to_company; modify hospitality.folio.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Apply against an open branch’s overlay view instead of the canonical (main) plane. The action’s writes land in the branch’s copy-on-first-write overlay, its events in the branch’s own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (POST /v1/branches forks one).
object
object
When true, the response carries modified_objects and modified_links projections — the engine reads the event log inside the same transaction so the projection observes the handler’s own writes.
object
Responses
Section titled “Responses”Action applied. modified_objects and modified_links populated when return_modified: true was supplied.
Envelope returned by the Aerandil action engine. correlation_id ties every event emitted by this invocation; modified_objects and modified_links project the events the handler emitted (per the action’s declared effects); warnings carries any non-blocking soft-validator observations.
object
Per-invocation correlation id; matches events.correlation_id for every event this action appended.
Links established or removed by this invocation. Empty when the caller did not request return_modified.
object
Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request return_modified.
object
Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.
object
Human-readable summary, suitable for logging or operator-UI surfacing.
Object type the warning was raised against.
Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.
Stable kebab-case rule identifier (e.g. comp-authority-over-limit).
Example
{ "modified_links": [ { "kind": "linked", "link_type": "hospitality.link.invoice_for_folio" } ], "modified_objects": [ { "kind": "created", "object_type": "hospitality.invoice" } ]}Conflict — concurrent modification or unique constraint violation.
Validation error — parameter validation or business-rule violation.