Topdata Topdata Docs

TopdataProductWatchSW6

Topdata Product Watch SW6 User Manual

Overview

Topdata Product Watch SW6 sends back-in-stock and price-drop notifications to customers who asked for them. A logged-in customer ticks one or both of two checkboxes in their account; from then on the plugin watches the products that customer currently has in their cart or on their wishlist and mails them when an item becomes orderable again or when its price drops far enough to be worth an email.

If several of a customer’s watched items change in the same run, they receive exactly one mail — a digest — never one mail per item. Every notification decision is written to an audit trail, so the question “why did this customer not hear about this product?” can be answered instead of guessed.

Key Features

  • Back-in-stock notifications for cart and wishlist items
  • Price-drop notifications measured against the customer-effective price, so B2B customer prices are respected
  • Strictly opt-in: nothing is watched until a customer ticks a checkbox, and guests are never processed
  • One mail per customer per run — a single notification gets a product-specific mail, two or more are grouped into one digest
  • Spam guards: a minimum price drop (percentage and amount), per-item cooldowns that absorb ERP stock flapping, a per-run mail budget and a per-customer daily cadence
  • One-click unsubscribe in every mail, in the HTML and the plain-text part, usable without a login session
  • Audit trail and admin log recording events only — never one row per evaluation — plus conversion attribution for orders placed shortly after a mail
  • No theme change required: the opt-in card and the onboarding banner are injected by the plugin

Getting Started

  1. Follow the Installation Guide.
  2. Set the thresholds in the Settings Guide — the defaults are sensible, but the price-drop gates are worth a look before you go live.
  3. Read how customers opt in and how the hourly job behaves in the Usage Guide.
  4. If a customer does not receive a mail you expected, the FAQ & Troubleshooting explains where to look.

Support

For additional support, please contact our technical support team or visit our support portal.

Topdata Product Watch SW6 Installation Guide

System Requirements

  • Shopware 6.7
  • topdata/topdata-foundation-sw6 (>= 1.6.0)
  • An availability field from your ERP: the plugin reads the product custom field tdg_props_verfuegbarkeit (see “What orderable means” below)

Installation Steps

1. Install via Composer

composer require topdata/product-watch-sw6

2. Activate the Plugin

Option A: Using the Shopware Admin Panel

  1. Log in to your Shopware admin panel.
  2. Go to Extensions > My extensions.
  3. Find “Topdata Product Watch SW6” in the list.
  4. Click Activate.

Option B: Using the Command Line

bin/console plugin:install --activate TopdataProductWatchSW6

3. Clear Cache

bin/console cache:clear

The migrations create three tables (topdata_product_watch_subscription, topdata_product_watch_state, topdata_product_watch_activity), seed the three mail template types and write the default configuration values.

4. Configure the Thresholds

Open Settings > System > Product notifications and review the defaults. At minimum, check the two price-drop gates — they are conjunctive, so a 10 % drop of 2.00 EUR is not mailed when minPriceDropAmount is set to 5.

5. Activate the Scheduled Task

The notification pass runs hourly as a scheduled task. Make sure Shopware’s scheduled task runner is active for topdata_product-watch.notify, or run the pass manually:

bin/console topdata:product-watch:notify

What “orderable” means in your shop

Availability in this plugin is not Shopware stock. It mirrors the buy gate of the shop theme, so customers are only notified when they could actually buy the item:

orderable  =  ((int) tdg_props_verfuegbarkeit !== 4)  &&  product.available
tdg_props_verfuegbarkeitMeaningOrderable
1tomorrowyes
23–5 daysyes
36–15 daysyes
4auf Anfrage (on request)no

If your shop does not sync this field, every product counts as orderable and no back-in-stock mails will be sent. Confirm the field is filled before you rely on the feature.

Verification

  • Log in to the storefront as a customer: the Produkt-Benachrichtigungen card appears below the account overview with two checkboxes, both unticked.
  • Tick “available again”, save, and confirm the subscription was stored.
  • Put a product with tdg_props_verfuegbarkeit = 4 into the cart and run bin/console topdata:product-watch:notify --customer-id <id> --dry-run — the report shows the item as watched, without sending anything.
  • In the administration, the module Product watch log lists the events of your runs.

Troubleshooting

No mails are sent although the checkboxes are ticked

  • enabled must be on. With the master switch off, the job exits immediately — before any query.
  • The scheduled task must be active. Check Settings > System > Scheduled tasks.
  • The customer must be logged in; guests are never processed.
  • Run bin/console topdata:product-watch:notify --customer-id <id> --dry-run and read the report: it names the reason for every suppressed row.

The opt-in card does not appear in the account

The card is injected into the account overview page. If your theme overrides that template completely, the card is lost — restore the template or place the plugin’s product-watch-card.html.twig snippet in your own template.

The mails are in English although the shop is German

The mail templates are seeded per locale prefix (de/gsw get the German template, en the English one). If a shop language has no seeded template, edit the three template types directly in Settings > E-mail templates.

Topdata Product Watch SW6 Settings Guide

All settings live in one card, Settings → System → Product notifications. The raw configuration key is shown in the first column, so you can also set it in your config.php.

Topdata

The first card only shows the Topdata banner with a link to this manual. It has no settings of its own.

Product notifications

Every setting lives in one card. The three switches decide what may be mailed, the thresholds decide when, and the two budget settings decide how much a single run may send.

SettingTypeDefaultDescription
enabledbooltrueEnable product notifications — Master switch. When off, the hourly job exits immediately and no mail is sent.
stockNotificationsEnabledbooltrueEnable “available again” notifications — Allow back-in-stock mails. Orderable means availability != “on request” and the product is available.
priceNotificationsEnabledbooltrueEnable price-drop notifications — Allow price-drop mails. Only the customer-effective price is compared.
minPriceDropPercentagefloat3.0Minimum price drop (percent) — A price drop is only mailed once it clears this percentage AND the minimum amount below. 0 disables the percentage gate.
minPriceDropAmountfloat0.0Minimum price drop (absolute amount) — Additionally required absolute drop. 0 = disabled, so only the percentage matters. Both gates are conjunctive.
priceDropCooldownDaysint7Minimum days between price mails per item — Guards against repeated price mails for the same item. 0 disables the cooldown.
stockNotificationCooldownDaysint14Minimum days between “available again” mails per item — Guards against ERP stock flapping (1 -> 4 -> 1). 0 disables the cooldown.
digestCooldownHoursint24Minimum hours between any notification mail to the same customer — The inbox-flooding guard. Together with the per-run grouping this caps a customer at one mail per day. 0 disables the per-day cadence.
cartStaleDaysint30Stop watching a cart item after N days without a cart event — Abandoned carts stop generating mails after this many days. Items also on the wishlist are never pruned this way.
customerBatchSizeint200Customers per job run — How many subscribers are processed per page. The rest is picked up by the next hourly run.
maxMailsPerRunint200Maximum mails per job run — Hard budget. A digest counts as one mail. Notifications beyond the budget are deferred to the next run, never lost.
activityLogEnabledbooltrueWrite the activity log — Support and evidence log. Records events only (mails sent, named suppressions, mail failures, conversions) — never one row per evaluation.
activityRetentionDaysint365Activity log retention (days) — Older rows are deleted by topdata:product-watch:activity:cleanup.
conversionWindowDaysint14Conversion window (days) — How long after a mail an order counts as stimulated by that mail. Measured from sent_at, not from when the row was created.
onboardingBannerEnabledbooltrueShow the onboarding banner in the account — Discovery aid, not part of the opt-in. Shows a dismissible banner on the account overview page while the customer has neither notification enabled. It never pre-ticks a checkbox and never enrolls anyone by itself.

Support

For additional support, please contact our technical support team or visit our support portal.

Topdata Product Watch SW6 Usage Guide

How a Customer Opts In

  1. The customer logs in to the storefront.
  2. In Account the plugin adds a Produkt-Benachrichtigungen card below the overview, with two independent checkboxes:
    • Enable “available again” notifications
    • Enable price-drop notifications
  3. While the customer has neither checkbox ticked, an onboarding banner on the account overview invites them to switch notifications on. The banner never pre-ticks a checkbox and never enrolls anyone by itself.

Nothing is watched before a checkbox is ticked. Unticking both — or using the Abbestellen link in any mail — removes the subscription and purges that customer’s watched products.

What Gets Watched

Only real products: promotions, custom lines and vouchers are never watched. The items come from two sources:

SourceHow it is captured
CartEvent-driven: a cart event writes the item into the pool when the cart’s product set actually changes. The job never scans carts itself, because a cart is not bound to a customer until they log in.
WishlistAuthoritative: it is read and reconciled on every run

An item that has not seen a cart event for cartStaleDays days stops generating mails — that is how abandoned carts are cleaned up. Items that are also on the wishlist are never pruned this way.

What the Hourly Job Does

The pass evaluates every subscribed customer and sends at most one mail per customer:

SituationResult
One item became orderable againProduct-specific “available again” mail
One item’s price dropped past the thresholdProduct-specific price-drop mail
Two or more items changedOne digest listing all of them
Nothing relevant changedNo mail, and no entry in the activity log

Two limits keep the inbox healthy:

  • digestCooldownHours caps a customer at one mail per day, no matter how much changed.
  • maxMailsPerRun is a hard budget per run. Notifications beyond the budget are deferred to the next run, never lost; a digest counts as a single mail.

State is stamped only when a mail was really sent, so a failed mail is retried on the next run instead of being silently swallowed.

Price drops in detail

  • Only the customer-effective price is compared, resolved through the customer’s sales channel. B2B customer prices are therefore respected, and comparing raw price rows would not produce false positives.
  • A drop must clear both minPriceDropPercentage and minPriceDropAmount. Setting both to 0 mails every drop of any size — use with care.
  • The reference price is downward-only: a price rise never raises it, and a drop that stays below the threshold never lowers it. That is deliberate — it is why rounding artefacts do not trigger a mail.
  • priceDropCooldownDays keeps a single item from producing repeated price mails.

Running It Manually

You never have to wait for the hourly run:

# full pass; the report lists what was scanned, mailed and why rows were skipped
bin/console topdata:product-watch:notify

# rehearse one customer, send nothing
bin/console topdata:product-watch:notify --customer-id 42 --dry-run

# rehearse everybody
bin/console topdata:product-watch:notify --all --dry-run

# override the budget for one run
bin/console topdata:product-watch:notify --batch-size 500 --max-mails 1000

# show the activity log lines the run produced
bin/console topdata:product-watch:notify --tail-log

Reading the Audit Trail

Every notification decision that is eventful — a mail sent, a named suppression, a mail failure, a conversion — is recorded in topdata_product_watch_activity. The plugin does not write a row per evaluation, so the table stays small and readable.

In the administration, the module Product watch log lists the trail with a status filter and a search over the customer mail address and the reason. It is read-only on purpose: the table is append-only evidence, and a sent row is never rewritten.

Two facts make it useful:

  • Conversion attribution: an order placed within conversionWindowDays of a mail is recorded on that same row as order_id + converted_at, giving an honest “stimulated orders” figure instead of a guess.

  • Retention: rows older than activityRetentionDays are removed by

    bin/console topdata:product-watch:activity:cleanup --dry-run   # preview
    bin/console topdata:product-watch:activity:cleanup             # delete

    Add --days to use a different window or --customer-id to clean one customer.

Changing the Mails

The three mail template types are owned by the plugin and editable in the administration:

TemplateSent for
product-watch-stocka single item became orderable again
product-watch-pricea single item’s price dropped
product-watch-digesttwo or more items in one run

All three exist per language as HTML and plain text, and every mail carries the one-click unsubscribe link in both parts.

Opting a Customer Out Manually

Open the customer in the administration and untick both notification checkboxes in their account, or send them a mail containing the unsubscribe link. Both routes remove the subscription and purge the customer’s watched products.

Support

For additional support, please contact our technical support team or visit our support portal.

Topdata Product Watch SW6 FAQ & Troubleshooting

Common Issues

SymptomLikely CauseSolution
No mails are sent at allThe master switch enabled is offSwitch enabled on — with it off the job exits before any query
No mails are sent although the checkboxes are tickedThe scheduled task is not runningCheck Settings > System > Scheduled tasks for topdata-product-watch.notify, or run bin/console topdata:product-watch:notify
A customer is subscribed but receives nothingThe item is not orderable: tdg_props_verfuegbarkeit = 4 (“auf Anfrage”) or available = falseThis is correct behaviour. Availability mirrors the buy gate of the shop theme
No back-in-stock mail ever arrivesThe ERP does not fill tdg_props_verfuegbarkeitWithout that field every product counts as orderable; check the field’s values in the product data
A price drop was not mailedIt did not clear both gates, or a cooldown is still runningThe price gate is conjunctive: the drop must clear minPriceDropPercentage and minPriceDropAmount. Check priceDropCooldownDays
A customer receives too many mailsDigests are off or the daily cadence is disabledOne mail per customer per run is automatic; set digestCooldownHours to cap one mail per day
A customer got no mail although several items changedmaxMailsPerRun was exhaustedNotifications beyond the budget are deferred, never lost — the next run sends them
A price drop of 2 % was ignored foreverThe baseline is downward-onlyDeliberate: a below-threshold drop never lowers the reference price, so rounding artefacts cannot spam. Widen minPriceDropPercentage or use minPriceDropAmount instead
An abandoned cart keeps generating remindersThe item is also on the wishlistItems on the wishlist are never pruned by cartStaleDays
The opt-in card is missing in the accountThe theme replaces the account overview templateRestore the template or insert the plugin’s product-watch-card.html.twig snippet
Mails arrive in the wrong languageThe shop language had no seeded templateEdit the three template types in Settings > E-mail templates
The activity log grows unexpectedlyA rule now evaluates as eventfulThe log records events, not evaluations; use topdata:product-watch:activity:cleanup and set activityRetentionDays

Troubleshooting Guide

1. Find out why one customer was not notified

Rehearse that customer. The report names every item and the first reason it was skipped — cooldown, threshold, or budget:

bin/console topdata:product-watch:notify --customer-id 42 --dry-run --tail-log

2. Find out whether a mail was really sent

The activity log is append-only evidence, so it is the authoritative answer — not a reconstruction. In the administration open Product watch log and filter by status, or search the customer’s mail address. A sent row also carries the order attribution when the customer converted within conversionWindowDays.

3. Check the configuration that is actually in effect

Every run reads the configuration fresh, so the admin values are what count. If a threshold does not behave as documented, compare it against the defaults in the Settings Guide — a setting left at “0” is not the same as a setting left empty.

4. Tune the spam guards before going live

The defaults are deliberately conservative. For a fast-moving catalogue you will usually want:

  • stockNotificationCooldownDays lower than 14 if your ERP stock flaps often
  • digestCooldownHours at 24 to keep one mail per customer per day
  • minPriceDropPercentage raised if customers consider small drops as spam

Change one value, run with --dry-run, read the report, then decide.

5. Reactivate customers after changing the opt-in rules

If you remove the opt-in card from a template, existing subscriptions stay in the database and customers keep being mailed. Untick the checkboxes for those customers (or send the unsubscribe link) to stop it.

Support

For additional support, please contact our technical support team or visit our support portal.