Advanced Options
Fine-tune how the pixel loads, handle non-standard payment modules, exclude specific customers or orders from tracking, and configure custom selectors for themes that deviate from PrestaShop's standard layout.
Available since v2.0
Overview
The Advanced Options panel covers edge cases and compatibility requirements that don't affect most stores. If your pixel is tracking correctly and your Purchase events are accurate, you can leave everything here at its defaults.
You will need this panel when:
- Your theme doesn't include PrestaShop's standard footer hook, so the pixel never fires
- A specific payment module's orders aren't being tracked because it uses a non-standard flow
- Staff orders, reseller orders, or internal test purchases are showing up in your Meta campaign stats
- Your CDN or server cache is serving an outdated version of the pixel script
- Your theme uses a custom button for Add to Cart, or a non-standard checkout module
The panel is divided into several sections: Pixel Load Optimization, Conversion Options, Refund/Cancellation Event, Customer Filtering, Display Options, Registration Options, PageView Options, Initiate Checkout Detection, Cache Prevention, and Custom Selectors. Each section is described below.
Configuration
Pixel Load Optimization
These settings control where and when the pixel script is injected into your store pages.
| Field | Default | Description |
|---|---|---|
| Force Pixels on Header | Disabled | Loads the pixel in the <head> instead of the footer. Enable only when your theme doesn't include PrestaShop's footer hook. The footer approach is preferred because it avoids blocking page rendering. |
| Deferred loading | Disabled | Delays pixel initialisation until after the page finishes loading. Can reduce perceived load time on slow connections, but any customer action that happens before the delay ends will not be tracked. |
| Deferred seconds | 0 | Seconds to wait after the page has fully loaded before the pixel initialises. Recommended value: 2–3 seconds when deferred loading is on. Integers only. |
| Defer only the first time | Enabled | Applies the deferred load only on the first page of a session. On subsequent pages, the pixel script is already in the browser cache and loads instantly, so deferral isn't needed. Leave this enabled whenever deferred loading is active. |
Force Pixels on Header and Deferred loading address different problems. If you enable both, the pixel fires from the header immediately — deferral has no effect. Choose one approach based on your situation.
Conversion Options
These settings control how Purchase events are fired and validated.
| Field | Default | Description |
|---|---|---|
| Exclude Back Office orders | Enabled | Orders created from the Back Office (by staff) don't trigger a Purchase event. Keep this enabled unless you specifically want staff orders tracked. |
| Use Ajax to confirm the conversion is sent | Enabled | The browser validates pixel availability via AJAX before firing the Purchase event. This prevents missed events for payment methods that redirect the customer away from the standard confirmation page. Recommended — leave enabled. |
| Use Cookies to prevent conversion duplicates | Disabled | Prevents the Purchase event from firing a second time for the same order if the confirmation page is reloaded or served from cache. Enable this if you see duplicate conversions caused by a caching module or Cloudflare. |
| Force Purchase event's Basic mode for | None | Per-payment-module checkboxes. Basic mode forces the Purchase event to fire when the customer visits the order confirmation page, bypassing the standard detection flow. Required for payment modules that use non-standard order confirmation flows. Enable only for the specific payment methods that need it. Note: basic mode does not prevent duplicates on its own — also enable cookie mode if duplicates occur. |
| Reload after order? | Disabled | Forces a one-time page reload after the order confirmation page loads. For a small number of payment modules that display the confirmation before the order is fully validated in PrestaShop. Usually not needed. |
| Exclude shipping in the order total | Disabled | Reports the order total without shipping costs in the Purchase event value field. Shipping is saved as a custom field inside the event. |
| Send order amount with taxes? | Enabled | When enabled, the Purchase value includes taxes. Disable to report tax-exclusive amounts. |
| Track only Payment Validated orders | Disabled | Beta feature. When enabled, only orders that reach a payment-validated status trigger a Purchase event immediately. Orders with unvalidated payment are held for up to the number of days set below. If they are validated within that period, the Purchase event is sent retroactively via the Conversion API. Requires CAPI to be configured. |
| Non-Validated Orders Validation limit | 7 days | How many days a pending order is held before being discarded. Only applies when "Track only Payment Validated orders" is on. |
| Order states to exclude | None | Purchase events are suppressed when an order reaches any of the selected statuses. Use this to exclude fraud-flagged, test, or administrative order states. |
Purchase event Debug Mode (described below under Customer Filtering) bypasses all deduplication logic. Never leave it active on a live store.
Refund / Cancellation Event
The Refund event is the canonical CAPI-only refund signal. Configuration and notes live in the single source-of-truth at Refund Event.
Customer Filtering
These settings let you suppress Purchase events for specific customers or groups.
| Field | Default | Description |
|---|---|---|
| Customer Groups to exclude | None | Purchase events are suppressed for customers belonging to the selected groups (for example, Employees, Resellers, Internal). This is a per-shop setting. |
| Customer ID to exclude | — | Comma-separated list of PrestaShop customer IDs. Purchase events are suppressed for these specific customers. This is a global setting — it applies across all shops in a multi-shop setup. |
| Purchase event Debug Mode | Disabled | Bypasses all deduplication logic and allows the same order to fire the Purchase event multiple times. Use only for testing in a development environment. Causes inflated stats in Meta if left on. |
Display Options
| Field | Values | Default | Description |
|---|---|---|---|
| External ID usage | Only on registered users / All users | Only on registered users | Controls when the cross-device matching identifier (external_id) is generated. The default is recommended: generating an external_id for guest visitors and then a different one after they register creates two IDs for the same person, which can cause attribution issues in Meta. |
Registration Options
| Field | Default | Description |
|---|---|---|
| Use Ajax to confirm Customer Registrations | Enabled | Validates CompleteRegistration events via AJAX. Recommended — leave enabled. |
PageView Options
| Field | Default | Description |
|---|---|---|
| Restrict PageView to known controllers | Disabled | When enabled, PageView events only fire on standard PrestaShop pages: product, category, cart, checkout, CMS, and contact pages. When disabled, PageView fires on every page including 404 errors and pages from custom modules. |
Initiate Checkout Detection
| Field | Values | Default | Description |
|---|---|---|---|
| Initiate Checkout Mode | Initial page / Click on the button | Initial page | Initial page fires the InitiateCheckout event when the customer first lands on the checkout. Click on the button fires when the customer explicitly clicks "Proceed to Checkout". Use the button mode if you see duplicate InitiateCheckout events in Meta Events Manager. |
Cache Prevention
| Field | Values | Default | Description |
|---|---|---|---|
| Static File Cache Prevention | Disabled / Always / Daily / Weekly / Monthly / Quarterly | Disabled | Appends a dynamic cache-busting parameter to Pixel Plus static file URLs. Enable only when a CDN or server cache (LiteSpeed, Nginx, Cloudflare) is serving an outdated version of the pixel script after a module update. Choose a frequency that matches how often you update the module. |
| Enhanced Cache Prevention | Disabled / Enabled | Disabled | Adds extra parameters to AJAX calls to prevent cached responses from interfering with tracking. Enable only if you experience missing events or inconsistent pixel behavior specifically caused by server-level caching. |
Custom Selectors
These fields are for stores whose themes or modules don't match the standard PrestaShop layout.
| Field | Description |
|---|---|
| Add To Cart custom selector | jQuery or CSS selector for a customized Add to Cart button. Use when your theme overrides the default button and AddToCart events aren't firing. |
| Start customization selector | CSS selector for a product customization button — a button the customer must click before customizing a product. Leave blank if your store doesn't use product customization. |
| Module name (Custom Checkout Page) | Technical name of a custom checkout module if your store doesn't use PrestaShop's standard checkout. Used to trigger InitiateCheckout events from the custom module's pages. |
| Search controller | Controller name of a custom search module. Visible in the URL after the controller= parameter when a search is performed. Leave blank to use PrestaShop's default SearchController. |
| Search query parameter | URL parameter name for the search query string. Common values: s, q, term. Leave blank to use the default. |
How It Works
Pixel Load Strategy
By default, the pixel script loads in the footer. This is the safest approach: footer scripts don't block page rendering, so your storefront appears to load faster. If your theme doesn't include the displayFooter or displayBeforeBodyClosingTag hooks, the pixel never fires — switch on Force Pixels on Header to inject it from the <head> tag instead.
Deferred loading is a third option: the pixel waits until the entire page has finished rendering before it initialises. This can improve PageSpeed scores because the pixel is no longer in the critical rendering path. The trade-off is that visitor actions taken immediately after the page loads — before the configured delay has passed — won't be captured. The "Defer only the first time" refinement addresses most of this: once the pixel script is in the browser's cache from a previous page in the same session, it loads essentially instantly and deferral is unnecessary.
Purchase Event Delivery
Most payment modules follow a standard flow: the customer completes payment, the payment module redirects to PrestaShop's order confirmation page, and the module fires the Purchase event from there. When a payment module uses its own confirmation page or redirects the customer outside of PrestaShop's standard flow, the standard detection fails. Force Purchase event's Basic mode tells the module to fall back to firing on the confirmation page URL regardless of how the order was created.
Use Ajax to confirm the conversion is sent adds a validation layer: before firing the Purchase event from the browser, the module checks via AJAX that the order has been properly registered. This prevents the event from misfiring when a payment redirect interrupts normal page loading.
Customer Filtering
Customer group exclusion (FCTP_ORDER_CUSTOMER_GROUP_EXC) is evaluated at the time the Purchase event would normally be sent. If the customer placing the order belongs to an excluded group, the event is silently skipped. The order processes normally in PrestaShop — only the Meta tracking is suppressed.
Customer ID exclusion (FCTP_ORDER_CUSTOMER_ID_EXCLUDE) works the same way for specific individuals rather than groups. Because it's a global setting, it applies across all shops in a multi-shop setup — useful for excluding an account used for regular cross-shop testing.
Usage Examples
Example: Theme with no footer hook
Your store uses a custom theme that was built without PrestaShop's standard footer hooks. The pixel never fires because the footer injection point doesn't exist. Enable Force Pixels on Header — the pixel is then injected into the <head> of every page, which all themes include.
Example: Staff and reseller orders inflating conversion stats You notice your Meta Purchase event count is higher than your actual customer sales because staff orders and reseller orders are included. Add your "Employees" and "Resellers" customer groups to Customer Groups to exclude. From that point forward, orders from those groups don't generate a Purchase event, while the orders themselves continue to process normally in PrestaShop.
Example: Duplicate Purchase events from a page cache Your store runs a full-page caching plugin and you're seeing duplicate Purchase events for the same order in Meta. Enable Use Cookies to prevent conversion duplicates — the module sets a short-lived cookie when the Purchase event fires, and if the confirmation page loads again (from cache) the cookie prevents a second event from being sent.
Example: CDN serving an outdated pixel script After updating Pixel Plus, some visitors still trigger events using old tracking logic because your CDN cached the previous version of the script. Set Static File Cache Prevention to Weekly — this adds a date-based parameter to the script URL that changes weekly, forcing the CDN to fetch and serve the updated file.
Example: InitiateCheckout firing twice You see two InitiateCheckout events per checkout session in Meta Events Manager. This happens when the customer both lands on the checkout page and clicks a "Proceed" button, both of which trigger the event. Switch Initiate Checkout Mode from Initial page to Click on the button so the event only fires on the explicit click.
Important Notes
- Force Pixels on Header and Deferred loading can be enabled at the same time, but the result is that the header placement wins: the script loads immediately from the
<head>. There is no combined benefit — choose the option that fits your situation. - Purchase event Debug Mode must never be left active on a live store. It bypasses all deduplication checks and causes inflated Purchase event counts in Meta, which corrupts campaign optimisation data.
- Customer ID to exclude is a global setting — it applies across all shops in a multi-shop setup. Customer group exclusion is per-shop.
- Track only Payment Validated orders is a beta feature and requires the Conversions API to be active. Orders held in the pending queue are processed retroactively by the CAPI — the browser pixel does not send delayed events.
- Static File Cache Prevention increases CDN cache miss rates for Pixel Plus static files. Enable it only when you have confirmed that stale file caching is actively causing a tracking problem.
- The External ID usage setting affects cross-device attribution in Meta. Changing it from "Only on registered users" to "All users" will generate
external_idvalues for guest visitors. If a guest later registers, they will have two differentexternal_idvalues, which can reduce attribution accuracy.
Troubleshooting
| Problem | Solution |
|---|---|
| Pixel doesn't fire on the storefront at all | Your theme likely doesn't include a footer hook. Enable Force Pixels on Header. |
| AddToCart events missing on a custom theme | Add the jQuery/CSS selector for your theme's Add to Cart button in Add To Cart custom selector. |
| InitiateCheckout fires twice per checkout | Switch Initiate Checkout Mode from Initial page to Click on the button. |
| Staff or internal test orders appear in Meta stats | Ensure Exclude Back Office orders is enabled. Also add internal customer IDs or a staff customer group to the exclusion fields. |
| PageView events from 404 error pages polluting Meta data | Enable Restrict PageView to known controllers. |
| Duplicate Purchase events in Meta | Enable Use Cookies to prevent conversion duplicates. Also ensure the payment module for which duplicates occur is not set to Basic mode without cookie protection. |
| Purchase events not tracked for a specific payment method | Enable Force Purchase event's Basic mode for that payment module. If duplicates appear afterward, also enable Use Cookies to prevent conversion duplicates. |
| Outdated pixel script being served after a module update | Enable Static File Cache Prevention and choose a suitable frequency (Daily or Weekly). |
| Missing events that seem related to AJAX caching | Enable Enhanced Cache Prevention to add cache-busting parameters to AJAX calls. |
Frequently Asked Questions
Should I enable deferred loading on my store?
Only if you have confirmed that the pixel script is in the critical rendering path and affecting your PageSpeed score. For most stores, the default footer loading is sufficient and ensures no events are missed. If you do enable it, also enable 'Defer only the first time' to minimise the risk of missing events on return visitors.
Should I report the Purchase value with or without shipping?
Most advertisers include shipping to report the full revenue amount. If you compare Meta's reported Purchase value to your own revenue reports, the most important thing is consistency with the method your accounting uses. Choose whichever setting matches how you measure revenue elsewhere.
What is the difference between 'Only on registered users' and 'All users' for External ID?
external_id is a cross-device matching identifier Meta uses to link a visitor's actions across sessions and devices. With 'Only on registered users', a stable ID is only generated once the visitor has an account. With 'All users', a temporary ID is created for guest visitors too. The risk with 'All users' is that a guest who later registers will receive a second, different ID — Meta may treat them as two separate people, reducing attribution accuracy.
My custom payment module isn't being tracked. What should I try first?
First, enable Force Purchase event's Basic mode for that payment module. This forces the Purchase event to fire when the customer reaches the order confirmation page, regardless of how the payment was processed. If duplicate events appear after enabling basic mode, also enable Use Cookies to prevent conversion duplicates.
Can I exclude just one or two specific customers without creating a whole customer group?
Yes. Enter their PrestaShop customer IDs as a comma-separated list in Customer ID to exclude. Note that this is a global setting — it applies across all your shops in a multi-shop setup, not just the current shop.
What happens to orders held in the pending queue if the payment is never validated?
The module holds unvalidated orders for the number of days set in Non-Validated Orders Validation limit (default 7 days). If the order is not validated within that window, the Purchase event is discarded and never sent to Meta. This prevents stale or failed orders from generating false conversion signals.
Related Features
- Purchase Event Advanced Settings — Validated-only tracking, deferred payments, duplicate prevention, and order status exclusions.
- Trackable Events — Enabling, disabling, and customising values for all tracked events.
- GDPR & Cookie Consent — Consent blocking interacts with how and when the pixel loads.
- Conversion API (CAPI) — Required for the Refund event and deferred Purchase events to function.