Beltoft Gift Cards for WooCommerce

Beltoft Gift Cards for WooCommerce adds a gift card product type to your store. Customers purchase a gift card, choose an amount, and enter the recipient’s email. When the order is processed, the recipient gets a branded email with their unique gift card code. Codes are redeemed at checkout through the standard WooCommerce coupon field — no extra steps for the customer.

Key Features

1. Gift card product type — predefined amounts (e.g., $25, $50, $100) or custom amounts within configurable min/max.
2. Email delivery using WooCommerce email templates — same look as your order emails.
3. Coupon field redemption — gift card codes work in the standard WooCommerce coupon field, no setup required.
4. Optional dedicated “Apply Gift Card” field on cart/checkout via settings or [bgcw_apply_field] shortcode.
5. Auto-apply from email — the “Shop Now” button in the delivery email automatically applies the gift card to the recipient’s cart.
6. Balance tracking with partial redemption — remaining balance carries over to the next purchase.
7. My Account tab — customers view their gift cards, balances, and full transaction history.
8. Personal message displayed in cart and order details.
9. Price range display — gift card products show “From $25” or “$25 – $100” in your shop catalog.
10. Admin dashboard with stats: total issued, outstanding balance, redeemed, and expired counts.
11. Gift card management list with search, status filters, pagination, and bulk actions (disable/delete).
12. Manual gift card creation from the admin panel — no order required.
13. Order meta box showing gift cards created by and used on each order.
14. Automatic balance restore on order cancel/refund, including proportional partial refund support.
15. Loyalty Rewards integration — optionally block or allow customers from using loyalty points to purchase gift cards (requires Loyalty Rewards for WooCommerce).
16. Shortcode [bgcw_product_form] for page builders (Bricks, Elementor, etc.).
17. HPOS compatible — works with WooCommerce High-Performance Order Storage.
18. Email settings (subject, heading, on/off) under WooCommerce > Settings > Emails.
19. Gift card source tracking (shop order, paid offline, promotion, compensation) — the redeeming order records whether the card was paid or free, for accounting.
20. REST API (wc-bgcw/v1) to list, create, update, adjust, and delete gift cards from external systems; works with WooCommerce REST API keys.

How It Works

1. Create a “Gift Card” product in WooCommerce and set the predefined amounts.
2. Customer purchases the gift card, picks an amount, and enters recipient details and an optional message.
3. When the order is processed, a unique code is generated and emailed to the recipient.
4. Recipient enters the code at checkout in the coupon field — the gift card balance is applied as a discount.
5. Partial use is tracked. The remaining balance stays on the gift card for future orders.

Configuration

Gift Card Product

• Create a product, select “Gift card” as the product type.
• Set predefined amounts in the Gift Card data panel (e.g., 25,50,75,100).
• Custom amounts and their min/max are controlled from the global settings page.

Redemption

• Gift card codes always work in the standard WooCommerce coupon field — this is automatic.
• To also show a dedicated “Apply Gift Card” field, enable it in settings with automatic placement or shortcode-only.
• Shortcode: [bgcw_apply_field] — place it on cart or checkout pages.
• Recipients can click “Shop Now” in the delivery email to auto-apply the gift card to their cart.

Email Template

• Uses WooCommerce’s email system — same header, footer, and colours as your other store emails.
• Customise subject and heading under WooCommerce > Settings > Emails > Gift Card Delivery.
• Override the template by copying templates/emails/gift-card-delivery.php to your theme’s woocommerce/emails/ folder.

Page Builders

• For Bricks, Elementor, or other page builders that replace WooCommerce templates, use the WooCommerce Add to Cart element or the [bgcw_product_form] shortcode.

REST API

Base: https://your-store.example/wp-json/wc-bgcw/v1/. Authenticate with WooCommerce REST API keys (Basic auth over HTTPS) or a WordPress application password. Requires the manage_woocommerce capability.

GET /gift-cards — List. Params: page, per_page (<= 100), search, status, source, orderby, order.
POST /gift-cards — Create. Body: amount*, source* (paid_offline, promotion, compensation), recipient_name, recipient_email, sender_name, sender_email, message, expires_at (ISO 8601 or null), send_email (default true).
GET /gift-cards/{id} — Single card.
GET /gift-cards/code/{code} — Single card by code.
PATCH /gift-cards/{id} — Update status (active/disabled), source, recipient/sender fields, message, expires_at.
POST /gift-cards/{id}/adjust — Change balance. Body: amount (positive credit, negative debit), note.
GET /gift-cards/{id}/transactions — Ledger.
DELETE /gift-cards/{id}?force=true — Permanently delete card and ledger.

All datetimes in responses (created_at, expires_at, transaction created_at) are ISO 8601 in UTC with a trailing Z (e.g. 2032-01-31T00:00:00Z). On input, expires_at accepts an ISO 8601 datetime (interpreted as UTC when no offset is given), a MySQL datetime string, or null to clear it. recipient_email and sender_email accept a valid email address or an empty string to clear the field.

Every card includes source and is_paid. On redeemed orders, each gift card coupon line carries bgcw_gift_card_id, bgcw_source, bgcw_is_paid, bgcw_source_order_id, and the order carries _bgcw_paid_redeemed_total / _bgcw_free_redeemed_total. Those two order totals reflect amounts actually deducted and are not reduced by later refunds; refunds appear as separate refund transactions in the ledger.

Validation failures return HTTP 400; failures while creating, updating, deleting a card, or recording a ledger entry return HTTP 500 (bgcw_rest_create_failed, bgcw_rest_update_failed, bgcw_rest_delete_failed, bgcw_rest_ledger_failed). The /adjust amount is bounded to +/-1,000,000.

Example:
curl -u ck_xxx:cs_xxx “https://your-store.example/wp-json/wc-bgcw/v1/gift-cards?source=promotion”

Hooks & Filters

Developers can extend the plugin:

• bgcw_gift_card_created — fires after a gift card is created (used by the email system).
• bgcw_show_recipient_name_field — return false to hide the Recipient Name field on the product page.
• bgcw_show_recipient_email_field — return false to hide the Recipient Email field on the product page. The buyer’s billing email is used as the recipient and the email validation is skipped.
• bgcw_show_personal_message_field — return false to hide the Personal Message field on the product page.
• bgcw_rest_permission — filter REST access (default: manage_woocommerce).

Example — hide the Recipient Email field on every gift card product:

add_filter( 'bgcw_show_recipient_email_field', '__return_false' );