Events & Purchase Flow

The widget communicates with the partner's page via Custom Events dispatched on document. This page documents the full event contract and the backend purchase flow partners must implement.

Event Contract

All events are standard CustomEvent instances dispatched on document with a detail payload.

Design notes:

• There is no coverage-removed event. The customer always has an active selection — either a protection tier or "No Protection".
• There is no payment-complete event. The widget does not handle payment.

Listening for Events

document.addEventListener('weatherit:coverage-selected', (e) => {
  const { quoteId, optionName, premium } = e.detail;
  // Store quoteId against the booking for later purchase
});

document.addEventListener('weatherit:coverage-declined', (e) => {
  const { quoteId } = e.detail;
  // Remove any stored quoteId for this booking
});

Partner Purchase Flow

The widget handles quoting and selection only. After the customer completes the partner's checkout, the partner's backend activates the policy.

sequenceDiagram
    participant Customer
    participant PartnerFrontend as Partner Frontend
    participant PartnerBackend as Partner Backend
    participant Widget as WeatherIt Widget
    participant API as WeatherIt API
    participant Stripe as Stripe Connect

    Widget->>Customer: Display protection options
    Customer->>Widget: Selects protection tier
    Widget->>PartnerFrontend: weatherit:coverage-selected event
    PartnerFrontend->>PartnerBackend: Store quoteId with booking

    Note over Customer,Stripe: Customer completes partner checkout

    PartnerBackend->>Stripe: Charge total (booking + premium split)
    Stripe-->>PartnerBackend: transaction_id

    PartnerBackend->>API: POST /quotes/quoteId/purchase
    API-->>PartnerBackend: policyId, status active

    PartnerBackend->>PartnerBackend: Store policyId

    Note over Customer,API: Customer views confirmation page

    Customer->>PartnerFrontend: Loads confirmation page
    PartnerFrontend->>Customer: Renders weatherit-confirmation with policy-id

Step-by-Step

1. During checkout — Your frontend listens for the weatherit:coverage-selected event and stores the quoteId against the booking.

2. On weatherit:coverage-declined — Remove any stored quoteId for the booking. No further action needed.

3. After checkout completes — If a quoteId is stored for the booking, your backend calls:

   POST /quotes/{quoteId}/purchase

   With the Stripe transaction ID and customer details. See the Purchase API reference for the full request/response shape.

4. Policy activated — The purchase API returns a policyId. Store this for the confirmation page.

5. Confirmation page — Pass the policyId to the confirmation widget:

   HTML

   <weatherit-confirmation
     partner="{WEATHERIT_PARTNER_ID}"
     booking="{booking.reference}"
     policy-id="{policyId}"
   ></weatherit-confirmation>

Confirmation Widget Data Flow

The confirmation component operates independently on a separate page. It has no shared state with the checkout widgets.

Recommended approach: Pass policy-id and quote-id attributes from your booking flow. This gives the component the data it needs without additional API calls.

📘

Booking-ref lookup — A future release will allow the confirmation widget to look up policies by booking reference alone. Currently, partners should pass policy-id and/or quote-id explicitly.

Related

• Purchase API Reference
• Split Payment & Reconciliation Guide