Insurance Integration (Optics)

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €44/mo; credential: per-country insurance APIs (Greece, Germany, etc.)

Generated from docs/plan/paid/insurance-integration/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Optical retailers verify patient insurance coverage before checkout, reducing claim denials and enabling instant coverage confirmation across Greece, Germany, and Austria. The paid pack maintains per-country insurance API credentials and reconciliation; core owns the verification interface and an honest HTTP wrapper.

The problem

Optical practices need to check whether a patient’s insurance covers the frames and lenses they are buying before checkout. Manual verification is slow and error-prone; claims get denied at reconciliation. Merchants in different countries have different insurance rules and APIs.

What it does

• Per-country insurance API adapters (Greece—EOPY, Germany—TK, Austria—SVA) with pluggable credential management
• Pre-checkout verification endpoint that returns coverage status: covered, denied, partial, unknown
• Coverage amount cache (with TTL) to avoid rate-limiting on high-traffic days
• Audit log entry for every insurance lookup (patient ID hashed, coverage status, amount)
• Admin UI to configure active countries, enable/disable insurance checks per storefront
• Webhook on coverage denial to notify support team via email or Slack
• Test mode using mock insurance API responses; production mode uses real credentials
• Error handling: timeout, API down, invalid patient ID—each returns a sensible customer message

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Direct insurance claim submission: we return coverage info; merchant’s backend files claims (support burden and per-country forms are the merchant’s responsibility).
• Coverage negotiation or dispute: we report what the API says; merchant disputes go directly to insurer (no value added by AstroBaaS).
• Multi-country patient lookup in a single call: each country’s API is independent; merchants must specify country first (API boundary is simpler, implementation risk lower).
• Real-time updates to coverage amounts during a patient’s session: cache TTL is 1 hour; live syncing would require persistent connections (support cost and complexity not justified).

Data model

New document type: insurance_lookup { cartId, patientId (hashed), country, status, coverageAmount, timestamp, errors }; new setting: insurance_active_countries (list); new setting: insurance_test_mode (boolean).

API

• POST /api/insurance/verify { patientId, country, itemIds } -> { status, amount, warnings }
• GET /api/insurance/config -> { activeCountries, testMode, coverage }
• POST /api/insurance/config { activeCountries, testMode } (admin only)
• GET /api/insurance/audit?country=GR&from=2026-01-01&to=2026-01-31 (admin only)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: list of active countries with toggle, test/production mode switch, coverage amounts per country, audit log viewer with date range filter, webhook URL editor, support notification settings. Operator can enable/disable per country; test mode always returns mock data.

The seam — why this is paid

Core owns the verification endpoint and honest HTTP error handling. Paid pack owns: per-country API credentials, real API adapters (Greece/Germany/Austria), coverage cache strategy, production support and API vendor relationship.

Per-country obligation: optical insurance rules differ by country (Greece/Germany/Austria)

Dependencies

• webhook-management (to notify on coverage denial)
• audit-log subsystem (existing; logs all lookups)
• settings subsystem (existing; stores credentials securely)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A patient with valid coverage in EOPY (Greece) is returned {status: ‘covered’, amount: 500}
• A patient with no coverage in TK (Germany) is returned {status: ‘denied’}
• Coverage results are cached for 1 hour; second lookup for same patient returns cached result
• An API timeout returns {status: ‘unknown’, error: ‘API timeout’} and a customer-visible message
• Audit log shows every lookup with country, patient ID (hashed), result, timestamp
• In test mode, any patient ID returns {status: ‘covered’, amount: 999}
• Disabling insurance for a country removes it from the verification flow
• A webhook is sent when coverage is denied, containing patientId, country, cartId

Risks

If credentials are logged unencrypted, they leak to the audit trail. If coverage amounts are returned as floats instead of integers (minor units), rounding errors propagate to final charges. If cache keys do not include country, a Greek patient might see German coverage. If the API adapter crashes, the whole checkout flow fails (must return sensible error, not 500).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.