Getting started with Artbees Gift Cards

Artbees Gift Cards for WooCommerce lets customers buy a digital gift card for themselves or someone else. The recipient then spends it at checkout. This guide takes a new store from installation to a first test card in about 15 minutes.

Before you start

You need:

WordPress 6.9 or later and WooCommerce.
64-bit PHP 7.4 or later with the Sodium and mbstring extensions.
MySQL or MariaDB with InnoDB tables.
A working WP-Cron or server cron. Gift emails and other background tasks run on it. WooCommerce's Action Scheduler is used when it's available.
A way to send email from WordPress, such as your host's mail or an SMTP plugin.
To let customers pay the rest of an order that a gift card doesn't fully cover: the official WooCommerce Stripe Gateway, WooPayments, or a bank transfer that you confirm yourself. See Redeeming gift cards at checkout.

A store runs gift cards in one currency. Choose your store currency before you issue any cards. You can't change it while cards still hold value.

1. Install and activate

Install and activate WooCommerce.
Go to Plugins → Add New, search for Artbees Gift Cards, then install and activate it. You can also upload the ZIP through Upload Plugin.
On multisite, activate the plugin on each site. Network-wide activation isn't supported.

When you activate the plugin, it creates its own database tables and an encryption key for gift card codes. The key is stored in your WordPress database, so a normal database backup includes it. If you want to keep it separate from the database, read Protecting codes and backups before you issue cards.

Two menus appear:

Artbees → Gift Cards for settings.
WooCommerce → Gift Cards for day-to-day work with cards.

2. Follow the three-step setup

Open Artbees → Gift Cards → Overview. The Your three-step setup panel lists:

Create a gift product. Choose preset amounts or a custom range.
Confirm your brand and email. Style the gift and place a balance-check page.
Run a paid test order. Check one card per unit, delivery and redemption.

Create a gift product

Go to Products → Add New.
Under Product data, choose Gift card as the product type.
Open the Gift card tab and fill in:
- Preset amounts: comma-separated values with a dot for decimals, for example 25, 50, 100.
- Custom amount: tick it to let the buyer enter their own amount.
- Minimum custom amount and Maximum custom amount.
Set the tax status you need. The plugin doesn't decide how gift card sales are taxed. Set this up on purpose for your store.
Publish.

You need at least one preset amount or a valid custom range. Gift card products are virtual. Coupons and sale prices never reduce the face value of a gift card.

Confirm your brand

Open Artbees → Gift Cards → Style:

Accent color, Text color and Corner radius.
Choose logo from media library to add your logo.
The Live gift preview shows the result. It's a sample and can't be redeemed.

Open General:

Store name on gift cards.
Require recipient name. The recipient email is always required when the gift goes to someone else.
Message character limit.
Balance-check page: select a page, or click Create balance-check page. See The balance-check shortcode.
Saved cards: Let customers save cards to their account is on by default.
Validity: cards don't expire unless you set Validity in days. See Saved cards and expiry.

Select Save changes. New settings apply to new purchases only. Cards that are already issued keep the design and terms they were sold with.

Confirm your email

Open Emails:

Edit the Subject, Heading and Footer of the gift email. You can use {store}, {sender} and {amount}.
Under Test the experience, enter a Test recipient and click Send a test email.
Check that inbox. The test uses a sample card that can't be redeemed.

If the test isn't accepted, see Gift email troubleshooting.

Run a paid test order

Open your gift product as a customer, choose an amount, choose Send to someone, and enter an email address you control.
Pay with the payment method your customers will use.
Go to WooCommerce → Gift Cards. The card appears once payment is confirmed.
Open the card. Check that its value, recipient and delivery state are correct.
Use the code from the email at checkout on a second order to confirm redemption.

If you paid by bank transfer or another offline method, the card won't appear until you confirm the payment. See Selling and sending gift cards.

The Overview health panel

Overview → Delivery & background health shows:

Queued or scheduled: emails waiting to be sent.
Needs delivery review: emails that failed or have an uncertain result.
Last queue run: when background tasks last ran.

Run due tasks now processes anything that is due straight away. Retry failed fulfillment tasks puts failed tasks back in the queue. If you see "WP-Cron is disabled", make sure a server cron runs WordPress scheduled tasks.

Who can do what

The plugin adds its own permissions to the Administrator and Shop manager roles: managing cards, issuing, refunding, exporting, adjusting balances and revealing codes. You can remove any of these from a role with a role-editor plugin. For example, a support agent could look up cards without being able to adjust balances.

Protecting codes and backups

Codes are random 128-bit values, encrypted in the database. Admin screens show them masked until someone with permission selects Reveal code.
Back up the database regularly. Codes can't be recovered without the encryption key.
To keep the key outside the database, define your own base64-encoded 32-byte key in wp-config.php before activating the plugin:

define( 'ARTBEES_GIFT_CARDS_MASTER_KEY', 'your-base64-key' );

Back up wp-config.php separately. Never replace the key once cards exist.

Deactivating or deleting the plugin keeps all card records, balances and settings, so customer balances are never lost by accident.

WP-CLI

wp gift-cards status checks the tables and encryption key.
wp gift-cards reconcile checks every card's balance against its history. It changes nothing.
wp gift-cards run-jobs processes due background tasks.