DF Samples — Product sample ordering (PrestaShop 8 & 9)

Overview

DF Samples adds an “Order a sample” button to your product pages. The sample can be free or charged a few euros. The module automatically generates a hidden sample product for each product enrolled in the programme, enforces per-customer limits, tracks the sample-to-purchase conversion and automatically follows up with your customers by email, with an optional discount voucher.

The module is compatible with PrestaShop 8.0 to 9.x, multistore and multilingual, and uses no core override.

Installation

1. In the back office, go to Modules > Module Manager.
2. Click Upload a module and drop the dfsamples.zip file.
3. On install, the module creates its two tables, its default settings, a security token for the cron task and an admin tab under Catalog > Samples (DF).

The module registers on the displayProductActions, displayProductAdditionalInfo, actionFrontControllerSetMedia, actionValidateOrder and actionObjectProductDeleteAfter hooks.

Adding a product to the sample programme

1. Open Catalog > Samples (DF).
2. Click Add.
3. Search for a product by name or reference in the autocomplete field, then select it from the list. Products already enrolled in the programme and sample products themselves are automatically excluded from the results.
4. Enter the sample price, tax included. Enter 0.00 for a free sample.
5. Set the maximum per customer for this product (0 = unlimited).
6. Save.

What the module does on save

The module automatically creates a hidden sample product:

• Name prefixed and translated into your languages: Échantillon, Sample, Muestra, Muster, Campione.
• Dedicated reference in the SMPL format, followed by the source product ID.
• Tax-excluded price computed from the tax-included price you entered and the VAT rate of the source product.
• Cover image of the source product copied and resized across all image formats.
• Visibility set to “nowhere”: the product appears neither in navigation nor in search.
• Unlimited stock (backorders allowed) so a request is never blocked.
• Sample weight taken from the global setting, used by carriers.

If you later change the price, the global weight or the active status, the sample product is resynchronised. If the sample product was manually deleted from the catalogue, it is recreated on the next save.

Settings

Settings are located at the bottom of the Catalog > Samples (DF) page, below the product list.

General settings

• Button position — below the add-to-cart button (displayProductActions) or in the additional information block (displayProductAdditionalInfo). Change this setting if your theme does not render the first hook.
• Default sample price, tax included — value pre-filled when creating a new sample.
• Sample weight — in kilograms, applied to all generated sample products. Used for shipping cost calculation.
• Require customer account — recommended and enabled by default. Per-customer limits can only be reliably enforced on identified customers.
• Conversion counted on — the purchase of the sampled product only, or any subsequent purchase.

Limits

• Maximum samples per cart — 0 for unlimited.
• Maximum samples per customer per window — all sample products combined. 0 for unlimited.
• Rolling window — in days, 30 by default. Per-customer counters apply over this rolling period.

The same sample can never be added twice to the same cart, regardless of the configuration.

Automatic follow-up

• Enable follow-up emails.
• Delay after the sample order — in days, 14 by default.
• Include a discount voucher — a customer-restricted, single-use voucher is generated for each follow-up.
• Voucher amount — as a percentage, 10 by default.
• Voucher validity — in days, 30 by default.

The token-secured cron URL is shown in this section as well as in the statistics panel.

Setting up the cron task

Follow-ups are sent by a cron task. Schedule the URL shown in the settings every hour. Example crontab:

0 * * * * wget -q -O /dev/null "https://your-shop.com/module/dfsamples/cron?token=YOUR_TOKEN"

Each run processes up to fifty pending follow-ups and returns a JSON summary: number of records processed, sent, skipped and waiting.

Rules applied by the cron task

• Only samples that have not converted and have not been followed up yet are considered.
• The sample order must have reached a paid, shipped or delivered status.
• Cancelled orders and payment errors are permanently skipped.
• Orders awaiting payment are postponed to the next run.

Conversion tracking

On every order validation, the module records the sample lines: customer, email, source product, language and shop.

When that same customer places a later order, the module marks the corresponding samples as converted:

• In product mode (default): only if the order contains the product whose sample was received.
• In any purchase mode: as soon as the order contains any real product.

The current order is excluded from the calculation: ordering a sample and its product in the same cart does not count as a conversion.

Dashboard

The panel displayed above the product list shows:

• Samples ordered — total number of sample lines recorded.
• Conversions — number of samples followed by a purchase, and the associated conversion rate.
• Revenue from conversions — sum of the tax-included amount of conversion orders.
• Pending follow-ups — number of samples eligible for a follow-up not yet sent.

The product list also shows, per product, the number of samples ordered and the number of conversions.

Follow-up emails

Templates are located in the module mails folder, in five languages: fr, en, es, de, it. Each language has an HTML and a plain-text version of the dfsamples_followup template.

Available variables: firstname, lastname, product_name, product_link, voucher_block and shop_name. The voucher_block variable contains the formatted discount voucher, or an empty string if the voucher is disabled.

You are free to customise these templates. Keep the variables in curly braces so that the replacement works.

Discount vouchers

When the option is enabled, each follow-up generates a PrestaShop cart rule:

• Code in the SMPL format, followed by eight random characters.
• Restricted to the recipient customer.
• Usable only once.
• Percentage discount, on the tax-included amount.
• Configurable validity period.

Generated vouchers are visible under Discounts > Cart rules.

Uninstall

On uninstall, the module removes its two tables, its settings and its admin tab. Generated sample products are deactivated, not deleted, so the history of your past orders stays consistent. You can delete them manually from the catalogue if you wish.

Troubleshooting

The button does not appear on the product page

Check that the product is enrolled in the programme and active under Catalog > Samples (DF). If the product is indeed active, change the “Button position” setting: some themes do not render the displayProductActions hook.

Follow-ups are not sent

Check that the cron task is scheduled and that the URL contains the right token. Call the URL manually in a browser: the module returns a JSON summary. Also check that the follow-up option is enabled and that the configured delay has actually elapsed since the sample orders.

The sample price is not the expected one

The price is entered tax included and converted to tax excluded using the VAT rate of the source product. If the source product has no tax rule, the tax-excluded price equals the price you entered.

A customer exceeds their limits

Per-customer limits only apply to identified customers. Enable the “Require customer account” setting to make them effective.