PHPackages                             return-guard/return-guard - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. return-guard/return-guard

ActiveShopware-platform-plugin[Utility & Helpers](/categories/utility)

return-guard/return-guard
=========================

return-guard/return-guard

00

Since Apr 25Compare

[ Source](https://github.com/medinaahmeti/ReturnGuard)[ Packagist](https://packagist.org/packages/return-guard/return-guard)[ RSS](/packages/return-guard-return-guard/feed)WikiDiscussions Synced 3w ago

READMEChangelogDependenciesVersions (1)Used By (0)

ReturnGuard
===========

[](#returnguard)

ReturnGuard is a Shopware 6.7 plugin for detecting products, customers, and categories with a high risk of returns or cancellations.

What it does
------------

[](#what-it-does)

ReturnGuard analyzes order history and calculates risk scores for:

- customers
- products
- categories

It stores:

- risk snapshots in `return_guard_risk_snapshot`
- customer flags in `return_guard_customer_flag`
- product flags in `return_guard_product_flag`
- category flags in `return_guard_category_flag`

It also provides a Shopware Administration module under **Marketing > ReturnGuard** with:

- Dashboard
- Customers
- Products
- Categories

---

Main features
-------------

[](#main-features)

- order-history based scoring
- customer, product, and category risk detection
- configurable thresholds and weights
- scheduled scoring via Shopware scheduled tasks
- DAL entities for snapshots and flags
- Administration pages with repository-based listings
- dashboard API for overview and high-risk results
- snapshot cleanup and latest snapshot tracking

---

Current architecture
--------------------

[](#current-architecture)

### Core services

[](#core-services)

- `ReturnGuard\Config\ReturnGuardConfigService`
- `ReturnGuard\Service\OrderPatternAnalyzer`
- `ReturnGuard\Service\RiskScoringService`
- `ReturnGuard\Service\ReturnGuardScoringRunner`

### Shared services

[](#shared-services)

- `ReturnGuard\Service\Shared\ReturnGuardSnapshotCleanupService`
- `ReturnGuard\Service\Shared\ReturnGuardDashboardReader`

### Customer domain

[](#customer-domain)

- `ReturnGuard\Service\Customer\CustomerScoringRunner`
- `ReturnGuard\Service\Customer\CustomerSnapshotWriter`
- `ReturnGuard\Service\Customer\CustomerFlagReader`

### Product domain

[](#product-domain)

- `ReturnGuard\Service\Product\ProductScoringRunner`
- `ReturnGuard\Service\Product\ProductSnapshotWriter`
- `ReturnGuard\Service\Product\ProductFlagReader`

### Category domain

[](#category-domain)

- `ReturnGuard\Service\Category\CategoryScoringRunner`
- `ReturnGuard\Service\Category\CategorySnapshotWriter`
- `ReturnGuard\Service\Category\CategoryFlagReader`

### Scheduled task

[](#scheduled-task)

- `ReturnGuard\ScheduledTask\ReturnGuardScoringTask`
- `ReturnGuard\ScheduledTask\ReturnGuardScoringTaskHandler`

### Admin controller

[](#admin-controller)

- `ReturnGuard\Controller\Admin\ReturnGuardDashboardController`

---

Database tables
---------------

[](#database-tables)

### `return_guard_risk_snapshot`

[](#return_guard_risk_snapshot)

Stores scored snapshots for customer, product, and category runs.

Important fields:

- `score`
- `risk_level`
- `snapshot_type`
- `is_latest`
- `signals`

### `return_guard_customer_flag`

[](#return_guard_customer_flag)

Stores customer-level flags.

### `return_guard_product_flag`

[](#return_guard_product_flag)

Stores product-level flags.

### `return_guard_category_flag`

[](#return_guard_category_flag)

Stores category-level flags.

---

DAL entities
------------

[](#dal-entities)

Implemented:

- `RiskSnapshotDefinition`
- `RiskSnapshotEntity`
- `RiskSnapshotCollection`
- `CustomerFlagDefinition`
- `CustomerFlagEntity`
- `CustomerFlagCollection`
- `ProductFlagDefinition`
- `ProductFlagEntity`
- `ProductFlagCollection`
- `CategoryFlagDefinition`
- `CategoryFlagEntity`
- `CategoryFlagCollection`

Repositories used:

- `return_guard_risk_snapshot.repository`
- `return_guard_customer_flag.repository`
- `return_guard_product_flag.repository`
- `return_guard_category_flag.repository`

---

Scoring flow
------------

[](#scoring-flow)

### Global flow

[](#global-flow)

1. scheduled task starts scoring
2. old snapshots are cleaned up
3. customer scoring runs
4. product scoring runs
5. category scoring runs

### Customer flow

[](#customer-flow)

1. load customer order history
2. analyze customer behavior
3. calculate score
4. write snapshot
5. upsert flags

### Product flow

[](#product-flow)

1. load product order history
2. calculate product signals
3. calculate score
4. write snapshot
5. upsert flags

### Category flow

[](#category-flow)

1. load category order history
2. calculate category signals
3. calculate score
4. write snapshot
5. upsert flags

---

Snapshot lifecycle
------------------

[](#snapshot-lifecycle)

ReturnGuard keeps snapshot history and tracks the current snapshot with `is_latest`.

Behavior:

- previous latest snapshot for the same entity/type is set to `false`
- new snapshot is inserted with `is_latest = true`

This makes it easier to query current risk state while keeping history.

---

Configuration
-------------

[](#configuration)

### General

[](#general)

- `enableScoring`
- `highRiskThreshold`
- `mediumRiskThreshold`
- `minimumOrdersForPatternAnalysis`
- `dashboardTopLimit`
- `customerReturnRateFlagThreshold`
- `customerCancelRateFlagThreshold`
- `productReturnRateFlagThreshold`
- `productCancelRateFlagThreshold`
- `categoryReturnRateFlagThreshold`
- `categoryCancelRateFlagThreshold`
- `multipleSizesFrequencyThreshold`
- `newCustomerOrderThreshold`
- `snapshotRetentionDays`

### Score weights

[](#score-weights)

- `customerReturnRateWeight`
- `customerCancelRateWeight`
- `productReturnRateWeight`
- `productCancelRateWeight`
- `categoryReturnRateWeight`
- `categoryCancelRateWeight`
- `highDiscountOrderWeight`
- `multipleSizesSameOrderWeight`
- `newCustomerWeight`

### Important defaults

[](#important-defaults)

- `highRiskThreshold`: `70`
- `mediumRiskThreshold`: `40`
- `dashboardTopLimit`: `25`
- `snapshotRetentionDays`: `30`

---

Dashboard behavior
------------------

[](#dashboard-behavior)

Endpoint:

- `GET /api/_action/return-guard/dashboard`

The dashboard:

- loads overview data from the controller API
- uses `highRiskThreshold` from plugin config
- uses `dashboardTopLimit` from plugin config
- only shows high-risk customer/product/category rows in the dashboard tables

This keeps the KPI cards and dashboard tables aligned.

---

Administration module
---------------------

[](#administration-module)

Location:

- **Marketing > ReturnGuard**

Pages:

- Dashboard
- Customers
- Products
- Categories

### Data loading strategy

[](#data-loading-strategy)

- **Dashboard** uses the custom backend API endpoint
- **Customers / Products / Categories** use Shopware `repositoryFactory` directly

This follows the Shopware admin flow:

- custom API for aggregated overview data
- DAL repositories for entity-based listings

---

Shopware commands
-----------------

[](#shopware-commands)

### Scheduled tasks

[](#scheduled-tasks)

```
bin/console scheduled-task:register
bin/console scheduled-task:list
bin/console scheduled-task:run-single return_guard.scoring
bin/console scheduled-task:run
bin/console messenger:consume
```

### Plugin refresh

[](#plugin-refresh)

```
composer dump-autoload
bin/console plugin:refresh
bin/console cache:clear
bin/console messenger:consume
```

### Migrations

[](#migrations)

```
bin/console database:migrate ReturnGuard --all
Administration build
composer build:js:admin
bin/console messenger:consume
```

###  Health Score

9

—

LowBetter than 0% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/54688?v=4)[medina](/maintainers/medina)[@medina](https://github.com/medina)

### Embed Badge

![Health badge](/badges/return-guard-return-guard/health.svg)

```
[![Health](https://phpackages.com/badges/return-guard-return-guard/health.svg)](https://phpackages.com/packages/return-guard-return-guard)
```

###  Alternatives

[benjaminhirsch/nova-slug-field

A Laravel Nova field to generate a slugs.

1401.1M11](/packages/benjaminhirsch-nova-slug-field)[sbine/route-viewer

A Laravel Nova tool to view your registered routes.

57249.9k](/packages/sbine-route-viewer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)