=== Demfilz Gift Cards and Store Credit for WooCommerce ===
Contributors: demfilz
Tags: gift card, gift cards, store credit, gift voucher, gift certificate
Requires at least: 6.2
Tested up to: 7.1
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Sell gift cards, email them to the recipient and let shoppers spend them at checkout. Give customers store credit that applies itself.

== Description ==

Turn any product into a gift card. The buyer picks an amount, writes a message and says who it is for. When the order is paid the recipient gets an email with their code, the amount and the expiry date. They enter the code in the cart or at checkout and the balance comes off the order. Whatever is left stays on the card for next time.

Store credit works the same way, without a code: you add credit to a customer's account and it comes off their next order automatically.

**Gift card products**

* A "Gift card" checkbox next to Virtual and Downloadable, on simple and variable products.
* Preset amounts shown as buttons (for example $25, $50, $100, $200), an "other amount" box with your lowest and highest amount, or both.
* Variable products work too: each variation's price is the value of its card.
* "Who is it for?": someone else (name and email) or the buyer. Sender name and a personal message of up to 300 characters.
* A card sold at a fixed price is worth its regular price, so a sale price lets you sell a $50 card for $45. Cards with amount buttons are worth the amount chosen.
* Shop and category buttons open the product page, because the recipient details are needed.

**Sending the card**

* One card per item bought, each with its own 16 character code made from letters and digits that cannot be confused (no 0/O or 1/I), with an optional prefix such as XMAS.
* Sent when the order is paid, or only when you mark it Completed if you want to review gift card orders first.
* A WooCommerce email you can edit under WooCommerce > Settings > Emails, with a template your theme can override.
* The buyer sees who each card went to on the thank you page and in the order email, but never the code itself.

**Spending gift cards**

* A gift card field in the cart and at checkout, on the classic shortcode pages and in the cart and checkout blocks.
* Applied cards appear as rows in the order totals with a Remove link and the balance left after the order.
* A gift card is a payment, not a discount: the order keeps its full prices, shipping and tax, and only the amount to pay goes down. Your tax reports stay right.
* Cards pay for everything on the order, including shipping and tax. When they cover the whole order, no payment method is needed.
* Up to five cards on one order, plus store credit.
* Shoppers who type a gift card code into the coupon field get the gift card applied, in the classic checkout and in the blocks.
* The balance is taken when the order is placed, with a database check that stops two checkouts spending the same balance.
* Cancelled orders put the amounts back on the cards automatically. For refunds, a "Return to card" button in the order's Gift cards box gives the gift card part back, so refunding the money never returns the gift card part twice.
* Orders left unpaid (pending or failed) give their gift card and store credit amounts back after an hour, so an abandoned payment never locks up a balance. You choose the delay.
* If the order that bought a card is cancelled or refunded, its unspent cards are disabled. Refunding some of the cards on a line disables that many.

**Store credit**

* Add or deduct credit for any customer from WooCommerce > Gift Cards > Store credit, with a note and an optional email.
* Credit comes off the next order automatically while the customer is logged in. They can choose not to use it on an order.
* Customers can move a gift card into their store credit from My Account, so they do not need the code again.

**My Account and balance checks**

* A "Gift cards" tab in My Account: store credit balance and history, add a gift card, the cards they bought and a balance check.
* A `[dgcw_balance]` shortcode for a public balance check page, linked from the gift card email.

**For the store owner**

* WooCommerce > Gift Cards with totals for the unspent gift card balance and store credit (the figures your accountant asks for), cards issued and spent this month.
* Search and filter cards (active, used up, expired, disabled), open a card to see its full history, adjust the balance, change the recipient or the expiry date, resend the email, disable or enable it.
* Issue a gift card by hand for in-store sales, prizes or goodwill.
* Export the list or the full history to CSV.
* A Gift cards box on each order showing the cards it used and the cards it bought.

**Sensible, safe defaults**

* Gift cards expire after 36 months by default, and the expiry date is shown in the email, the account page and the balance check. In Australia most gift cards sold to consumers must be valid for at least 3 years and show their expiry date; the plugin warns you if you set less. Set 0 for cards that never expire.
* Gift cards cannot be bought with other gift cards, and coupons do not discount gift card products. You can allow both.
* Wrong codes are limited to 8 attempts per 15 minutes per visitor, and codes you type in yourself must be at least 8 letters or digits.
* Works with the WordPress privacy tools: exporting a person's data includes their gift cards, and erasing it removes names, email addresses and messages while keeping the balances, which are financial records.
* Compatible with WooCommerce High-Performance Order Storage (HPOS) and the cart and checkout blocks.
* No external services. Nothing leaves your site.

**For developers**

Actions: `dgcw_card_created`, `dgcw_card_debited`, `dgcw_card_credited`, `dgcw_card_status_changed`, `dgcw_card_applied`, `dgcw_product_fields_after`, `dgcw_email_card_before`, `dgcw_email_card_after`, `dgcw_account_card_actions`, `dgcw_admin_card_actions`, `dgcw_order_box_after`, `dgcw_admin_tab_{tab}`.

Filters: `dgcw_validate_product_fields`, `dgcw_cart_item_data`, `dgcw_item_display_rows`, `dgcw_card_args_from_item`, `dgcw_send_card_now`, `dgcw_admin_tabs`, `dgcw_account_endpoint`, `dgcw_max_failed_attempts`.

== Installation ==

1. Install and activate the plugin. WooCommerce must be active.
2. Edit a product (or add a new one), tick "Gift card" next to Virtual, and open the Gift card tab to set the amounts.
3. Publish it, and buy one to see the email.
4. Optional: create a page with the `[dgcw_balance]` shortcode and choose it under WooCommerce > Gift Cards > Settings as the balance check page.

== Frequently Asked Questions ==

= Why is a gift card a payment and not a coupon? =

Because that is what it is. When someone pays with a gift card, the goods are still sold at their full price and tax is still due on them; the card simply pays part of the bill. Coupons reduce the price, and with it the tax, which is wrong for gift cards. So the plugin keeps the order's prices, shipping and tax, and takes the gift card off the amount left to pay.

= Is tax charged when a gift card is sold? =

Gift card products are set as not taxable, because tax is normally due when the card is spent, on the goods it pays for. Check with your accountant for your country.

= Does it work with the cart and checkout blocks? =

Yes. The gift card field, the applied cards and store credit appear in the order summary of the cart and checkout blocks, and the total updates straight away. The classic shortcode cart and checkout are supported too.

= What happens if a payment fails? =

The amount taken from the gift card stays reserved on the order for an hour (you can change this), so the customer can try the payment again. After that, or as soon as the order is cancelled, the amount goes back on the card and the order's total goes back to the full amount.

= What happens when an order is refunded? =

Refund the money through WooCommerce as usual. The gift card and store credit part of the payment is not given back automatically, because WooCommerce marks an order Refunded as soon as the money part is refunded. To give it back, use "Return to card" in the order's Gift cards box. Cancelled orders give everything back automatically.

= Can I set my own codes? =

Yes, when you issue a card by hand. Codes created automatically are random, 16 characters long, and can have a prefix you choose.

= Can customers check their balance? =

Yes: in My Account > Gift cards, and on any page where you put the `[dgcw_balance]` shortcode. Applied cards also show the balance left after the order.

= How long are gift cards valid? =

36 months by default, which meets the 3 year minimum that applies to most gift cards sold to consumers in Australia. Change it under WooCommerce > Gift Cards > Settings. Expired cards keep their history; give one a new expiry date and it comes back with the balance it had when it expired.

= Can a gift card pay for shipping? =

Yes. It pays for anything on the order: products, shipping, fees and tax.

= Can I sell a gift card at a discount? =

Yes, for a card sold at a fixed price (no amount buttons): put the product on sale. The card is worth its regular price and the customer pays the sale price.

= I typed a gift card code into the coupon field. Does that work? =

Yes. If the code is not one of your coupons but is a gift card, it is applied as a gift card.

= Does it work with PayPal, WooPayments, Stripe, Afterpay and Zip? =

Yes. The payment gateway charges the order total, which is what is left after gift cards and store credit. For gateways that also send the order's lines, the plugin tells them about the gift card part: WooCommerce PayPal Payments shows it as a discount, so the PayPal window shows the amount that will be charged and the tax stays correct, and WooPayments and Stripe get card data (Level 3, US accounts) that adds up to the amount charged. Afterpay and Zip need nothing extra. With a gift card applied, Apple Pay and Google Pay show the total without the itemised lines.

= Does it work with Xero, QuickBooks and MYOB? =

Yes, with Demfilz Sync for Xero (1.2.9 or later), Demfilz Sync for QuickBooks (1.2.1 or later) or Demfilz Sync for MYOB (1.3.4 or later). Choose a gift card liability account (QuickBooks: a "Gift card" item whose account is a liability) and a tax code with no tax on the plugin's Mapping tab. Gift cards sold post to that account instead of income. When an order is paid partly by gift card or store credit, the invoice keeps every product and shipping line with its tax, and the amount paid by card is a negative line against the gift card account, so revenue and tax stay complete and the invoice total matches what the customer paid at checkout.

= How do other plugins see the gift card part of an order? =

The order total is what is left to pay after gift cards and store credit; prices, shipping and tax are unchanged. The amounts are stored in the order meta `_dgcw_applied`: a list of entries with `card_id`, `type` (gift or credit), `tail`, `amount`, `debited` and `returned`. Entries with `debited` 1 and `returned` 0 are the ones that paid for the order (`DGCW_Redeem::order_sum( $order )` adds them up). Gift card lines being sold carry the order item meta `_dgcw_data`.

= Is there a Pro version? =

Yes. Demfilz Gift Cards and Store Credit Pro adds delivery dates, card designs, printable cards, bulk codes, CSV import, refunds to store credit and expiry reminders. Everything described on this page works without it.

= Is there a limit on cards per order? =

Five gift cards per order, plus the customer's store credit.

= Are the codes secure? =

Codes have 80 bits of randomness, which makes guessing one impossible in practice, and the code fields lock a visitor out for 15 minutes after 8 wrong codes. Store managers see full codes; buyers only see the last four characters of cards they sent to someone else.

== Screenshots ==

1. WooCommerce > Gift Cards: balances, filters and the card list.
2. A gift card: balance, details, editing and the full history.
3. The product page: amount buttons, own amount, recipient and message.
4. The gift card email.
5. A gift card and store credit applied in the checkout block.
6. Store credit for a customer.
7. My Account > Gift cards.
8. Settings.

== Changelog ==

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.0.0 =
First release.
