SimplyClub

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 </body> 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.