Developer guide

Extend Wallet Ready Gift Cards for WooCommerce and Pro · Hooks, APIs, database

1. Architecture overview

• Free plugin (wallet-ready-gift-cards-for-woocommerce) — required base: product type, cart, orders, PDF, email, redeem, Blocks Store API, security, ePasscard integration.
• Pro plugin (wallet-ready-gift-cards-for-woocommerce-pro) — optional: license gate, checkout edit, AI, REST, bulk import, etc. Self-disables if free is inactive. Runtime Pro modules load only when wallregi_pro_license_is_active() is true (wallregi_pro_bootstrap() in Pro main file).

Loader: includes/initialize-giftcard.php. Bootstrap: wallet-ready-gift-cards-for-woocommerce.php.

2. Important files and folders

3. Database tables

Created on activation via wallregi_create_database_tables() in includes/database-functions.php.

4. Options and product meta

4.1 Options

• wallregi_settings — General, form, PDF styling, fraud; Pro keys when licensed
• wallregi_email_settings — Email templates
• wallregi_pro_license — Pro license payload (signed)
• wallregi_pro_ai_settings — Pro AI provider, credits, messages
• wallregi_pro_expiry_reminder_settings — Pro expiry emails

4.2 Product meta (wxgiftcard)

• _wallregi_checkout_receiver_address — '', billing, or shipping
• _wallregi_enable_email_schedule — yes / no
• Price rows, expiry fields — see backend/backend.php save handler
• Pro: _wallregi_pro_product_greeting_presets_raw, etc.

4.3 Cart line

Cart items store giftcard_data array (recipient fields, price, image URL, checkout_receiver_source, etc.).

Line totals: wallregi_apply_giftcard_prices_to_cart() (in frontend/frontend.php) sets each gift card product’s price from giftcard_data['giftcard_price'] on woocommerce_before_calculate_totals and after cart-edit saves. Required because direct cart_contents edits do not always pass through woocommerce_cart_contents_changed.

5. Pro licensing and capability gates

• wallregi_pro_license_is_active() — strict check (Pro plugin).
• wallregi_pro_is_licensed() — same, callable from free plugin (includes/wallregi-pro-capabilities.php).
• wallregi_checkout_giftcard_edit_is_enabled( $settings ) — applies filter wallregi_is_checkout_edit_enabled with default false; Pro sets true when licensed and giftcard_edit_in_checkout === 'yes'.
• wallregi_strip_pro_only_settings() — clears Pro-only keys on save when not licensed.
• Admin: admin.php?page=wx-gift-cards-pro-license · class WALLREGI_Pro_License.

6. Programmatic gift card creation

$id = wallregi_insert_manual_giftcard( array(
    'giftcard_number'     => '', // empty = auto-generate
    'auto_generate'       => true,
    'initial_amount'      => 100,
    'current_amount'      => 100,
    'expiry_period'       => '+1 year',
    'preferred_date_time' => '', // normalized via wallregi_normalize_giftcard_preferred_datetime()
    'receipent_name'      => 'Jane Doe',
    'receipent_email'     => 'jane@example.com',
    'sender_name'         => 'Store',
    'message'             => 'Enjoy!',
    'order_id'            => 0,
    'item_id'             => 0,
    'product_id'          => 123,
) );

if ( is_wp_error( $id ) ) {
    // handle error
}

Pro bulk import and admin manual create both use this function. Filter: wallregi_manual_giftcard_code_format_valid.

7. Hooks and filters (free plugin)

Prefer these over editing core files. Full list also in docs/EXTENSIONS-ROADMAP.md.

7.1 Cart, checkout, edit

7.2 Redeem / session

7.3 Email, PDF, wallet

• wallregi_send_giftcard_email — action to send (args: code, context array)
• wallregi_epass_pass_issued / wallregi_epass_pass_updated — wallet pass lifecycle
• wallregi_blocks_settings — filter JS config for Blocks integration
• wallregi_admin_dashboard_tabs / wallregi_sidebar_menu_items — admin UI extension

8. WooCommerce Store API (Blocks)

Class: WALLREGI_Blocks_Integration in frontend/blocks/class-wallregi-blocks-integration.php.

• Namespace: wallet-ready-gift-cards-for-woocommerce
• Cart extension: appliedGiftcards (codes + formatted amounts)
• Cart item extension: isGiftCard, giftcardData, displayPrice, customPrices, gallery, etc.
• Update callback: update_cart_giftcard — same fields as classic AJAX edit

Frontend: frontend/assets/js/blocks/blocks-integration.js registers checkout filters and handles apply/redeem UI.

9. REST API Pro

Class: WALLREGI_Pro_Giftcard_Rest. Namespace: wc/v3 (WooCommerce REST authentication).

POST /wp-json/wc/v3/wallregi-giftcards/lookup
Content-Type: application/json
{ "giftcard_number": "YOUR-CODE" }

GET /wp-json/wc/v3/wallregi-giftcards/{giftcard_number}/transactions

Permission: manage_woocommerce or WooCommerce manager read; filter wallregi_pro_rest_giftcard_read_allowed.

10. AI assistant Pro

Requires valid Pro license. Option wallregi_pro_ai_settings; admin wx-gift-cards-ai. Classes in Pro includes/ai/; AJAX wallregi_pro_ai_generate. Custom copy: WALLREGI_AI_Messages + admin “Customize messages” on AI settings.

Helpers: wallregi_ai_is_enabled(), wallregi_ai_storefront_is_enabled() in includes/wallregi-ai-hooks.php (Pro maps real settings when licensed).

11. Security module

includes/wallregi-fraud-safeguards.php — rate limits on apply, form submit, cart edit, admin actions. Pro endpoints use wallregi_security_allow_pro_* filters (including AI generate).

Audit log table + admin screen wallregi_security. Hook: wallregi_security_audit_log( $event, $status, $context ).

12. Pro-only hooks & feature modules

12.1 Core Pro filter & action hooks

12.2 Balance Top-Up Architecture (WALLREGI_Pro_Topup)

Handles commercial recharge flows where buyers add funds to an existing gift card:

• Shortcode: [wallregi_topup] renders templates/topup-form.php.
• Cart Meta: Cart items store wallregi_topup_card_number and wallregi_topup_amount.
• Settlement Handler: Hooked on woocommerce_order_status_completed and woocommerce_order_status_processing. Updates current_amount in {prefix}wx_gift_cards, writes a topup ledger entry in {prefix}wx_giftcard_transaction, and triggers ePasscard push sync for Apple & Google Wallet passes.

12.3 SMS Gateway Contract & SendCloud Compatibility

Gift Rocket includes pluggable contracts for third-party SMS delivery and shipment tracking notifications:

• SMS Hook: apply_filters( 'wallregi_sms_dispatch_payload', $payload, $giftcard ) — Dispatches recipient SMS alerts via compatible SMS addons.
• SendCloud Integration: class-wallregi-sendcloud-compatibility.php ensures PDF vouchers and order notes attach cleanly during automated SendCloud fulfillment workflows.

13. Example: add a field to the edit modal

add_filter( 'wallregi_editable_giftcard_fields', function ( $fields, $key, $data, $context ) {
    $fields[] = 'my_custom_field';
    return $fields;
}, 10, 4 );

add_filter( 'wallregi_giftcard_cart_edit_payload', function ( $giftcard, $cart_item ) {
    $giftcard['my_custom_field'] = 'default';
    return $giftcard;
}, 10, 2 );

Then handle save in your own AJAX or extend the Store API update callback via free plugin patches (advanced).

14. Internationalization (i18n), RTL & WPML Integration

Gift Rocket is fully internationalized and adheres to modern WordPress i18n coding standards.

14.1 Text domain constants & translation helpers

14.2 Generating POT templates & compiling MO binaries

Both plugins include scripts to build POT templates and sync PO/MO files:

# Generate POT file for Free plugin
wp i18n make-pot . languages/wallet-ready-gift-cards-for-woocommerce.pot \
  --domain=wallet-ready-gift-cards-for-woocommerce \
  --exclude=vendor,languages

# Compile MO files for Pro plugin
wp i18n make-mo languages/

14.3 WPML configuration (wpml-config.xml)

Gift Rocket options (wallregi_settings, wallregi_email_settings, and wallregi_pro_ai_settings) can be automatically registered in WPML String Translation using the following wpml-config.xml schema:

<wpml-config>
    <admin-texts>
        <key name="wallregi_settings">
            <key name="recipient_name_label" />
            <key name="recipient_email_label" />
            <key name="message_label" />
            <key name="delivery_date_label" />
            <key name="price_label" />
            <key name="gallery_label" />
            <key name="apply_code_label" />
        </key>
        <key name="wallregi_email_settings">
            <key name="email_subject" />
            <key name="email_heading" />
            <key name="email_body" />
        </key>
        <key name="wallregi_pro_ai_settings">
            <key name="error_quota_exceeded" />
            <key name="error_rate_limited" />
        </key>
    </admin-texts>
    <custom-fields>
        <custom-field action="copy">_wallregi_checkout_receiver_address</custom-field>
        <custom-field action="copy">_wallregi_enable_email_schedule</custom-field>
        <custom-field action="translate">_wallregi_pro_product_greeting_presets_raw</custom-field>
    </custom-fields>
</wpml-config>

15. Development standards

• Sanitize all input; escape all output.
• Use manage_woocommerce (or stricter) for admin actions.
• Nonces on AJAX admin and storefront mutations.
• HPOS: gift card tables are custom; order reads should use WooCommerce order APIs.
• Text domain: wallet-ready-gift-cards-for-woocommerce (Pro uses wallet-ready-gift-cards-for-woocommerce-pro for Pro-only strings). Always pass text domain explicitly in all gettext calls.