--- title: Product Requirements (MVP) --- ## 1. Introduction & Definitions **General Purpose** The primary purpose of this plugin is to act as a standardized, lightweight bridge between third-party commerce platforms (e.g., CRM, ERP, POS, e-commerce: Shopify, WooCommerce, etc.) and the SimplyClub loyalty and marketing automation ecosystem. By utilizing a pre-built connection layer (called Dropins), the plugin minimizes custom frontend development while delivering a native-feeling loyalty experience. It handles user synchronization, dynamic cart benefit application, and secure order lifecycle reporting via webhooks. **Note for Technical Spec Generation:** This PRD must be used in conjunction with the `Dropins Technical Documantation.md` file. Any technical specification generated from this document must synthesize the product requirements outlined here with the specific technical implementation details, events, and commands provided in the Dropins documentation. **Definitions & Terminology** * **SimplyClub / Simply Club / Service / Platform:** The core SimplyClub backend loyalty and marketing automation solution. * **SimplyClub Dropins / Dropins / Loyalty Dropins:** The connection layer facilitating the integration. This encompasses visual UI/GUI components, underlying SDK events, functions, and webhook architecture. * **POI (Point of Interaction) / Touch Point / Host System / System:** The third-party platforms (e.g., E-commerce websites, ERPs, POS, CRM systems) integrating with SimplyClub via Dropins. --- ## 2. Core Identity & Session Synchronization (MVP) The plugin bridges the hosting platform’s user session and the SimplyClub member profile. * **Initialization:** Inject the Dropins script before `` and initialize using the specific `poiId`. * **User Sync (`setUser`):** * Upon host system login, sync the user: `instance.commands.setUser({ id, firstName, lastName, email, phone })`. * Upon logout, clear the session: `instance.commands.setUser(null)`. * **Authentication Bridge:** Listen for the Dropins' auth request and redirect unauthenticated users to the host's native login page. --- ## 3. Cart Interaction & Product Suggestions (MVP) The plugin supports dynamic cart updates and loyalty-driven product additions. * **Cart Monitoring (`setCart`):** Monitor all host cart mutations (add, remove, update) and send the state to SimplyClub. * **Native Promotion Awareness:** Cart data sent to SimplyClub must include existing host-system discounts to ensure benefits are calculated on the net price. * **Product Addition:** Programmatically add suggested SKUs/memberships to the host cart when triggered by Dropin events. --- ## 4. Benefit Selection & Recalculation (MVP) Handles the state between the host cart and selected loyalty benefits. * **Benefit Application:** Apply discounts to the host checkout total when a user selects a benefit via the Dropin. * **Change Detection & Recalculation:** If the host cart changes *after* a benefit is applied: 1. Notify the user of the change. 2. Trigger a recalculation. 3. Require the user to re-confirm benefits via the Dropin. ### 4.1 Benefit Application Strategy (V1 vs. V2) * **V1 (MVP) - Total Order Discount & Pretty Print:** * **Standardized Naming:** Apply an aggregate order-level discount programmatically named/tagged `sc_club_discount` in the host system. * **Pretty Print Summary:** Generate a human-readable string (e.g., *"Rewards Applied: Anniversary Gift, 10% Off"*) to display in the checkout UI and save to the admin order view. * **Strict Refresh Logic:** Modifications to benefits require the host to completely clear the existing `sc_club_discount` and "Pretty Print" data before applying new data. * **V2 (Future Roadmap) - Line-Item Discount Allocation:** * **Logic:** Map specific benefit names, unit prices, and quantities directly to relevant line items. Essential for strict tax compliance and partial refunds. --- ## 5. Transaction Finalization & Order Lifecycle (MVP) * **Transaction Code Capture:** Store the unique `sc_transaction_code` generated by the Dropin during checkout as order metadata. * **The Unified Webhook:** Send all lifecycle events to a single SimplyClub webhook (`POST /api/v1/transaction/order-webhook`). * **Payload Structure:** Uses the Shopify-style snake_case wire format: `topic`, `domain`, `sc_transaction_code`, `order_id`, and `customer_id` (required for `orders/paid`). The server handles two topics: `orders/paid` (enabled by default) and `refunds/create` (disabled by default). Any topic that isn't enabled for the POI — by default that's everything except `orders/paid` — returns HTTP 200 with `{ skipped: true }` (not an error); the `404 Unhandled webhook topic` response only occurs if a POI explicitly enables a topic that has no server handler. Order cancellation is not handled. --- ## 6. Hosting System Responsibilities & Scope The integration relies on a Frontend Pub/Sub model and a Backend Webhook publisher. ### 6.1 Frontend (User Storefront) Responsibilities * **Initialization & State Publishing:** Inject scripts, monitor auth states, and publish real-time cart states to Dropins. * **Event Subscription (Pub/Sub):** Translate SimplyClub discount data to native host discounts, handle recalculations, execute "Add to Cart" requests, capture transaction codes, and handle auth redirects. ### 6.2 Backend (Server-Side) Responsibilities * **Unified Webhook Publisher:** Trigger a POST request to the SimplyClub Webhook (`POST /api/v1/transaction/order-webhook`) upon `orders/paid` and `refunds/create` lifecycle events. (Order cancellation is not handled.) ### 6.3 Admin (Backoffice) Responsibilities * **Orders List View:** Display a visual "Club" tag and a "Sync Status" (Approved/Failed/Pending) based on the webhook response. * **Single Order View:** Display the Member ID, `sc_transaction_code`, "Pretty Print" rewards summary, and the raw webhook Info Log. ### 6.4 Future Roadmap: Advanced Admin Actions & Payment Flows (V2+) * **J5 Payments (Auth & Capture) Admin Dropin:** For uncaptured orders where the merchant alters contents before shipping, an embedded **Admin Dropin** will allow merchants to visually recalculate and adjust benefits based on the final collected products without backend API development. * **Manual Order Resync:** A manual "Resync to SC" button to retry failed webhook payloads. * **Marketing Automation:** Abandoned cart and product view tracking. * **Gamification:** Scratch cards, spin-to-win, and community milestones.