Reference Diagnostics
Available since v2.4
Scan your product catalogue for missing or duplicate reference fields that would break dynamic ad matching when you identify products by their SKU rather than their PrestaShop ID.
Overview
When you configure Pixel Plus for Facebook to send the Product Reference (SKU) as the content identifier in pixel events, that reference becomes the link between an event and a product in your Meta catalogue. Every ViewContent, AddToCart, and Purchase event carries that reference, and Meta looks it up in your catalogue feed to know which product was involved.
PrestaShop does not require references to be filled in, and does not enforce that they are unique. A product with no reference, or two products sharing the same reference, will silently break dynamic ad matching. Meta will either fail to match the event to any product, or randomly match it to the wrong one.
The Product Reference Diagnostics panel scans your entire catalogue and surfaces four types of problems. Each issue shows a direct link to the relevant product so you can fix it without leaving the Back Office. A fallback counter lets you see how often the module had to use a substitute identifier because a clean reference was not available.
This panel only appears when Product Identifier Type is set to Product Reference (SKU). It is automatically hidden in Product ID mode.
Configuration
- Go to Modules > Module Manager > Pixel Plus for Facebook > Configure.
- Confirm that Product Identifier Type is set to Product Reference (SKU) in the Product & Combination Options panel. Save if you just changed it.
- The Product Reference Diagnostics panel appears below. Click Run Diagnostics.
- Review the four summary tiles — each turns green (no issues) or amber/red (issues found).
- Click View on any tile to expand the detail table for that issue type.
- For each flagged item, click Edit to open the product directly and add or correct the reference, or click Dismiss to acknowledge the issue and remove it from future scans.
- After fixing products in another browser tab, click Run Diagnostics again to confirm the issues are resolved.
- Click Export (CSV) to download the full issue list if you have many products to address in bulk.
- If you previously dismissed issues and want to review them again, click Reset Dismissed Issues to clear all dismissals and show the full picture on the next scan.
Issue Types
| Issue | What it means | Impact on your ads |
|---|---|---|
| No Product Ref. | The product's reference field is empty. | The module uses the product's internal ID as a fallback. This fallback is unlikely to match your Meta catalogue feed unless your feed uses the same IDs. |
| Duplicate Product Ref. | Two or more products share the same reference string. | Meta may attribute the event to either product arbitrarily. Dynamic ads can show the wrong item. |
| No Combi Ref. | A product variant (combination) has no reference. | The module uses a product_reference-combination_id fallback (or product_id-combination_id if the parent product also has no reference). This format is unlikely to match your catalogue. |
| Duplicate Combi Ref. | Two or more combinations share the same reference. | Same arbitrary-matching problem as duplicate product references. |
Each tile shows a count of active (non-dismissed) issues. If any issues were previously dismissed, a smaller label appears beneath the count showing how many are hidden.
How It Works
Running a scan
When you click Run Diagnostics, the module queries all products and combinations in the current shop. It checks for empty reference fields and finds any reference values that appear on more than one product or combination. The results are loaded into the panel immediately, grouped by issue type.
Each product or combination in the results has an Edit link that opens the product page directly so you can add or correct the reference without hunting for it in the product list.
The scan is read-only. It does not modify any product data.
Summary cards and detail tables
The four summary tiles give you an at-a-glance count of each problem type. Tiles with issues turn amber (missing references) or red (duplicates). Tiles with no issues turn green.
Click View on any non-zero tile to expand the detail table beneath it. The table shows the product name, its current reference (or lack of one), the fallback identifier the module is currently using for it, and action buttons.
Fallback tracking
Every time a visitor triggers a pixel event for a product or combination that lacks a clean reference, the module records it. After you run a scan, a blue notice appears at the top of the results showing the total count and the date the tracking started. This tells you how many events have gone out with imperfect identifiers since you last reset the counter.
The fallback counter resets each time you click Reset Dismissed Issues — the dismissed list is cleared and the counter restarts from that point.
Dismissing issues
Clicking Dismiss on an item marks it as acknowledged. Dismissed items are hidden from future scans unless you click Reset Dismissed Issues to restore them. Dismissing is appropriate for products that are intentionally absent from your Meta catalogue — services, digital products, gift cards, and so on.
Dismissing does not fix the underlying problem. Events for dismissed products still use the fallback identifier, and they are still counted in the fallback total. Use dismissal only when you have decided the fallback is acceptable for a specific product.
Exporting to CSV
Click Export (CSV) to download a spreadsheet with all issues, including dismissed ones. The file columns are: Type, ID, Name, Reference, Attributes, Edit Link, Dismissed. Use this to share the issue list with a colleague or to build a bulk correction import.
Usage Examples
Example: Newly imported product catalogue You imported 500 products from a CSV and some rows had empty reference fields. Click Run Diagnostics immediately after the import. The No Product Ref. tile shows the count of affected products. Click View, then Export (CSV) to get the list. Open your original spreadsheet, add the missing references, re-import the products, and run the scan again to confirm everything is clean before launching catalogue campaigns.
Example: Supplier catalogue with shared SKUs across size variants
Your supplier reuses the same reference code for every size of a product — for example, SHIRT-001 appears on all sizes. In PrestaShop these should be separate combinations, each with their own combination reference. The diagnostics panel flags them under Duplicate Combi Ref. Click into the detail table, use the Edit link for each combination to assign unique references (for example SHIRT-001-S, SHIRT-001-M, SHIRT-001-L), then re-run the scan.
Example: Products not in your Meta catalogue Some of your products are service bookings or digital downloads that you have deliberately excluded from your Meta product feed. Run diagnostics and locate them in the results. Click Dismiss for each one. They will no longer appear in future scans and you can focus your fixing effort on genuine catalogue products.
Important Notes
- The panel is scoped to the currently active shop. If you run a multi-shop setup, switch to each shop and run the scan separately.
- The scan queries all products and combinations in the active shop. On large catalogues with thousands of products, the scan may take a few seconds.
- The panel is hidden when Product Identifier Type is set to Product ID. Switch to Product Reference (SKU) mode first if you want to run a scan.
- Dismissing issues is per-shop. Dismissed lists are stored as global configuration values (not per-shop), so dismissals made in one shop context apply across shops.
- After switching from Product ID mode to Reference mode, always run diagnostics before going live to catch any pre-existing gaps in your catalogue.
- If you change a reference that was already in use in pixel events and matched in your Meta catalogue, historical audience data tied to the old reference will no longer link to new events. Plan reference changes before launching catalogue-based campaigns.
Troubleshooting
| Problem | Solution |
|---|---|
| Diagnostics panel does not appear | Confirm Product Identifier Type is set to Product Reference (SKU) in the Product & Combination Options panel and that the setting is saved. The panel is hidden in Product ID mode. |
| Fallback notice keeps showing a high count after fixing products | Some products may have been dismissed rather than fixed, or new products were added without references. Click Run Diagnostics again to see if new issues appear. |
| Cannot find a product from the diagnostics list | Use the Edit link in the detail table — it opens that specific product page directly, bypassing the product list search. |
| Dismissed issues are reappearing | Clicking Reset Dismissed Issues clears all dismissals. Only use this button when you want to review everything from scratch. |
| Export CSV is empty | The CSV includes all issues including dismissed ones. If you have zero total issues (all clean or all dismissed), the file will contain only the header row. Run diagnostics with issues present before exporting. |
| Two products share a reference across different product lines | Each product must have a globally unique reference in PrestaShop. Prefix one product line's references to differentiate them — for example, change ABC-001 to LINE2-ABC-001. |
Frequently Asked Questions
Do I need to fix every issue before using dynamic product ads?
You do not need to fix every issue before enabling ads, but any unfixed product is a product Meta cannot match reliably. Products that are intentionally absent from your catalogue — services, gift cards, digital items — are fine to dismiss. Everything else should have a clean, unique reference.
What identifier does the module send when a product has no reference?
For a product with no reference, the module sends the product's internal PrestaShop ID as the fallback. For a combination with no reference, the fallback is product_reference-combination_id if the parent product has a reference, or product_id-combination_id if the parent also has no reference.
Can I undo a dismissal for a specific product without clearing all dismissals?
The panel itself does not have a per-item undismiss button. To restore a single dismissed item you need to click Reset Dismissed Issues, which clears all dismissals at once, then re-run diagnostics and dismiss only the items you want to keep hidden.
Does running diagnostics affect my live store or visitors?
No. The scan is entirely read-only and runs in the Back Office. It queries your product database but does not change any data or affect front-office performance.
Why are duplicate combination references flagged as more serious (red) than missing references (amber)?
Missing references have a predictable fallback that at least uniquely identifies the product by ID. Duplicate references mean two different products or combinations send the same identifier — Meta has no way to know which one was actually viewed or purchased, which leads to wrong product attribution in your dynamic ads.
The fallback notice says hundreds of events used ID fallback — is this a problem for past campaigns?
Past events have already been sent. Fixing references now corrects all future events, but it does not retroactively update previously sent data in Meta. If your campaigns were running with fallback identifiers that matched your catalogue, check whether the matching was correct before making changes.
Does the diagnostics panel check all shops at once or only the current shop?
It checks only the currently active shop. If you manage multiple shops, switch to each shop context from the top of the Back Office and run the scan separately in each one.
Related Features
- Product Identifier Type — The identifier type setting that determines whether this panel appears.