Getting Started with Levy Cover

This guide walks you through enabling Levy Cover on a subaccount from a cold start. It assumes the carrier partnership has been signed and you have sandbox or production credentials from Cover Genius.

Prerequisites

Before you start, confirm:

• The subaccount has Stripe Connect onboarding completed.
• The subaccount operates in at least one jurisdiction in the Jurisdiction Matrix.
• You have Cover Genius API_KEY and PARTNER_ID values (sandbox or production).
• Riders on this subaccount are using a mobile-app build that includes the Levy Cover opt-in card (shipped with mobile-app SDK runtime version covering project #09).

Step 1 - Set the carrier credentials

Set the two environment variables on Vercel for every environment that will hit production traffic:

COVER_GENIUS_API_KEY=<from Cover Genius portal>
COVER_GENIUS_PARTNER_ID=<from Cover Genius portal>

Full instructions are in Carrier Credentials Setup. The carrier client reads these at runtime - no deploy required after rotation, but a redeploy is required the first time you set them.

Step 2 - Verify the jurisdiction matrix

Open the matrix at /dashboard/insurance/settings and confirm the unlock locations you serve are marked available: true with the carrier you intend to use. Initial supported jurisdictions:

• US: California, Texas, Florida, North Carolina, Massachusetts (Phase 1). Colorado, Arizona, Georgia, Oregon, Tennessee added in Phase 2.
• EU: Germany, France, Netherlands, Portugal.
• Excluded: New York, Washington (DOI friction). Out of scope in v1.

If your jurisdiction is missing, contact support - we either add it to the matrix and the insurance_offerings table, or the carrier is not yet licensed there.

Step 3 - Configure the offering

Still at /dashboard/insurance/settings:

1. Toggle Levy Cover on for the subaccount.
2. Choose which tiers to offer. v1 ships only "Standard"; v2 unlocks "Minimal" and "Premium".
3. Set the operator commission percentage. The default comes from the global INSURANCE_OPERATOR_SHARE_PCT env var (typically 50% of Levy's gross commission); per-subaccount values override that.
4. Save.

The settings page writes to the insurance_offerings table, which is the runtime source of truth for opt-in availability and commission math.

Step 4 - Test in sandbox

Before going live:

1. Configure Cover Genius sandbox credentials in a preview environment.
2. Unlock a vehicle on a sandbox subaccount. Confirm the opt-in card appears.
3. Accept the offer, complete the ride, and check the receipt - "Levy Cover - Standard - $1.00" should appear as a separate line item.
4. File a test claim from ride history. Upload at least one photo. Confirm the claim lands in the operator queue at /dashboard/insurance/claims.
5. Inspect ride_insurance_policies and insurance_claims in the database - both should have the carrier IDs returned by Cover Genius sandbox.

Step 5 - Promote to production

When sandbox UAT is clean and Cover Genius has signed off:

1. Set production COVER_GENIUS_API_KEY and COVER_GENIUS_PARTNER_ID in Vercel production env.
2. Verify the webhook receiver URL is registered with the carrier: https://fleets.levyelectric.com/api/webhooks/insurance/cover-genius.
3. Enable the subaccount toggle in production.
4. Watch the first 10-20 insured rides. Monitor insurance_webhook_log for signature_verified = true on every inbound event.

Step 6 - Hand off to ops

Tell Levy ops:

• Which subaccount is now live.
• Which jurisdictions are covered.
• Operator commission percentage.
• Sandbox vs production carrier credentials in use.

Support tickets for "I crashed and want my money back" now route through the carrier claim flow rather than goodwill refunds.

Common first-day issues

---