Gift cards

The gift cards module lets you sell cards as WooCommerce products. The customer buys a card, receives a code and pays with it on future orders.

How it works

1. The administrator marks an ordinary product as a gift card on the Polski Pro tab of the product editor
2. The customer purchases a gift card in the store
3. After the order is paid, the plugin generates a unique card code
4. The code is sent to the customer (or the recipient) via email
5. The recipient enters the code in the cart and receives a discount equal to the card value
6. The card balance decreases by the amount used

Configuration

Since Polski PRO 1.22.0 gift cards have their own row on Polski > Modules (module key gift_cards). Switch the module on there, and set the store-wide values on the same row; saving writes them into the polski_gift_cards option. The module ships off.

The row does not expose every key the module reads. Anything missing from it can still be set on the option directly, for example with WP-CLI:

wp option patch update polski_gift_cards expiry_days 180

Per-product values (whether a product is a gift card at all, its preset amounts and custom-amount bounds) are on the Polski Pro tab of the product editor, see Per-product settings.

Settings the module reads

Key	Default	Description
show_on_single	true	Show the gift card fields on the product page
allow_custom_amount	true	Let the buyer enter their own amount
min_amount / max_amount	20 / 1000	Bounds for a custom amount
default_amounts	50,100,200	Preset amounts offered on the product page
code_prefix	SP	Prefix of the generated code
expiry_days	365	Days a card stays valid
show_in_account / account_label	true / Gift cards	My Account section listing card balances
email_subject / email_heading	see below	Wording of the gift card email
date_format	d.m.Y	Date format in customer-facing output

Every label and notice has its own key as well (recipient_name_label, invalid_code_text, applied_code_text and so on). The defaults live in Polski\Pro\Service\GiftCardService.

Creating a gift card product

There is no “Gift card” product type. A gift card is an ordinary product with the gift-card meta set on it, and since Polski PRO 1.26.0 the Polski Pro tab in the product data box writes that meta:

1. Go to Products > Add New and build an ordinary product.
2. Set the price (face value of the card).
3. Open the Polski Pro tab in the Product data box and tick Sell as a gift card. This writes _polski_gift_card_enabled, which is the key the module gates on.
4. Optionally set the preset amounts, allow a custom amount, and the bounds for a custom amount.
5. Publish the product.

See Per-product settings for every field on that tab, the meta key behind it, and how the custom-amount bounds fall back to the global ones.

For custom amounts, the customer sees a field to enter the card value instead of a fixed price.

Code generation

Gift card codes are generated automatically after the order is paid. Algorithm:

• alphanumeric characters (A-Z, 0-9)
• exclusion of ambiguous characters (0, O, I, L, 1)
• uniqueness validation in the database
• formatting with separators (e.g. ABCD-EFGH-JKMN-PQRS)

Each code is unique across the entire store. The plugin verifies uniqueness before saving and generates a new code in case of a collision.

Cart redemption

Code field

On the cart page (and optionally on the checkout page), a field is displayed for entering the gift card code:

[Wpisz kod karty podarunkowej] [Zastosuj]

After entering a valid code:

• the card balance is displayed
• the discount amount is subtracted from the order total
• if the card balance is less than the order value - the remainder is paid using other methods
• if the card balance is greater - the remaining amount stays on the card

Code validation

The plugin validates the card code before applying it:

• checks if the code exists in the database
• checks if the card has not expired
• checks if the balance is greater than zero
• checks if the card has not been blocked

The error message informs the customer about the reason for code rejection.

Session tracking

The applied card code is stored in the customer’s WooCommerce session. This means that:

• the code is remembered even after refreshing the page
• the code is removed after placing an order or logging out
• the customer can manually remove the applied code

Balance tracking

Each gift card has a balance that decreases with each use. The card transaction history contains:

Field	Description
Date	Transaction date
Type	Top-up / Usage / Refund
Amount	Operation amount
Order	Order ID (for usage and refund)
Balance after operation	Current balance after the transaction

Admin panel

In the WooCommerce > Gift cards panel, the administrator can:

• browse the list of all cards with balances
• check a card’s transaction history
• manually top up a card
• block a card
• export the card list (CSV)

My Account panel

The module adds a /polski-gift-cards endpoint to the customer’s My Account panel. The endpoint is available at:

/moje-konto/polski-gift-cards/

In the panel, the customer can see:

• list of owned gift cards
• current balance of each card
• usage history
• card code (with copy option)
• expiration date (if set)

Hooks

polski_pro/gift_card/validate

Filters the gift card code validation result in the cart.

/**
 * @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;

Example:

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

Action fired after a gift card is applied in the cart.

/**
 * @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);

Example:

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

Action fired after an order is created using a gift card.

/**
 * @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);

Example:

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

Filters the amount to deduct from the gift card when recalculating cart totals.

/**
 * @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;

Email with code

After an order containing a gift card is paid, the plugin sends an email with the code. The email includes:

• formatted card code
• face value
• expiration date (if applicable)
• usage instructions

The email template can be customized in WooCommerce > Settings > Emails > Gift card.

Email for the recipient

When purchasing a card, the customer can provide the recipient’s email address. In that case:

• the code is sent to the recipient’s address
• the buyer receives a purchase confirmation (without the code)
• optionally: the buyer can add a message for the recipient

Common issues

Code not accepted in the cart

1. Check if the code is entered correctly (no leading/trailing spaces)
2. Verify that the card has not expired
3. Check the card balance in the admin panel
4. Make sure the card is not blocked

Customer did not receive the code via email

1. Check if the order is paid (status “Processing” or “Completed”)
2. Verify the WooCommerce email configuration
3. Check email logs for sending errors

Balance not decreasing after an order

1. Check if the order was successfully placed (not cancelled)
2. Verify the card transaction history in the admin panel
3. Check logs for PHP errors

Related resources

• PRO overview
• Report an issue

This page is for informational purposes only and does not constitute legal advice. Consult a lawyer before implementation. Polski for WooCommerce is open source software (GPLv2) provided without warranty.