DataFirefly Affiliate Program: affiliate program for PrestaShop

Installation

Install the module from Modules > Module Manager > Upload a module by sending the ZIP file, or copy the dfaffiliate folder into the /modules/ directory of your shop and click Install.

On installation, the module creates its tables, saves its default settings and adds an Affiliation menu under Sell with five entries: Affiliates, Commissions, Statements and payouts, Commission rules and Settings. The Configure button in the Module Manager opens the settings page, which starts with an overview of the program.

To move from version 1.0.0 to 1.1.0, just upload the new ZIP: the upgrade script adds the new settings and hooks without touching existing affiliates, commissions or statements.

First settings

Check at least these points before inviting your first affiliates:

• Default commission value: 10 % of products tax excluded on installation, or a fixed amount per order.
• Cookie lifetime: 30 days by default, the time window between the click and the order.
• Approve the commission on and Reject the commission on: the order statuses that confirm payment, and those that cancel (cancelled, refunded, payment error).
• Hold period: 30 days by default. An approved commission joins a statement only after this delay, to cover returns.
• Minimum payout: below it, the balance is carried over to the next month.
• Company name, IBAN and BIC: required to generate the SEPA transfer file.

Tracking and attribution

Tracking links

Each affiliate has a code. Two kinds of links carry it:

• the tracking parameter, added to any address of the shop: ?aff=CODE. The parameter name can be changed in the settings, for example to ref;
• short links the affiliate creates in their area from the address of a product, a category or any page. They redirect to the chosen page and count clicks and orders per link.

On click, a signed cookie (dfaff_ref) records the affiliate. Its signature prevents a visitor from changing it. Search engine robots, automated browsers and the affiliate’s own clicks are not counted, and the same visitor is counted once per 30-minute window. No IP address is stored in clear.

Attribution order of an order

1. An affiliate’s personal discount code used in the order, even without a click.
2. The link or cookie: the cart is linked to the affiliate during the visit, which also covers payments confirmed later by the bank.
3. A customer previously referred by this affiliate, if the Returning customer commissions setting is above 0 days.

The attribution model decides what happens when a visitor clicks the links of two affiliates: last click (default), the last affiliate visited wins; first click, the first one keeps the sale until the cookie expires.

Protections

• An affiliate earns no commission on their own orders, recognised by customer account and by e-mail address.
• New customers only: only a customer’s first order earns a commission.
• Minimum order amount: products tax excluded after discounts, 0 for no minimum.

Commissions

Calculation

The base is the product amount tax excluded. With Deduct discounts, the order vouchers are removed from the base; a free shipping voucher does not change it. Shipping is never included. The amount is converted into the shop’s default currency.

The rate applied is, in this order: the affiliate’s specific commission if any, otherwise the program rate. For percentages, product rules then category rules replace the rate line by line. For a fixed amount, a single commission is created per order, and a single one when PrestaShop splits a cart into several orders for several carriers.

Category and product rules

The Commission rules tab sets a percentage for a category or a product, for example 3 % on electronics and 15 % on accessories. A product rule wins over a category rule. For categories, the module first looks at the product’s default category, then the best of its other categories. A rate of 0 excludes the products from commissions. Rules apply to percentage commissions only.

Life cycle

• When the order is placed, the commission is created as Pending.
• When the order reaches an approval status, it becomes Approved and the approval date starts the hold period.
• When the order moves to a cancellation status, it is Rejected.
• A partial credit slip reduces the commission in proportion to the product amount refunded.
• If the commission is already on a statement or paid, the module no longer changes it: it creates a negative adjustment deducted from the next statement, without hold period. A second cancellation status on the same order does not create another deduction.

Manual commissions

In the Commissions tab, Add a manual commission credits or debits an affiliate (negative amount for a deduction), with a note visible in their area. These lines follow the same statement cycle as order commissions.

Affiliates

Applications

The public program page presents your conditions (rate, cookie duration, minimum payout), three steps and an FAQ generated from your settings. The presentation text is edited in the settings, in each language. If you select a CMS page for the program terms, applicants must accept it.

Applicants must be logged in to a customer account. They say where they publish, describe their audience and, optionally, their company. By default each application waits for your approval and the notification e-mail receives a message. With Approve applications automatically, the account is active at once.

Affiliate sheet

The sheet starts with a summary (clicks, orders, pending, due and paid commissions) and the tracking link to copy, followed by three blocks:

• Identity and channel: name, e-mail, website, audience, status and internal note. Setting the status to Approved sends the “Your affiliate account is active” e-mail.
• Tracking and commission: affiliate code, specific commission, own cookie duration, personal discount code. If the code does not exist yet and you enter a discount percentage, the cart rule is created automatically, limited to one use per customer.
• Payment details: SEPA transfer or PayPal, account holder, IBAN, BIC, PayPal e-mail.

You can create an affiliate without a customer account: they receive statements by e-mail but have no online area. If a customer account uses the same e-mail address, it is linked automatically.

An affiliate who still has open commissions or an unpaid statement cannot be deleted: suspend them or settle the balance first.

What the affiliate sees

• My account: an “Affiliate area” tile, or “Become an affiliate” for a customer who is not one.
• Overview: link builder, figures strip (clicks, orders, conversion, pending, approved, paid), 30-day chart, conditions and recent links.
• My links: all short links with clicks, orders, copy and delete.
• Commissions: date, masked order reference, source, base, commission, status, filter by status and expected payout month. No customer data is shown.
• Statements: one statement per month, viewable and printable as PDF.
• Payment details: choice of transfer or PayPal, IBAN checked with its check digits and shown masked. A dot and a banner flag missing details.
• Product page: a “Your affiliate link” box, visible only to the logged-in affiliate, gives the product link and the rate earned on it.

Statements and payouts

Creating statements

A statement groups, for one affiliate and one month, the approved commissions created before the end of the month whose hold period is over, plus negative adjustments. If the total is below the minimum payout, nothing is created and the balance is carried over.

Two ways to create statements:

• Statements and payouts > Create the monthly statements: pick the month, preview the amounts per affiliate, then create the statements and send the e-mails.
• The cron URL, shown in the settings overview. Call it once a day: between the 1st and the 5th of the month it creates the statements of the previous month. Add &period=YYYY-MM to force a given month. It is protected by a token.

Paying affiliates

In the statements list, select the statements to pay and use the bulk action you need:

• Export SEPA transfer file (XML): pain.001.001.03 file to import into your bank, for affiliates paid by transfer. It requires EUR as the default currency and the company IBAN.
• Export PayPal Payouts file (CSV): for PayPal bulk payments, affiliates paid by PayPal.
• Export for accounting (CSV): all selected statements, semicolon separated.

Payment exports are refused, with a message naming the statement concerned, when a selected statement is already paid or an IBAN is missing or invalid: an incomplete file would leave an affiliate unpaid, and a paid statement could be paid twice.

Once the transfer is done, mark the statements as paid, in bulk or from a statement’s detail with the payment reference and date. The commissions concerned move to Paid.

E-mails

The module sends four e-mails, translated into 8 languages and sent in the recipient’s language, amounts included:

• New affiliate application, to the notification address.
• Your affiliate account is active, with the link to the affiliate area.
• New sale, with commission, base and rate, never the customer’s details. Can be turned off in the settings, and by each affiliate in their payment details.
• Statement available, with the amount and the link to the statement.

Templates live in the module’s mails/ folder and can be customised like any PrestaShop e-mail.

Back office

• Overview (settings page): active affiliates, applications to review, clicks, orders and sales over 30 days, pending, due and paid commissions, top affiliates.
• Order page: a panel shows the affiliate, the commission, its status and its source.
• CSV exports of the affiliate and commission lists, with raw amounts ready for a spreadsheet.

GDPR and account deletion

The module registers with the official PrestaShop GDPR module. A customer’s data export includes their affiliate profile and commissions. Erasure anonymises the affiliate (name, e-mail, IBAN, website and audience cleared, links and clicks deleted) while keeping commissions and statements for accounting.

When an employee deletes a customer account, the linked affiliate is kept without an online account and their payment details stay in place.

Troubleshooting

No click is counted

Test in a private browsing window, without being logged in with the affiliate’s account: their own clicks are ignored. Automated browsers are filtered as robots. If your shop uses a full-page cache, a page served from the cache does not run PHP and the ?aff= parameter is not seen: use short links, which always go through PrestaShop, or exclude the parameter from the cache.

A commission stays pending

Check that the current order status is ticked in Approve the commission on. If the status was changed by an employee whose profile lacks the View permission on the module (Advanced Parameters > Team > Permissions), PrestaShop did not run the module: set the order to that status again with an administrator account.

The link builder refuses an address

The builder only accepts addresses from your shop. Paste the full address as it appears in the browser, on the shop domain.

The SEPA export is refused

Read the message shown: it names the statement already paid or the affiliate whose IBAN is missing. Deselect it or complete their details. Also check that the company name and IBAN are filled in.

Compatibility

• PrestaShop 8.0 to 9.x, the same ZIP covers both branches.
• Multilingual and multi-currency, commissions calculated in the default currency.
• ModuleAdminController architecture, no Composer dependency.
• Module and e-mails translated into English, French, Spanish, German, Italian, Dutch, Polish and Portuguese.