# DataFirefly Loyalty — Shopware 6 Loyalty Program

> Installation, configuration and usage of DataFirefly Loyalty: points, tiers, voucher redemption and troubleshooting.

- Page: <https://www.datafirefly.com/en/documentation/dfloyalty-shopware/>
- Language: en
- Last updated: 2026-10-08
- Other languages: [fr](https://www.datafirefly.com/documentation/dfloyalty-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dfloyalty-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dfloyalty-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dfloyalty-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfloyalty-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfloyalty-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfloyalty-shopware/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Overview

DataFirefly Loyalty adds a complete loyalty program to Shopware 6: your customers earn points on every order, climb tiers with point multipliers and convert their points into vouchers based on Shopware's native promotions. The extension runs on Shopware 6.5, 6.6 and 6.7 with a single ZIP, with no compilation whatsoever.

## Installation

### From the administration

1. Go to **Extensions > My extensions**.
2. Click **Upload extension** and select the `DfLoyalty-1.0.0.zip` file.
3. Click **Install**, then activate the extension.

### From the command line

```
bin/console plugin:refresh
bin/console plugin:install --activate DfLoyalty
bin/console cache:clear
```

Installation creates two dedicated tables: `df_loyalty_account` (one row per customer) and `df_loyalty_transaction` (the ledger of all point operations).

No JavaScript build is needed: the extension ships no compiled administration module, which guarantees compatibility across the 6.5, 6.6 and 6.7 branches.

## Configuration

Open **Extensions > My extensions > DataFirefly Loyalty > Configure**. All settings are available per sales channel: you can enable the program on one shop only, or apply different rates per channel.

### Point awarding

- **Enable the program**: master switch. When disabled, the customer account page returns a 404 and no points are awarded.
- **Award trigger**: _Payment captured_ (transaction state `paid`, recommended) or _Order completed_ (order state `completed`).
- **Points per currency unit**: points earned per unit spent. Default: 1.
- **Calculation basis**: gross or net order amount.
- **Include shipping costs**: shipping is excluded from the calculation by default.

### Tiers

Three tiers are configurable, each with a name, a threshold and a multiplier. Thresholds apply to **lifetime earned points** (never decreased by a redemption), and the multiplier applies to all future earnings.

- **Tier 1** — default: Bronze, from 0 points, multiplier ×1.0
- **Tier 2** — default: Silver, from 500 points, multiplier ×1.25
- **Tier 3** — default: Gold, from 2,000 points, multiplier ×1.5

Example: a Silver customer (×1.25) placing a 100 gross-value order with a rate of 1 point per unit earns 125 points.

### Voucher redemption

- **Conversion rate**: points needed for 1 unit of voucher value. Default: 100 (100 points = 1.00).
- **Redemption minimum**: minimum points required to redeem. Default: 200.
- **Redemption step**: points convert in multiples of this value. Default: 100.
- **Voucher validity**: voucher lifetime in days. Default: 90.

## How it works for customers

A **Loyalty programme** entry appears in the customer account menu. The `/account/loyalty` page shows:

- the available points balance and total lifetime earned points;
- the current tier with a progress bar towards the next tier;
- the voucher redemption form;
- the history of the last 50 operations (earnings, redemptions, revocations).

When a customer redeems points, the extension creates a **native Shopware promotion**: a unique code such as `LOYAL-XXXXXXXX`, restricted to their account, single use, with a fixed cart discount. The code is applied in the cart like any promo code. All generated promotions can be found under **Marketing > Promotions**.

## Cancellations and refunds

When an order enters the _Cancelled_ state or its payment enters the _Refunded_ state, the points earned on that order are automatically revoked. The operation is traced in the customer's history under the label "Revoked". Revocation is idempotent: it can occur at most once per order.

In version 1.0, partial refunds are not prorated: it is the full payment entering the _Refunded_ state that triggers revocation of all points earned on the order.

## Security and data integrity

- The point debit is atomic at database level: two simultaneous redemptions cannot spend the same balance twice.
- Every operation is written to an append-only ledger, with order reference, type, signed points and the voucher code where applicable.
- Voucher creation and the ledger write run in the same SQL transaction: never a voucher without a debit, never a debit without a voucher.

## Troubleshooting

### The Loyalty programme link does not appear in the account

The extension injects its link through the `page_account_sidebar_link_orders` Twig block. If your custom theme removed or renamed this block, add the link manually in the account sidebar template, pointing to the `frontend.account.dfloyalty.page` route.

### Points are not being awarded

1. Check that the program is enabled for the relevant sales channel.
2. Check the configured trigger: with _Payment captured_, the transaction must reach the `paid` state; with _Order completed_, the order must reach `completed`.
3. Clear the cache after any configuration change: `bin/console cache:clear`.

### Uninstalling

During uninstallation, Shopware offers to keep the data. If you untick this option, the `df_loyalty_account` and `df_loyalty_transaction` tables are permanently removed — previously generated vouchers remain in place, as they are standard Shopware promotions.