Exemption certificates

Store the documentary proof behind exemption claims — diplomatic cards, government exemption certificates, entity exemptions — and let proof-gated exemption rules verify it automatically at calculation time.

Why certificates exist

Many jurisdictions exempt certain stays from lodging taxes — diplomatic missions, federal employees on official travel, charitable entities — but only when the operator holds valid documentation. Waiving tax without the paperwork is an audit finding; collecting tax from a genuinely exempt guest is a billing dispute. Certificates close that loop: the exemption only fires when a calculation references a certificate that actually backs it.

Detail

The gate is fail-closed by construction. A certificate-gated exemption rule charges full tax unless the booking references a certificate that passed every check. The validation flag is computed server-side — API callers can send a certificate reference, never the validation result itself.

Managing certificates

1
Add the certificate
Certificates → Add a certificate. Record the holder, type, certificate number, issuing authority, validity window, and (optionally) the jurisdictions it covers.
2
Attach the proof document
Upload the scanned certificate (PDF, PNG, or JPEG, up to 5 MB). The file is stored with the record and retrievable for audits.
3
Reference it on a calculation or booking
In the Calculator (Guests & Booking Purpose section) pick the certificate, or pass exemption_certificate_id in the API request. The server validates it and, if valid, certificate-gated exemption rules can fire.
4
Watch expiry
The list shows a computed status — active, expiring soon (30 days), expired, or revoked — so renewals never surprise you.

Writes are organization-admin actions (compliance configuration); all members can view the list and use certificates on calculations.

What the server validates

Field	Type	Description
Organization scope	404	The certificate must belong to your organization. Unknown or cross-org references are rejected.
Validity window	409	The window must cover the WHOLE stay — from the check-in date through the last occupied night. A certificate expiring mid-stay is rejected.
Jurisdiction scope	409	If the certificate lists jurisdiction codes (e.g. US-TX), the booking's jurisdiction must fall under one of them. An empty scope means unrestricted.
Status	409	Revoked certificates are rejected for new calculations. Existing bookings keep their frozen validation snapshot.

Heads up

Validity is checked against the stay dates, not today's date — recording a past booking whose certificate covered the stay (but has since expired) works, because that's the audit-correct question.

Snapshots and audit defense

When a booking is created with a certificate, the validation result — holder, type, number, window, and the validation timestamp — is frozen into the booking's response snapshot. Editing or revoking the certificate later never retro-changes a persisted booking, and adjusting a booking re-validates the certificate against the new calculation. The booking detail page shows the frozen certificate panel; the certificate record links back to every booking that used it.

Authoring note for rule authors: certificate-gated rules AND the entity condition with has_valid_exemption_certificate == true (optionally narrowing by exemption_certificate_type). Existing rules that don't reference those fields are completely unaffected. See Rules & exemptions for rule anatomy.

What this is (and isn't)

This wave ships certificate storage, validation, and the calculation gate. Outbound collection campaigns (emailing guests for certificates), OCR extraction, and state-registry verification of certificate numbers are not included yet — the certificate's authenticity remains the operator's check-in responsibility, exactly as it is on paper today.