T Triple Whale for nopCommerce — by nopmodules.com
← Back to product

Documentation

Everything you need to install and configure the Triple Whale plugin for nopCommerce 4.90.

⚠️ Important: when you set up your Triple Whale account, choose Custom MSP as the integration type — not Shopify, WooCommerce or BigCommerce. This plugin uses Triple Whale's Data-In API, which maps to the Custom MSP connector.

Installation

  1. Download the plugin archive

    Get the Widgets.TripleWhale.zip file.

  2. Go to admin area > Configuration > Local plugins

    Log in to your nopCommerce administration and open the Local plugins page.

    Local plugins page
    Admin → Configuration → Local plugins

  3. Upload the plugin archive

    Use the "Upload plugin or theme" button to upload the archive.

    Upload plugin dialog
    Upload dialog with the .zip selected

  4. Install the plugin

    Find the newly uploaded plugin and click "Install". This schedules the background sync task (every 5 minutes) and the log cleanup task (daily).

    Install the plugin
    The Triple Whale plugin with the "Install" button

Configuration

Configuration is done in nopCommerce under Configuration → Widgets: activate the Triple Whale widget, then click Configure.

  1. API key

    Paste your Triple Whale API key (found under Data → APIs in Triple Whale).

  2. Shop URL

    Enter the shop domain that matches Settings → Store in Triple Whale. Leave empty to auto-detect from the store URL.

  3. Pixel snippet

    Paste the Triple Whale base tracking snippet for client-side pixel tracking. This step is required.

    Plugin fully configured
    The plugin fully configured — API key and pixel snippet filled in

  4. Enable the sync toggles

    Turn on pixel, server-side events, order sync, customer sync and product sync as needed.

  5. Test connection

    Press "Test connection" to verify your API key, then "Save".

  6. Sync all

    Press "Sync all" to backfill your existing orders, customers and products.

How data syncs

The plugin keeps Triple Whale in sync with your store's revenue, customers and catalog.

EntityWhat is sent
OrdersLine items, revenue, shipping, discounts, tax, customer, payment gateway, currency and status.
RefundsFull and partial refunds. For multi-item orders the refund amount is distributed proportionally across the line items. Refund dates are read from the order notes so they land on the correct day.
Cancelled ordersMarked as void and excluded from revenue, so they don't inflate your Triple Whale metrics.
CustomersEmail, name, address and consent.
ProductsCatalog and variants, so Triple Whale can apply COGS.
EventsPurchase and Refund server-side events for attribution (works without client-side JavaScript).
Sync frequency: data is pushed to Triple Whale automatically in the background every 5 minutes. The manual "Sync all" button performs a full sync of the entire store database — orders, customers and products — sending only the records relevant to Triple Whale.
The pixel snippet is required for client-side tracking. Server-side events complement it for attribution when JavaScript is blocked.

Troubleshooting

Use the built-in logs to diagnose any issue.

⚠️ Behind a proxy or load balancer? The public pixel endpoint is rate-limited to 60 requests per minute per IP. If your store sits behind a reverse proxy (nginx, Cloudflare, load balancer, etc.), make sure the X-Forwarded-For header is forwarded correctly — otherwise all visitors appear as a single IP and the rate limit will block legitimate traffic.

  1. Download logs

    On the plugin configuration page press "Download logs" to export a CSV with every API request, response and error.

  2. Check the retry queue

    Transient failures are retried automatically with exponential backoff (up to 5 attempts).

  3. Verify the connection

    Run "Test connection" to confirm the API key and shop URL are valid.