Klaviyo Email (Advanced Tier)

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €59/mo; credential: we manage Klaviyo integration, template library

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

A paid integration module that syncs AstroCMS customer and order data to Klaviyo, lets merchants design and send campaigns in Klaviyo, and syncs engagement metrics back. Includes managed template library and Klaviyo API credential management.

The problem

Merchants use Klaviyo as the industry standard for email marketing but manually export customer lists from AstroCMS to Klaviyo as CSV, losing sync when customer data changes. Data silos between storefront and email platform cost hours per week in manual updates.

What it does

• Two-way sync of customer data (name, email, purchase history, custom attributes) between AstroCMS and Klaviyo
• Order event tracking (send new order, cart abandoned, product purchased events to Klaviyo real-time)
• Sync configuration UI (merchant maps AstroCMS customer fields to Klaviyo custom fields)
• Campaign template library (50+ Klaviyo templates available to merchant via AstroCMS admin)
• Draft and send campaigns in Klaviyo; metrics sync back to AstroCMS (open rate, click rate, unsubscribe)
• Subscriber list sync (AstroCMS subscribers → Klaviyo list; two-way: Klaviyo unsubscribes → AstroCMS)
• Webhook handling (Klaviyo sends webhooks when subscriber unsubscribes, complains, bounces)
• Credential management (merchant pastes Klaviyo API key; we store encrypted, test connection on save)
• Sync logs and error handling (show merchant sync status: last sync date, errors, retry count)
• Dual-send control (if customer in both AstroCMS and Klaviyo, send only once; no duplicates)

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.

• Automated Klaviyo workflows (if-then-else flows defined in Klaviyo) — Klaviyo owns automation; we sync data, not logic
• Predictive send time from Klaviyo — Klaviyo owns ML; we read the send time selected by Klaviyo and apply it
• Klaviyo SMS or push notifications — separate Klaviyo modules; we own email integration only
• Bulk-edit Klaviyo lists (bulk delete, update, re-import) — Klaviyo owns list management; we own sync
• Klaviyo analytics deep-dive (cohort analysis, revenue attribution) — Klaviyo owns analytics; we own metric sync
• Klaviyo pricing calculation or usage monitoring — Klaviyo bill customers directly; we don’t proxy billing

Data model

New entities: integrations.klaviyo {id, merchantId, apiKey (encrypted), apiKeyId, status (connected/disconnected/error), lastSyncAt, syncErrorMessage, createdAt}; integrations.fieldMappings {id, klaviyoIntegrationId, astrocmsField (firstName/lastName/email/customField), klaviyoField (firstName/lastName/email/customProperty), mappingType (direct/computed/webhook)}; integrations.syncLog {id, klaviyoIntegrationId, syncType (customer/order/subscriber/unsubscribe), direction (push/pull), status (success/partial/failed), recordsProcessed, errors[], syncStartAt, syncEndAt}; integrations.eventQueue {id, integrationId, eventType (new-order/cart-abandoned), customerId, orderId, eventData (json), sentToKlaviyoAt, status (queued/sent/failed)}; integrations.webhookLogs {id, integrationId, eventType (unsubscribe/bounce/complaint), payload (json), processedAt}.

API

• POST /api/integrations/klaviyo
• GET /api/integrations/klaviyo/{id}
• DELETE /api/integrations/klaviyo/{id}
• POST /api/integrations/klaviyo/{id}/sync-now
• GET /api/integrations/klaviyo/{id}/sync-logs
• POST /api/integrations/klaviyo/{id}/field-mappings
• GET /api/integrations/klaviyo/{id}/field-mappings
• POST /api/integrations/klaviyo/{id}/test-connection
• POST /api/integrations/klaviyo/webhooks
• GET /api/integrations/klaviyo/{id}/campaigns
• GET /api/integrations/klaviyo/{id}/templates
• GET /api/integrations/klaviyo/{id}/event-queue

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

Admin

Klaviyo integration setup: paste API key, test connection, show status (connected/disconnected/error). Field mapping: show AstroCMS customer fields and map to Klaviyo fields. Sync control: trigger manual full sync, view last sync date and status. Sync logs: show sync history, error messages, retry failed syncs. Webhooks: view Klaviyo webhook events received (unsubscribe, bounce, complaint), show processing status. Campaign metrics: fetch campaigns from Klaviyo, display open rate, click rate, unsubscribe rate. Template browser: show Klaviyo template library, preview, send to Klaviyo for editing. Event queue: view pending order and customer events queued for Klaviyo. Dual-send prevention: show merchants which customers exist in both AstroCMS and Klaviyo.

The seam — why this is paid

Core owns free email-newsletter-campaigns (subscriber list, send, tracking). Paid Klaviyo integration module owns Klaviyo API credential management (API key storage, encryption, periodic refresh — security infrastructure), two-way sync orchestration (customer sync, order events, webhook handling — complex data flow), Klaviyo template library access and preview (curated by Klaviyo; we own access mechanism), field mapping configuration (customer fields → Klaviyo custom fields — business logic, support), metric sync and campaign metrics dashboard (Klaviyo data integration).

Credential: Klaviyo API key management, template design, compliance

Dependencies

• email-newsletter-campaigns module (subscriber list, segmentation)
• Orders module (for order events: new order, cart abandoned)
• Customers module (to sync customer name, email, custom attributes)
• Email service (to send transactional emails, not Klaviyo emails)
• Scheduler (for periodic sync of customers and campaigns)

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.

• Merchant pastes Klaviyo API key in integration setup; connection test is successful and ‘connected’ status shows
• A new customer created in AstroCMS is synced to Klaviyo within 5 minutes; appears in Klaviyo list with correct email and name
• A new order placed in AstroCMS generates ‘new-order’ event, queued in eventQueue, and sent to Klaviyo within 1 minute
• A customer unsubscribed in Klaviyo sends webhook to AstroCMS; AstroCMS marks subscriber as unsubscribed within 1 minute
• Field mapping maps AstroCMS ‘loyaltyPoints’ to Klaviyo ‘loyalty_points’ custom field; when customer earns points, Klaviyo field is updated
• A campaign created and sent in Klaviyo shows metrics in AstroCMS: open rate 25%, click rate 8%, unsubscribe count 3
• An order placed by customer who is on both AstroCMS and Klaviyo results in only ONE ‘new-order’ event sent to Klaviyo (no duplicate)
• Sync log shows: ‘2024-09-02 14:30 - Customer sync complete: 1000 records synced, 5 errors (invalid email format)’ with specific error details
• Webhook from Klaviyo with unsubscribe event is processed and AstroCMS subscriber record is updated within 10 seconds
• Test connection fails with clear message if API key is invalid, expired, or account is suspended

Risks

API key exposure: if API key is logged in plaintext or displayed in debug output, security is compromised; encrypt at rest, never log. Sync data loss: if sync crashes mid-way, restart must skip already-synced customers; implement checkpointing. Duplicate order events: if send-to-Klaviyo is triggered twice, customer receives duplicate events; deduplication by order ID required. Field mapping conflicts: if AstroCMS field maps to multiple Klaviyo fields, sync may write conflicting data; enforce 1:1 mapping. Webhook signature validation: if webhook is not validated (Hmac signature check), fake webhooks can be injected; always verify. Bi-directional sync conflicts: if customer email changed in both systems, which wins? Document conflict resolution (last-write-wins or merchant chooses). Rate limiting: if syncing 100k customers, hitting Klaviyo API rate limits causes sync to fail partway; implement backoff. Metric sync lag: if campaign sent 1 week ago, metric sync is stale; refresh periodically and show ‘last updated’ timestamp.

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.