Atomic Purchase Flow

sequenceDiagram
    participant P as Partner
    participant API as WeatherIT API
    participant DB as Database

    P->>API: POST /quotes/multi/{id}/purchase<br/>+ X-Request-Id (idempotency)
    API->>API: Check idempotency cache (7-day TTL)
    API->>DB: Validate all quotes in batch

    loop For each quote (sequential)
        API->>DB: accept_and_pay_quote
        alt Success
            DB-->>API: Policy created
        else Failure
            DB-->>API: Error
            Note over API: Entire batch fails
            API-->>P: 500 TRANSACTION_FAILED
        end
    end

    API-->>P: 200 All policies created

What This Endpoint Does

1. Validates Batch: Confirms all quotes in the batch are still valid
2. Atomic Purchase: Purchases all selected quotes together or none
3. Creates Policies: Generates policy numbers and activates coverage for each
4. Returns Summary: Provides transaction details and all created policies

When to Use This Endpoint

Call this endpoint when:

• Customer has selected coverage options from a multi-quote batch
• Payment has been processed for the combined total
• You want to create multiple policies in a single transaction
• You need rollback protection (all succeed or none)

Request Parameters

Understanding the Response

multi_purchase object contains:

policies[] for each policy:

payment summary:

Error Handling

Idempotency

Include X-Request-Id header for safe retries. The endpoint caches responses for 168 hours (7 days) - retrying with the same request-id returns the original response.

Best Practices

1. Verify totals: Ensure payment amount matches sum of selected quote premiums
2. Use idempotency: Always include X-Request-Id for production requests
3. Store all policy_ids: Each policy in the batch may need individual operations later
4. Handle rollbacks: If purchase fails, the entire batch is rolled back - create new quotes

Next Steps

After successful purchase:

1. Send confirmation email with all policy numbers
2. Store each policy_id linked to your bookings
3. Use GET /policies/{id} to retrieve individual policy details
4. Use POST /policies/{id}/cancel if a booking is cancelled