User guide

Coming from version 1

If your shop runs Order Source Tracking 1.x, the earlier name of this module, you upgrade in place and keep your data. The module has a new name, a new menu and a new way of recording visits, and its dashboard counts differently. This chapter tells you what to expect.

How to upgrade

Check that your shop runs PrestaShop 8.0 or later. Version 2 does not install on PrestaShop 1.7; such a shop stays on version 1.
Open Modules › Module Manager, click Upload a module and select the new zip. PrestaShop runs the upgrade.
Open Orders › Order sources › Settings and read the Checklist.

You do not uninstall version 1 first. If the upgrade stops half-way, for example because a large table takes too long, upload the zip again: the upgrade continues where it stopped.

What is kept

Data of version 1	After the upgrade
The sources of your orders	Kept, for every order that still exists. Source and medium are now in small letters, so “Facebook” and “facebook” have become one source.
Visits	Kept when they are younger than 13 months. Older visits are not carried over. A large table is copied month by month, the newest first; what the upgrade does not finish, the daily housekeeping does. Copied visits have no landing page, term, content or kind of ad click: version 1 did not store them.
Your settings	Kept: the attribution window, your referrer rules, your excluded sites, your test addresses, and the two switches for the first and the last touch columns of the module’s Orders tab.
Visitors on their way	A visitor who arrived before the upgrade and orders after it still gets the right first and last touch: the module reads the cookies of version 1 once, then removes them.
The tables of version 1	Not touched by the upgrade. They stay for 30 days as a safety net and are then removed by the housekeeping. Until then the Checklist shows an amber line that says so, and Data and upkeep names the date. It is information, not a problem.

What changed

Topic	Version 1	Now
Name and menu	Order Source Tracking: three entries under Orders, and the settings in the Module Manager	Order Source Pro: one entry, Order sources, with the tabs Dashboard, Orders, Visits and Settings
Orders confirmed by the payment provider in the background	Had no source	Get their source: it travels with the cart
Orders created in the back office	Took the source of the employee’s own visits	Have no source, which is the truth
Referrer rules and excluded sites	Were saved and never used	Take effect
Coming back from a payment page	Could become the source of the order	Never counts; your own domains and the usual payment providers are excluded
Ad clicks without UTM parameters	Not recognised	Recognised (Ad platforms: recognised without UTM parameters)
What a visit stores	IP address, browser, device and the pages seen	None of these (What is stored, and what is not)
Settings	One page in the Module Manager	A tab with sections, with new settings for detection, consent, retention and display. They start with the same values as after a new installation (Settings)

Screens that are gone

The two CSV import screens, the visitor export screen and the date range export above the order list. The Orders and Visits tabs export with the button of their list.
The details page of a visitor. Everything a visit holds is in the list.
The settings “Track First UTM” and “Track Last UTM”. They never had an effect.

The new numbers on the dashboard

After the upgrade the dashboard shows a note: “The numbers on this page changed in version 2.1. Only valid orders count, and revenue is what was paid without tax and without shipping, in your default currency, as on the dashboard of PrestaShop. An order counts on the day it was placed.” It stays until you click Dismiss. What each number means explains the day an order counts on, the one difference kept on purpose. Behind the note:

Number	Version 1 counted	Now
Orders	Every order, cancelled and unpaid ones included	Valid orders only, and all of them: orders without a source are the row Not tracked
Revenue	The totals of the orders, not converted between currencies	Without tax and without shipping, converted to your default currency
Orders without a source	“Unknown”	Not tracked, with the figure Tracked orders to say how many have a source

So the totals of a past month can differ from what version 1 showed. Nothing was lost: cancelled and unpaid orders no longer count, and revenue leaves out tax and shipping. To report with tax, switch Revenue on the dashboard to With tax (Orders: where the source is shown). In a multistore, old visits that led to no order are all in the default shop (Visits from version 1).

Questions and problems

Start with the Checklist in Settings › Overview: most problems show there, with a link to the section that fixes them. A fault in the module does not stop a page of your shop: it is written to Advanced Parameters › Logs instead, in a line that starts with pch_ordersource.

Problems

No visits appear

Make a test visit: open your shop in a private window and add ?utm_source=test to the address. If recording starts After the visitor accepts cookies, accept the cookie banner on that page first. Open the Visits tab after a minute.
If it is missing and recording waits for consent, your banner may not report the visitor’s answer to the module: then nothing at all is recorded (Consent: when recording may start).
Look at Settings › Detection. With Server only and a page cache, cached pages are not recorded. Choose Script only, as My shop uses a page cache or a CDN explains.
With Script only, a browser that blocks scripts, or a rule of a firewall in front of your shop, can stop the script’s report. Try another browser without extensions.
Still nothing? Switch on Log decisions in Settings › Data and upkeep, repeat the test visit and read Advanced Parameters › Logs: the module writes what it recorded or skipped, and why, in lines that start with pch_ordersource. Switch the setting off afterwards.

Some arrivals are skipped on purpose: search engine robots and monitoring tools, a page the browser only loads in advance, and the return from a payment page.

Orders without a source (Not tracked)

An order has no source when the module could not link it to a visit. The usual reasons:

The order was created in the back office, or through the webservice.
The order was placed before the module was installed.
The visitor’s browser refused or deleted the cookie, or the visitor did not accept in your cookie banner.
The visit itself was not recorded, for one of the reasons above.

A share of untracked orders is normal. The figure Tracked orders on the dashboard tells you how large it is. If it is low, check the consent setting first: with After the visitor accepts cookies, every visitor who does not accept is untracked.

The numbers differ from Google Analytics

They will, and neither tool is wrong. The two count different things:

Difference	Order Source Pro	An analytics service
Orders	The real orders of your shop, when they are valid, including those confirmed by the payment provider in the background.	The orders its script saw on the confirmation page.
Revenue	Without shipping, without tax unless you chose otherwise, in your default currency.	What your shop’s tracking code sends, often with tax and shipping.
Which visit gets the order	First touch, or last touch that was not direct, inside your attribution window.	Its own model and its own window.
A visit	One arrival; 30 minutes without a page ends it.	A session, by its own rules.
Who is counted	Depends on your Detection and Consent settings.	Depends on its own consent settings and on script blockers.

Compare with PrestaShop’s own dashboard instead: it counts orders and sales by the same rules. What each number means names the one thing that differs on purpose, the day an order is counted on.

My shop uses a page cache or a CDN

Choose Script only in Settings › Detection, as the help of the field advises. It is the one to use when the cache or the CDN removes cookies from the pages it stores. Never Server only: a cached page is sent without the shop being asked. The Checklist warns you when it finds a page-cache module together with Server only. If your cache is set up outside PrestaShop, for example at your hosting company, the checklist cannot see it: choose the setting yourself.

My shop has a cookie banner

Decide whether your visitors must agree before they are tracked; that is a legal question (Consent: when recording may start). If yes, choose After the visitor accepts cookies and make sure your banner reports the answer: a banner with Google Consent Mode does it by itself, any other banner needs one call. Then test: in a private window, a visit must appear in the Visits tab only after you accepted.

A payment provider appears among my sources

Add its domain in Settings › Excluded sites (Excluded sites: pages a customer only comes back from). Visits already recorded keep their source; new ones no longer get it.

A partner’s site is listed under its domain, or my own visits are counted

A site without a rule is recorded under its domain, as a referral: give it the source you want in Settings › Referrer rules (Referrer rules: a source of your choice for a site). To keep your own visits out of the dashboard, add your address under Test IP addresses in Settings › Attribution.

The checklist says that housekeeping has not run

Housekeeping runs when someone opens the back office. Click Run now in Settings › Data and upkeep. For a shop whose back office is not opened every day, let a scheduled task call the Maintenance address once a day (The maintenance address).

Visits from one office or one network are missing

To stop floods, the module records at most 30 new visits per minute from one address. Real visitors never reach that, unless your shop sits behind a proxy or a CDN that shows the shop one single address for everybody. Your hosting company can set the server up so that the shop sees the real address of each visitor.

An employee cannot open the module’s tabs

The four tabs are pages of the back-office menu. Give the employee’s profile the right to see them in Advanced Parameters › Team › Permissions. The Source column and the Order source card need no right of their own.

Known limits

Limit	What it means (a property of the way the module works, not a fault)
One browser is one visitor	Someone who clicks an ad on a phone and buys on a laptop is two visitors. The order gets the source the laptop arrived with.
Orders created in the back office	They have no source: no visit of the customer leads to them. The same holds for orders that arrive through the webservice.
Visitors who refuse the cookie	They are not tracked, and their orders have no source. With After the visitor accepts cookies, that is every visitor who does not accept. A browser that keeps no cookies looks new on every page; the flood limit keeps it from filling your lists.
Consent given late	With After the visitor accepts cookies, a visitor who accepts only after leaving the first page is recorded as direct.
A proxy that hides the visitors’ addresses	The flood limit then counts everybody together (see above).
Several shops	A shop in a folder of another shop shares its visitors with it. Visits from version 1 that led to no order are in the default shop (Several shops).
First and last touch only	The module does not split an order between several sources, and it does not import ad cost. An order gets its source once: a setting or a rule you change later does not rewrite orders and visits already stored.
PrestaShop 1.7	Not supported by version 2.

Frequently asked questions

What do my customers see?

Nothing: no pop-up and no banner. Depending on Detection, one small script is loaded after the page. It sends one short report per visit, to your own shop.

Why is “direct” so large?

Direct holds every visit that says nothing about its origin: typed addresses and bookmarks, and also links in apps, in e-mail programs and in messages that carry no parameters. Tag the links you publish with UTM parameters (Building campaign links) and that share shrinks.

Support

PrestaChamps develops and supports this module. Sign in on addons.prestashop.com, open your order of Order Source Pro and write to the developer with the contact form. Tell us your PrestaShop, PHP and module versions, what you expected and what happens instead, with a screenshot of the Checklist. If visits or sources are missing, switch on Log decisions, repeat the case and send us the module’s lines of Advanced Parameters › Logs. Never send your own password: if we need to see your back office, we ask for a temporary employee account.

For developers

This chapter is for the person who sets up your cookie banner, your server or your reports: the JavaScript calls for a cookie banner, the address for a scheduled task, and the tables behind the lists.

The JavaScript calls for a cookie banner

They matter only when When recording starts is set to After the visitor accepts cookies (Consent: when recording may start). The module’s script then stores nothing and sets no cookie until it learns that the visitor agreed.

Google Consent Mode

Nothing to add. The script reads the consent entries your banner pushes to window.dataLayer:

An entry that sets analytics_storage to granted starts the recording, whether it is a default or an update entry.
An update entry that sets it to denied withdraws consent.
A default entry with denied is the banner’s starting state: it changes nothing.

Any other banner

window.pchOrderSource.grantConsent();    // the visitor accepted statistics cookies
window.pchOrderSource.revokeConsent();   // the visitor withdrew, or refused after having accepted

A banner that knows the stored answer early can set a flag instead, before the module’s script runs: window.pchOrderSourceConsent = 'granted', or 'denied'.

What happens	Effect
Consent is granted on the page the visitor arrived on	The visit is recorded with its real source. Later pages of the same visit need no new signal.
Consent is granted on a later page	The visit is recorded as direct: the campaign of the arrival is no longer known.
Consent is withdrawn	The script removes the visit marker, and the shop removes both cookies. Visits already stored are not deleted (Export and erase a customer’s data).

To check your setup, open the shop in a private window: before you accept, no cookie named pch_os_v or pch_os_s may exist; after you accept, both do, and the visit is in the Visits tab.

The maintenance address

The housekeeping starts when someone opens the back office. If yours stays closed for days, let a scheduled task (a cron job) call the maintenance address once a day.

Open Settings › Data and upkeep and click Copy next to Maintenance address.
In the control panel of your hosting, create a scheduled task that calls this address once a day, at a quiet hour. Most panels have a field for an address; on a server with a command line, a line like this does it:

# every day at 03:15; paste the address you copied between the quotes
15 3 * * * curl -fsS "PASTE-THE-MAINTENANCE-ADDRESS-HERE" > /dev/null

A call that worked answers with OK and what it deleted, for example OK visits=0 cart_links=0 legacy_tables=0. The address contains a secret token: treat it like a password. A call without the right token is refused and does nothing. It is the same address for all shops of a multistore.

The tables

The module keeps its data in four tables, after your shop’s table prefix (ps_ in most shops). Read them for your own reports; do not write to them.

Table	One row is
`pch_ordersource_visit`	A visit: `visitor_key`, `id_shop`, `date_add`, `source`, `medium`, `campaign`, `term`, `content`, `click_id_type`, `landing_path`, `referrer_host`, `id_order`, `is_test`, `origin`.
`pch_ordersource_order`	The source of an order: `id_order`, `id_shop`, then `first_source`, `first_medium`, `first_campaign`, `first_term`, `first_content`, `first_click_id_type`, `first_landing_path`, `first_date`, and the same eight columns with `last_`.
`pch_ordersource_cart`	The link between a cart and its visitor: `id_cart`, `visitor_key`, `date_add`.
`pch_ordersource_guard`	The counter of the flood limit. The daily housekeeping deletes its rows.

Values worth knowing

A direct visit is stored as source (direct) and medium (none). A link with utm_source and no utm_medium has the medium (not set).
click_id_type is empty or one of google, microsoft, tiktok, meta.
origin says how the visit was recorded: 0 by the shop, 1 by the script, 2 copied from version 1, 3 read from a cookie of version 1. Rows with 3 exist for attribution only; leave them out when you count visits, as the dashboard does.
The dashboard counts orders with valid = 1 by date_add and adds up (total_paid_tax_excl - total_shipping_tax_excl) / conversion_rate (with tax: the two _tax_incl columns). An order without a row in pch_ordersource_order is not tracked.

How the module connects to your shop

The script’s report. One short request per visit to /module/pch_ordersource/beacon of your own shop, which accepts requests from your shop’s pages only. A firewall in front of your shop has to let it pass.
The order. The module links a cart to its visitor when the cart is saved in the storefront, and writes the source when PrestaShop validates the order. It reads no cookie at that moment, so an order confirmed by a payment provider’s server gets its source too. Carts created in the back office or through the webservice are not linked.

↑

Coming from version 1 — Order Source Pro