Magento 2 + Returnless — retourenportaal implementeren

Magento 2 + Returnless — retourenportaal implementeren

Gemiddeld 25% van alle online bestellingen wordt teruggestuurd. In fashion loopt dat op naar 40%. Elke retour kost je gemiddeld €7 tot €15 aan verwerkingstijd, verzendkosten en klantenservice. Een geautomatiseerd retourenportaal zoals Returnless betaalt zichzelf terug — maar alleen als de koppeling met Magento 2 goed staat.

In dit artikel lees je hoe je Returnless technisch koppelt aan Magento 2: van orderdata ophalen tot carrier-integratie en voorraadmutaties. Met concrete code, eerlijke kanttekeningen en de business-impact die wij bij klanten zien.

Waarom Returnless boven een eigen retourformulier

De standaard aanpak is een PDF-formulier of een simpel contactformulier. Dat werkt, maar schaal je niet. Je klantenservice verwerkt elke retour handmatig: e-mail lezen, order opzoeken, label aanmaken, bevestiging sturen. Bij 100 retouren per maand ben je al snel 15 uur kwijt aan repetitieve handelingen.

Returnless automatiseert die flow volledig. De klant logt in met ordernummer en e-mailadres, kiest een retourreden, selecteert artikelen en krijgt direct een retourlabel. Jij ziet alles in één dashboard — inclusief redenen, waarde en status per artikel.

Een bijkomend voordeel: de klantervaring verbetert direct. Geen wachttijd op een handmatig label, geen onduidelijkheid over de status. Dat verlaagt ook het aantal "waar is mijn retourgeld"-tickets. Voor webshops met meer dan 50 retouren per maand is dat geen luxe, dat is een operationele noodzaak.

De technische architectuur van de koppeling

Returnless werkt via een REST API. Magento 2 levert orderdata, Returnless beheert de retourstroom en stuurt events terug naar Magento. De integratie bestaat uit drie lagen:

1. Orderdata push of pull — Returnless haalt orders op via de Magento REST API, of jij pusht orders naar Returnless bij plaatsing.
2. Webhook events — Returnless stuurt status-updates terug (retour aangemaakt, label geprint, pakket ontvangen, terugbetaling goedgekeurd).
3. Voorraadmutaties — na goedkeuring update je de voorraad in Magento automatisch via de API.

Optie A: Pull via Magento REST API

Returnless haalt orders op via de standaard Magento REST endpoint. Je hoeft zelf weinig te bouwen, maar de latency is hoger: orders zijn beschikbaar zodra Returnless ze ophaalt (doorgaans elk uur of op trigger).

Minimale configuratie in Returnless: je voert je Magento base URL en een API-token in. Dat token maak je aan via Systeem > Integraties in de Magento backend.

Optie B: Push via Magento observer

Voor real-time synchronisatie gebruik je een Magento observer op het sales_order_place_after-event. Zodra een order wordt geplaatst, stuur je de orderdata naar de Returnless API.

<?php
namespace CodingNl\ReturnlessConnect\Observer;

use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\HTTP\Client\Curl;
use Psr\Log\LoggerInterface;

class PushOrderToReturnless implements ObserverInterface
{
    private const API_ENDPOINT = 'https://returnless.com/api/v1/orders';

    public function __construct(
        private readonly Curl $curl,
        private readonly LoggerInterface $logger,
        private readonly \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig
    ) {}

    public function execute(Observer $observer): void
    {
        $order = $observer->getEvent()->getOrder();

        $payload = [
            'external_id'    => $order->getIncrementId(),
            'order_date'     => $order->getCreatedAt(),
            'customer_email' => $order->getCustomerEmail(),
            'customer_name'  => $order->getCustomerFirstname() . ' ' . $order->getCustomerLastname(),
            'items'          => $this->mapOrderItems($order->getAllVisibleItems()),
            'currency'       => $order->getOrderCurrencyCode(),
            'total'          => (float) $order->getGrandTotal(),
        ];

        $apiKey = $this->scopeConfig->getValue('returnless/api/key');

        $this->curl->addHeader('Authorization', 'Bearer ' . $apiKey);
        $this->curl->addHeader('Content-Type', 'application/json');
        $this->curl->post(self::API_ENDPOINT, json_encode($payload));

        if ($this->curl->getStatus() !== 201) {
            $this->logger->error('Returnless push failed for order ' . $order->getIncrementId());
        }
    }

    private function mapOrderItems(array $items): array
    {
        return array_map(fn($item) => [
            'sku'      => $item->getSku(),
            'name'     => $item->getName(),
            'quantity' => (int) $item->getQtyOrdered(),
            'price'    => (float) $item->getPrice(),
        ], $items);
    }
}

Registreer de observer in etc/events.xml:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="sales_order_place_after">
        <observer name="returnless_push_order"
                  instance="CodingNl\ReturnlessConnect\Observer\PushOrderToReturnless" />
    </event>
</config>

De API-sleutel sla je op in de Magento systeemconfiguratie — nooit hardcoded in de code.

Webhooks: Returnless praat terug met Magento

Zodra de klant een retour aanmaakt, stuurt Returnless een webhook naar jouw Magento-installatie. Registreer een custom REST endpoint of een controller URL.

Relevante webhook-events:

Het verwerken van webhooks doe je asynchroon. Gebruik een Magento queue (RabbitMQ of database queue) om de webhook-payload op te slaan en in de achtergrond te verwerken. Zo vermijd je timeouts bij piekbelasting.

Voorraadmutaties na ontvangst

Na return.approved wil je de retourhoeveelheid terug in de voorraad. Gebruik de CatalogInventory\Api\StockRegistryInterface:

public function updateStock(string $sku, int $returnedQty): void
{
    $stockItem = $this->stockRegistry->getStockItemBySku($sku);
    $newQty = $stockItem->getQty() + $returnedQty;

    $stockItem->setQty($newQty);
    $stockItem->setIsInStock($newQty > 0);

    $this->stockRegistry->updateStockItemBySku($sku, $stockItem);
}

Let op: gebruik je MSI (Multi Source Inventory) in Magento 2.3+, dan werk je met SourceItemsSaveInterface per source, niet met de legacy StockRegistry. In de praktijk zien wij dat veel shops nog de legacy inventory-stack gebruiken, ook op Magento 2.4. Controleer dit vóór implementatie.

Retourredenen analyseren: van data naar beslissing

Returnless registreert elke retourreden. Dat is waardevoller dan het lijkt. Wij zien bij klanten dat 60 tot 70% van de retourredenen in drie categorieën valt:

• Maatproblemen — product past niet of valt anders dan verwacht
• Kwaliteitsverwachting — foto's kloppen niet met het echte product
• Beschadigd ontvangen — verpakkings- of transportschade

Die data gebruik je direct in je productpagina's. Als 30% van de retouren op een specifiek artikel de reden "maatvoering klopt niet" geeft, voeg je een maattabel toe of pas je de productbeschrijving aan. Dat verlaagt het retourpercentage structureel. Geen campagne nodig, geen budgetverhoging.

Exporteer de Returnless-data maandelijks naar een spreadsheet of koppel de API aan een BI-tool. Dan zie je trends per categorie, seizoen en leverancier. Leverancier X levert structureel beschadigde producten? Dat zie je in de data lang voordat een account manager het signaleert.

Wij raden aan elke drie maanden een retouranalyse te doen met de inkoopverantwoordelijke én de content-editor samen. Die combinatie zorgt dat bevindingen ook daadwerkelijk vertaald worden naar productverbeteringen.

Carrier-integratie: labels automatisch aanmaken

Returnless werkt out-of-the-box met de grote carriers: PostNL, DHL, DPD en UPS. Je configureert per retourtype welke carrier het label aanmaakt. De klant krijgt een QR-code of PDF die hij bij een afhaalpunt inlevert.

Voordeel: je stuurt geen losse retourlabels meer mee in het pakket. Dat scheelt direct €1 tot €3 per zending aan label- en handlingskosten. Bij 200 verzendingen per week is dat al €800 tot €2.400 per maand besparing op labels alleen.

Sommige carriers werken via de Returnless-contracten, andere via je eigen carrier-account. Welke optie goedkoper uitvalt, hangt af van je volume. Ga bij de onboarding altijd na of je eigen carrier-tarieven gunstiger zijn.

Wanneer Returnless NIET de juiste keuze is

Eerlijk zijn: Returnless is niet voor elke webshop de beste optie.

• Minder dan 20 retouren per maand — de maandelijkse abonnementskosten wegen niet op tegen de tijdsbesparing. Een eenvoudig formulier met handmatige verwerking is dan efficiënter.
• Sterk afwijkende retourflows — verkoopt je B2B-producten met RMA-processen, maatwerk contractvoorwaarden of leaseconstructies? Dan biedt Returnless te weinig flexibiliteit. Bouw dan een eigen retourmodule in Magento of Laravel.
• Harde ERP-afhankelijkheid — als elke retour direct en synchroon in een koppig legacy ERP moet landen, is de webhook-aanpak van Returnless mogelijk te asynchroon. Bespreek dit met je ERP-leverancier voor je begint.

Business-impact: wat levert het op?

Wij zien bij klanten die overstappen op een geautomatiseerd retourenportaal de volgende resultaten — niet als garantie, maar als reëele range:

Die laatste rij is de meest waardevolle. Een lager retourpercentage is geen bijeffect, dat is een direct gevolg van het analyseren van retourredenen en het aanpassen van productcontent. Dat vereist discipline: je moet de data ook écht gebruiken.

Stel je verkoopt 500 orders per maand met een retourpercentage van 20%. Dat zijn 100 retouren. Als je door betere productcontent dat percentage naar 15% drukt, bespaar je 25 retouren per maand. Bij €10 gemiddelde verwerkingskost is dat €250 per maand aan directe kostenbesparing — structureel, zonder extra marketing-euro's.

Implementatietijd en kosten: wat moet je rekenen op

Een standaard Returnless-koppeling met Magento 2 bouwen kost bij ons doorgaans 16 tot 24 ontwikkelingsuren. Dat omvat:

• Custom module met observer en webhook-controller
• Configuratiescherm in de Magento backend
• Queue-implementatie voor asynchrone verwerking
• Testen op staging en productie

Tel daar 4 tot 8 uur extra bij op als je MSI gebruikt, meerdere stores hebt of een extra ERP-koppeling nodig is voor de voorraadmutaties.

Returnless zelf rekent een maandelijks abonnement. De exacte tarieven hangen af van retourvolume en gewenste functies — vraag dit op bij Returnless zelf, want de prijzen wijzigen regelmatig. De ontwikkelkosten zijn eenmalig; de besparing op klantenservice-uren is doorlopend.

Stel jezelf de ROI-vraag concreet: hoeveel uur besteedt je team nu per maand aan retourverwerking? Vermenigvuldig dat met een uurtarief. Als dat boven de €300 per maand uitkomt én je retourvolume rechtvaardigt de tool, is de business case snel gemaakt.

Voor shops op Magento met een groeiend retourvolume is dit een van de snelste manieren om operationele kosten terug te dringen zonder het assortiment of de prijsstrategie aan te raken.

Veelgestelde vragen

Ja, maar de voorraadkoppeling vereist extra aandacht. Gebruik SourceItemsSaveInterface in plaats van de legacy StockRegistry. Welke source je bijwerkt na een retour hangt af van je magazijnstructuur. Bij meerdere sources moet je in de webhook-handler bepalen naar welk magazijn het artikel terugkeert.

Returnless heeft native integraties met de meeste gangbare helpdesk-tools. Retour-events kunnen direct tickets aanmaken of bijwerken. Zo werkt je klantenservice-team vanuit één interface, zonder te wisselen tussen systemen.

Doorgaans staat het label binnen enkele seconden klaar via de carrier-API. Alleen bij carriers die een batchverwerking gebruiken kan dit oplopen tot een kwartier. In de praktijk merken klanten hier niets van — zij ontvangen de bevestiging direct per e-mail.

Returnless is een Nederlands bedrijf en verwerkt data binnen de EU. Er is een verwerkersovereenkomst beschikbaar. Controleer deze voor je live gaat en voeg Returnless toe aan je register van verwerkingsactiviteiten.

Wil je weten of een Returnless-koppeling voor jouw Magento 2-shop de juiste stap is? Neem contact op — wij kijken mee naar je retourvolume, huidige stack en de snelste route naar minder handmatig werk.