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
- Follow the Installation Guide.
- Set the thresholds in the Settings Guide — the defaults are sensible, but the price-drop gates are worth a look before you go live.
- Read how customers opt in and how the hourly job behaves in the Usage Guide.
- 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
- Log in to your Shopware admin panel.
- Go to Extensions > My extensions.
- Find “Topdata Product Watch SW6” in the list.
- 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_verfuegbarkeit | Meaning | Orderable |
|---|---|---|
| 1 | tomorrow | yes |
| 2 | 3–5 days | yes |
| 3 | 6–15 days | yes |
| 4 | auf 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 = 4into the cart and runbin/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
enabledmust 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-runand 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.
| Setting | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Enable product notifications — Master switch. When off, the hourly job exits immediately and no mail is sent. |
stockNotificationsEnabled | bool | true | Enable “available again” notifications — Allow back-in-stock mails. Orderable means availability != “on request” and the product is available. |
priceNotificationsEnabled | bool | true | Enable price-drop notifications — Allow price-drop mails. Only the customer-effective price is compared. |
minPriceDropPercentage | float | 3.0 | Minimum price drop (percent) — A price drop is only mailed once it clears this percentage AND the minimum amount below. 0 disables the percentage gate. |
minPriceDropAmount | float | 0.0 | Minimum price drop (absolute amount) — Additionally required absolute drop. 0 = disabled, so only the percentage matters. Both gates are conjunctive. |
priceDropCooldownDays | int | 7 | Minimum days between price mails per item — Guards against repeated price mails for the same item. 0 disables the cooldown. |
stockNotificationCooldownDays | int | 14 | Minimum days between “available again” mails per item — Guards against ERP stock flapping (1 -> 4 -> 1). 0 disables the cooldown. |
digestCooldownHours | int | 24 | Minimum 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. |
cartStaleDays | int | 30 | Stop 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. |
customerBatchSize | int | 200 | Customers per job run — How many subscribers are processed per page. The rest is picked up by the next hourly run. |
maxMailsPerRun | int | 200 | Maximum mails per job run — Hard budget. A digest counts as one mail. Notifications beyond the budget are deferred to the next run, never lost. |
activityLogEnabled | bool | true | Write the activity log — Support and evidence log. Records events only (mails sent, named suppressions, mail failures, conversions) — never one row per evaluation. |
activityRetentionDays | int | 365 | Activity log retention (days) — Older rows are deleted by topdata:product-watch:activity:cleanup. |
conversionWindowDays | int | 14 | Conversion 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. |
onboardingBannerEnabled | bool | true | Show 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
- The customer logs in to the storefront.
- In Account the plugin adds a Produkt-Benachrichtigungen card below the overview, with
two independent checkboxes:
- Enable “available again” notifications
- Enable price-drop notifications
- 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:
| Source | How it is captured |
|---|---|
| Cart | Event-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. |
| Wishlist | Authoritative: 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:
| Situation | Result |
|---|---|
| One item became orderable again | Product-specific “available again” mail |
| One item’s price dropped past the threshold | Product-specific price-drop mail |
| Two or more items changed | One digest listing all of them |
| Nothing relevant changed | No mail, and no entry in the activity log |
Two limits keep the inbox healthy:
digestCooldownHourscaps a customer at one mail per day, no matter how much changed.maxMailsPerRunis 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
minPriceDropPercentageandminPriceDropAmount. 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.
priceDropCooldownDayskeeps 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
conversionWindowDaysof a mail is recorded on that same row asorder_id+converted_at, giving an honest “stimulated orders” figure instead of a guess. -
Retention: rows older than
activityRetentionDaysare removed bybin/console topdata:product-watch:activity:cleanup --dry-run # preview bin/console topdata:product-watch:activity:cleanup # deleteAdd
--daysto use a different window or--customer-idto clean one customer.
Changing the Mails
The three mail template types are owned by the plugin and editable in the administration:
| Template | Sent for |
|---|---|
product-watch-stock | a single item became orderable again |
product-watch-price | a single item’s price dropped |
product-watch-digest | two 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
| Symptom | Likely Cause | Solution |
|---|---|---|
| No mails are sent at all | The master switch enabled is off | Switch enabled on — with it off the job exits before any query |
| No mails are sent although the checkboxes are ticked | The scheduled task is not running | Check Settings > System > Scheduled tasks for topdata-product-watch.notify, or run bin/console topdata:product-watch:notify |
| A customer is subscribed but receives nothing | The item is not orderable: tdg_props_verfuegbarkeit = 4 (“auf Anfrage”) or available = false | This is correct behaviour. Availability mirrors the buy gate of the shop theme |
| No back-in-stock mail ever arrives | The ERP does not fill tdg_props_verfuegbarkeit | Without that field every product counts as orderable; check the field’s values in the product data |
| A price drop was not mailed | It did not clear both gates, or a cooldown is still running | The price gate is conjunctive: the drop must clear minPriceDropPercentage and minPriceDropAmount. Check priceDropCooldownDays |
| A customer receives too many mails | Digests are off or the daily cadence is disabled | One mail per customer per run is automatic; set digestCooldownHours to cap one mail per day |
| A customer got no mail although several items changed | maxMailsPerRun was exhausted | Notifications beyond the budget are deferred, never lost — the next run sends them |
| A price drop of 2 % was ignored forever | The baseline is downward-only | Deliberate: 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 reminders | The item is also on the wishlist | Items on the wishlist are never pruned by cartStaleDays |
| The opt-in card is missing in the account | The theme replaces the account overview template | Restore the template or insert the plugin’s product-watch-card.html.twig snippet |
| Mails arrive in the wrong language | The shop language had no seeded template | Edit the three template types in Settings > E-mail templates |
| The activity log grows unexpectedly | A rule now evaluates as eventful | The 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:
stockNotificationCooldownDayslower than 14 if your ERP stock flaps oftendigestCooldownHoursat 24 to keep one mail per customer per dayminPriceDropPercentageraised 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.