Gift cards

Das Geschenkkarten-Modul ermöglicht Ihnen, Karten als WooCommerce-Produkte zu verkaufen. Der Kunde kauft eine Karte, erhält einen Code und bezahlt damit bei zukünftigen Bestellungen.

Funktionsweise

1. Der Administrator erstellt ein Produkt vom Typ “Geschenkkarte”
2. Der Kunde kauft eine Geschenkkarte im Shop
3. Nach Bezahlung der Bestellung generiert das Plugin einen eindeutigen Kartencode
4. Der Code wird per E-Mail an den Kunden (oder an den Beschenkten) gesendet
5. Der Beschenkte gibt den Code im Warenkorb ein und erhält einen Rabatt in Höhe des Kartenwerts
6. Das Kartenguthaben verringert sich um den verwendeten Betrag

Konfiguration

Seit Polski PRO 1.22.0 Geschenkkarten haben eine eigene Zeile unter Polski > Module (Modulschlüssel gift_cards). Dort schalten Sie das Modul ein und setzen in derselben Zeile die shopweiten Werte; das Speichern schreibt sie in die Option polski_gift_cards. Das Modul wird ausgeschaltet ausgeliefert.

Die Zeile zeigt nicht jeden Schlüssel, den das Modul liest. Was dort fehlt, lässt sich weiterhin direkt an der Option setzen, etwa mit WP-CLI:

wp option patch update polski_gift_cards expiry_days 180

Werte pro Produkt (ob ein Produkt überhaupt eine Geschenkkarte ist, seine Beträge und die Grenzen des freien Betrags) liegen auf dem Tab Polski Pro des Produkteditors, siehe Per-product settings.

Einstellungen, die das Modul liest

Schlüssel	Standard	Beschreibung
show_on_single	true	Geschenkkartenfelder auf der Produktseite anzeigen
allow_custom_amount	true	Käufer einen eigenen Betrag eingeben lassen
min_amount / max_amount	20 / 1000	Grenzen für einen freien Betrag
default_amounts	50,100,200	Auf der Produktseite vorgeschlagene Beträge
code_prefix	SP	Präfix des erzeugten Codes
expiry_days	365	Gültigkeitstage einer Karte
show_in_account / account_label	true / Geschenkkarten	Bereich in Mein Konto mit den Kartenguthaben
email_subject / email_heading	siehe Code	Wortlaut der Geschenkkarten-E-Mail
date_format	d.m.Y	Datumsformat in der Kundenansicht

Auch jede Beschriftung und jeder Hinweis hat einen eigenen Schlüssel (recipient_name_label, invalid_code_text, applied_code_text und so weiter). Die Standardwerte stehen in Polski\Pro\Service\GiftCardService.

Erstellen eines Geschenkkarten-Produkts

1. Gehen Sie zu Produkte > Erstellen
2. Wählen Sie den Produkttyp: Geschenkkarte
3. Legen Sie den Preis fest (Nennwert der Karte)
4. Optional: Aktivieren Sie “Freier Betrag” - der Kunde gibt den Kartenwert selbst ein
5. Optional: Legen Sie einen Mindest- und Höchstbetrag für freie Beträge fest
6. Veröffentlichen Sie das Produkt

Bei freien Beträgen sieht der Kunde anstelle eines festen Preises ein Feld zur Eingabe des Kartenwerts.

Code-Generierung

Geschenkkarten-Codes werden automatisch nach Bezahlung der Bestellung generiert. Algorithmus:

• alphanumerische Zeichen (A-Z, 0-9)
• Ausschluss mehrdeutiger Zeichen (0, O, I, L, 1)
• Prüfung der Eindeutigkeit in der Datenbank
• Formatierung mit Trennzeichen (z. B. ABCD-EFGH-JKMN-PQRS)

Jeder Code ist im gesamten Shop eindeutig. Das Plugin prüft die Eindeutigkeit vor dem Speichern und generiert bei einer Kollision einen neuen Code.

Einlösung im Warenkorb

Code-Feld

Auf der Warenkorb-Seite (und optional auf der Kassen-Seite) wird ein Feld zur Eingabe des Geschenkkarten-Codes angezeigt:

[Wpisz kod karty podarunkowej] [Zastosuj]

Nach Eingabe eines gültigen Codes:

• wird das Kartenguthaben angezeigt
• wird der Rabattbetrag von der Bestellsumme abgezogen
• wenn das Kartenguthaben geringer ist als der Bestellwert - wird der Restbetrag mit anderen Methoden bezahlt
• wenn das Kartenguthaben höher ist - verbleibt der Restbetrag auf der Karte

Code-Validierung

Das Plugin validiert den Kartencode vor der Anwendung:

• prüft, ob der Code in der Datenbank vorhanden ist
• prüft, ob die Karte nicht abgelaufen ist
• prüft, ob das Guthaben größer als null ist
• prüft, ob die Karte nicht gesperrt wurde

Die Fehlermeldung informiert den Kunden über den Grund der Ablehnung des Codes.

Sitzungsverfolgung

Der angewendete Kartencode wird in der WooCommerce-Sitzung des Kunden gespeichert. Das bedeutet:

• der Code wird auch nach dem Aktualisieren der Seite gespeichert
• der Code wird nach dem Aufgeben einer Bestellung oder dem Abmelden entfernt
• der Kunde kann den angewendeten Code manuell entfernen

Guthabenverfolgung

Jede Geschenkkarte hat ein Guthaben, das sich mit jeder Verwendung verringert. Der Transaktionsverlauf der Karte enthält:

Feld	Beschreibung
Datum	Datum der Transaktion
Typ	Aufladung / Verwendung / Rückerstattung
Betrag	Betrag der Operation
Bestellung	Bestell-ID (bei Verwendung und Rückerstattung)
Guthaben nach Operation	Aktuelles Guthaben nach der Transaktion

Admin-Bereich

Im Bereich WooCommerce > Geschenkkarten kann der Administrator:

• die Liste aller Karten mit Guthaben durchsuchen
• den Transaktionsverlauf einer Karte prüfen
• eine Karte manuell aufladen
• eine Karte sperren
• die Kartenliste exportieren (CSV)

Bereich Mein Konto

Das Modul fügt dem Bereich Mein Konto des Kunden einen Endpunkt /polski-gift-cards hinzu. Der Endpunkt ist verfügbar unter:

/moje-konto/polski-gift-cards/

Im Bereich kann der Kunde einsehen:

• Liste der eigenen Geschenkkarten
• aktuelles Guthaben jeder Karte
• Nutzungsverlauf
• Kartencode (mit Kopieroption)
• Ablaufdatum (falls festgelegt)

Hooks

polski_pro/gift_card/validate

Filtert das Ergebnis der Validierung des Geschenkkarten-Codes im Warenkorb.

/**
 * @param bool   $is_valid  Czy kod jest prawidłowy
 * @param string $code      Kod karty podarunkowej
 * @param float  $cart_total Suma koszyka
 */
apply_filters('polski_pro/gift_card/validate', bool $is_valid, string $code, float $cart_total): bool;

Beispiel:

add_filter('polski_pro/gift_card/validate', function (bool $is_valid, string $code, float $cart_total): bool {
    // Blokowanie kart podarunkowych dla zamówień poniżej 50 zł
    if ($cart_total < 50.00) {
        wc_add_notice('Karty podarunkowe można wykorzystać przy zamówieniach od 50 zł.', 'error');
        return false;
    }
    return $is_valid;
}, 10, 3);

polski_pro/gift_card/applied

Aktion, die nach der Anwendung einer Geschenkkarte im Warenkorb ausgelöst wird.

/**
 * @param string $code    Kod karty
 * @param float  $amount  Kwota do odliczenia
 * @param float  $balance Pozostałe saldo
 */
do_action('polski_pro/gift_card/applied', string $code, float $amount, float $balance);

Beispiel:

add_action('polski_pro/gift_card/applied', function (string $code, float $amount, float $balance): void {
    // Logowanie użycia karty
    wc_get_logger()->info(
        "Karta {$code}: odliczono {$amount} zł, saldo: {$balance} zł",
        ['source' => 'polski-pro-gift-cards']
    );
}, 10, 3);

polski_pro/gift_card/order_created

Aktion, die nach der Erstellung einer Bestellung unter Verwendung einer Geschenkkarte ausgelöst wird.

/**
 * @param int    $order_id ID zamówienia
 * @param string $code     Kod karty
 * @param float  $amount   Kwota odliczona z karty
 */
do_action('polski_pro/gift_card/order_created', int $order_id, string $code, float $amount);

Beispiel:

add_action('polski_pro/gift_card/order_created', function (int $order_id, string $code, float $amount): void {
    $order = wc_get_order($order_id);
    $order->add_order_note(
        sprintf('Użyto kartę podarunkową %s na kwotę %.2f zł', $code, $amount)
    );
}, 10, 3);

polski_pro/gift_card/calculate_totals

Filtert den von der Geschenkkarte abzuziehenden Betrag beim Neuberechnen der Warenkorbsummen.

/**
 * @param float  $discount   Kwota rabatu z karty
 * @param string $code       Kod karty
 * @param float  $cart_total Suma koszyka przed rabatem
 */
apply_filters('polski_pro/gift_card/calculate_totals', float $discount, string $code, float $cart_total): float;

E-Mail mit Code

Nachdem eine Bestellung mit einer Geschenkkarte bezahlt wurde, sendet das Plugin eine E-Mail mit dem Code. Die E-Mail enthält:

• formatierten Kartencode
• Nennwert
• Ablaufdatum (falls zutreffend)
• Nutzungshinweise

Die E-Mail-Vorlage kann unter WooCommerce > Einstellungen > E-Mails > Geschenkkarte angepasst werden.

E-Mail für den Beschenkten

Beim Kauf einer Karte kann der Kunde die E-Mail-Adresse des Beschenkten angeben. In diesem Fall:

• wird der Code an die Adresse des Beschenkten gesendet
• erhält der Käufer eine Kaufbestätigung (ohne den Code)
• optional: der Käufer kann eine Nachricht für den Beschenkten hinzufügen

Häufige Probleme

Code wird im Warenkorb nicht akzeptiert

1. Prüfen Sie, ob der Code korrekt eingegeben wurde (keine Leerzeichen am Anfang/Ende)
2. Überprüfen Sie, ob die Karte nicht abgelaufen ist
3. Prüfen Sie das Kartenguthaben im Admin-Bereich
4. Stellen Sie sicher, dass die Karte nicht gesperrt ist

Kunde hat den Code nicht per E-Mail erhalten

1. Prüfen Sie, ob die Bestellung bezahlt ist (Status “In Bearbeitung” oder “Abgeschlossen”)
2. Überprüfen Sie die WooCommerce-E-Mail-Konfiguration
3. Prüfen Sie die E-Mail-Protokolle auf Versandfehler

Guthaben verringert sich nach einer Bestellung nicht

1. Prüfen Sie, ob die Bestellung erfolgreich aufgegeben wurde (nicht storniert)
2. Überprüfen Sie den Transaktionsverlauf der Karte im Admin-Bereich
3. Prüfen Sie die Protokolle auf PHP-Fehler

Verwandte Ressourcen

• PRO-Übersicht
• Ein Problem melden

Diese Seite dient ausschließlich Informationszwecken und stellt keine Rechtsberatung dar. Konsultieren Sie vor der Umsetzung einen Anwalt. Polski for WooCommerce ist Open-Source-Software (GPLv2), die ohne Gewährleistung bereitgestellt wird.