Customize Features Docs Changelog Support
Buy Now — $39/yr

Documentation

Complete guide for installing, configuring, and using Gift Cards for Amelia.

Requirements

Installation

  1. Download the amelia-gift-cards.zip file from your LemonSqueezy account
  2. Go to WordPress Admin → Plugins → Add New
  3. Click Upload Plugin and select the ZIP file
  4. Click Install Now, then Activate

After activation, you should see a "Gift Cards" menu in your WordPress admin sidebar.

Quick Start

Get your gift card system running in under 10 minutes:

  1. Activate the plugin — an admin notice appears with a link to the License page and information about the Divi module
  2. Configure payments — Stripe/Square auto-detected from Amelia (Pro/Premium) or enter keys manually
  3. Create a gift card type — list your amounts in Gift Cards → Settings → General → Predefined Amounts, then create your first type in Gift Cards → Gift Card Types
  4. Add the form to a page — copy the shortcode of your type from the Shortcode column of Gift Cards → Gift Card Types, for example [agc_gift_card_form type="1"], and paste it on any page
  5. Test a purchase — use test mode to verify everything works

Payment Setup

v3.19 Buyers can pay with Stripe, Square, PayPal or at your WooCommerce checkout; Mollie, Razorpay and Barion are coming soon. The plugin uses the payment methods you have already set up in Amelia: same keys, same test or live mode, same currency. A method can be offered once Amelia itself would take payments with it:

In Gift Cards → Settings → Payment, tick the methods buyers can choose and drag the rows into the order you want: the first one is preselected. Each row shows what Amelia reports (mode, currency, and why a method cannot be offered, with a link to fix it). With a single method the purchase form looks as before; with several, buyers pick one before paying.

Stripe Setup

Automatic (Pro / Premium)

If you have Amelia Pro or Premium, the plugin automatically uses your existing Stripe configuration from Amelia. No additional setup required.

Manual (Starter / Standard)

If you have Amelia Starter or Standard:

  1. Go to Gift Cards → Settings → Payments
  2. Enter your Stripe Publishable Key and Secret Key
  3. Enable Test Mode for initial testing
  4. Click Save & Verify to test the connection
Note: You can find your Stripe API keys at dashboard.stripe.com/apikeys.

v3.19 With Amelia's keys, Stripe follows its switch in Amelia: when it is off there, the gift card form no longer offers it; turn it on in Amelia, or choose your own keys in Gift Cards → Settings → Payment. Like Amelia, Stripe only offers payment methods confirmed during checkout: SEPA Direct Debit, other bank debits and vouchers are left out. Unfinished Stripe payments are checked every 15 minutes, so a buyer who pays with iDEAL or Klarna and never comes back still gets the gift card. Webhook (recommended): add the endpoint shown in the settings in Stripe's test mode and live mode, and paste each signing secret in its field.

Square Setup

Square is also supported as a payment provider:

  1. Set up Square in Amelia → Settings → Payments: the plugin reads its configuration from there
  2. In Gift Cards → Settings → Payment, tick Square
  3. Open its details to check the configuration read from Amelia (application, location, mode, currency)

v3.19 The currency of the Square location selected in Amelia must be Amelia's currency: otherwise Square refuses the payments, so it is not offered. When Square's access token expires, the plugin renews it through Amelia. Google Pay and Apple Pay can be ticked in the Square settings (off by default); Apple Pay also needs your domain registered with Square, as described in Amelia's Square guide. A refund made in Square is emailed to you; the gift card stays active until you deactivate it.

PayPal v3.19

Set up PayPal in Amelia (client ID and secret of the sandbox or live app), then tick it. Buyers pay in PayPal's window without leaving your page; your site captures the payment as soon as they approve it, then shows the confirmation page. PayPal sends no notification to your site: a payment approved in a window closed too early is captured by the check of unfinished payments. In live mode PayPal only pays a verified Business account: until yours is verified, PayPal holds the payments; the plugin follows them, emails you what to do in PayPal, and issues each gift card once PayPal completes its payment.

Mollie, Razorpay and Barion Coming soon

Amelia also takes payments with Mollie, Razorpay and Barion; the plugin will offer them in a coming update. Until then they are shown in Gift Cards → Settings → Payment with a Coming soon badge and cannot be ticked, even when they are set up in Amelia.

WooCommerce v3.19

Turn on Amelia's WooCommerce integration, then tick WooCommerce. Amelia then also sends bookings through WooCommerce. The plugin creates a hidden virtual product for gift cards: each card becomes a cart line priced by the plugin, and buyers pay with any payment method of your shop. Your WooCommerce currency must be the same as Amelia's, and a cart cannot hold a gift card and a booking together.

The gift card is issued when the payment completes, when you mark the order Completed, or when it moves to Processing from On hold, Pending payment or Failed with a method other than cash on delivery. So a bank transfer issues the card once you mark the order Processing, and cash on delivery once you complete it. The code appears on the order, in the customer's account and in WooCommerce's emails, unless the card is delivered physically.

v3.19 A gift card is issued only for what the order really paid: shop coupons never apply to a gift card, and a discount, a negative fee or a currency switched at checkout is refused or leaves the order to you (you are emailed, no card is issued). A refund of a gift card order, even partial, is emailed to you; the card stays active until you deactivate it. A bank transfer or a cheque confirmed weeks later still issues its card.

Unfinished payments and payments needing attention v3.19

Payments left unfinished (a window closed too early, a missed notification) are checked with the payment provider every 15 minutes, or at once with Check unfinished payments now in Settings → Payment. When a payment was taken but its gift card could not be issued, the plugin tries again with growing waits and emails you after 5 tries with the purchase details. After 10 tries, or at once when trying again cannot help, it stops and lists the payment under Payments needing attention at the top of Settings → Payment: create the gift card in Gift Cards → Manual Gift Card or refund the buyer, then click Mark as handled. The Payment Gateways card of Diagnostics counts these payments and checks your gateways' keys.

Content Security Policy: if your site sends one, allow PayPal (*.paypal.com, *.paypalobjects.com) for scripts and frames, or its window will not open.

General Settings

Navigate to Gift Cards → Settings → General to configure:

Text & Language Presets

Every label, button and message on the purchase form, the confirmation page, the emails and the printable PDF is editable in Gift Cards → Customize → Text, with one sub-tab per language. Each language ships with a complete preset:

You do not pick the language yourself: each visitor is served the one matching your site’s language, and every gift card remembers the language it was bought in — so a card bought in French keeps sending French emails, whatever language the site is showing later.

Note: a field you leave empty keeps the preset's wording, and later improvements of that wording reach you with updates. Only the fields you fill in are yours.

Email Settings

The sender of every gift card email is set in Gift Cards → Customize → Confirmation Page & Mail → Sending Settings:

Delivery & Printable PDF

In Gift Cards → Settings → Delivery, choose how a buyer can receive the gift card. Delivery by email is always offered. The two physical options are off until you turn them on, and the purchase form only asks the question once one of them is on:

The code of a physical card stays with you. Neither the buyer nor the recipient receives it by email: you print or write it on the card, and the surprise stays intact. The buyer still gets their purchase confirmation, and a code printed on a card keeps working until its balance is used up (see Rolling Balance).

Printable PDF gift card v3.24

A printable A4 version of the gift card, for buyers who buy online but prefer to hand the card over in person. It shows your card image (set in Customize → Confirmation Page & Mail → Branding, or else a band in the colour of the gift card type), the amount, who the card is for and from, the personal message, the code, the validity date and how to use it, in the language the card was bought in.

See an example: gift-card-example-en.pdf (A4, 145 KB).

Three options under Settings → Delivery → Printable PDF, all off by default:

Edit its wording per language under Customize → Text → Printable PDF Gift Card, check it with Preview the PDF on the settings page, and download the PDF of any card from its record in All Gift Cards. Every preset language prints, Polish and Bulgarian included, and a card always fits one A4 page, with margins any printer can handle.

In your own email templates v3.25, place a download button for the PDF wherever you like with the PDF variables of the HTML Email tab.

A PDF never holds up an email. If one cannot be created, the email leaves without it and the reason is written to the plugin log. Developers can change what the card shows, its image or its font with the PDF filters.

Advanced Settings

Customize Menu

Gift Cards → Customize brings every visual setting in one place, in four tabs: Text for every customer-facing wording, per language; Visual Template for the public purchase form; Confirmation Page & Mail for the confirmation page and the emails; and HTML Email for your own email templates. The visual tabs offer a live preview that reflects your changes as you edit. New in v2.0

Migration from v1.x: The legacy Settings → Appearance and email-customization screens have been merged here. The global Primary/Secondary color settings have been removed — email colors are now driven by each gift card type's preset (see Email Templates).

Visual Template tab

Designs the public purchase form. Each of the 6 built-in templates (Spa, Restaurant, Beauty, Fitness, Medical, Generic) can be duplicated and edited independently — your customizations live alongside the originals so you can always revert.

Mail tab

Designs the recipient and purchaser emails. The colors come from the gift card type that's being sent — pick a type in the preview selector to see what each customer would actually receive.

Starter presets

Three one-click presets bundle typography, layout and spacing as a sensible starting point:

Typography

Layout

Branding

Live preview

A gift card type selector at the top of the preview lets you instantly visualize the actual rendering for each type — no need to send test emails to verify your branding.

Next to it, a second selector chooses which email you are looking at: the gift card sent to the recipient, the purchase confirmation sent to the buyer, or the balance update sent after each booking. v3.13

What these settings cover: the logo, colours, typography and footer on this tab apply to all three emails — including the balance update, which before v3.13 went out as plain unstyled text. An email you give its own template on the HTML Email tab no longer uses them.

HTML Email tab v3.14

When the visual controls are not enough, this tab lets you replace the emails with your own raw HTML — your existing house template, pasted in. Switch on Enable custom HTML, write your markup, and use the %token% list shown beside the editor to drop in the code, the amount, the recipient's name and so on. Values typed by the buyer, such as names and the personal message, are inserted safely: they cannot break your layout.

Each language has its own template, on its own sub-tab. Buyers receive the template for the language they bought in; a language you leave untouched falls back to English, and if you never write an English one either, the built-in design is used. The on/off switch is shared — it covers every language at once.

One template per email: sub-tabs above the language tabs select the email you are editing — the gift card sent to the recipient, the purchase confirmation sent to the buyer, or the balance update sent after each booking. The purchase confirmation keeps sending the gift card template, and the balance update keeps its Confirmation Page & Mail design, until you tick Own template on their sub-tab. You can prepare and save a template first: it only goes out once that box is ticked.

The balance update template has its own variables: %amount_used% (the amount just spent), %remaining_balance%, %formatted_amount% (the card's original value) and %formatted_expiry_date%, alongside the code, the recipient's name, your site details and the card colours. Purchase details such as the buyer or the personal message are not available there — that email is sent at booking time.

The purchase emails also have per-purchase variables: %amount_label% (the amount's tile label, v3.16), %card_visual_url% (your card picture, v3.16), %invoice_request_notice% (the line confirming an invoice request, purchase confirmation only, v3.16), %supplements% (the supplements included, names only, v3.17) and %supplements_detail% (with their prices, purchase confirmation only, v3.17). %supplements_detail% stays empty in the gift card email, so a gift never shows prices.

Printable PDF v3.25: %pdf_download_button% places a ready-made button that downloads the card's printable PDF, in the colour of the gift card type and with the Download button wording of Customize → Text → Printable PDF Gift Card. For your own design, use %pdf_download_url% as the address of a link: <a href="%pdf_download_url%">Print your gift card</a>. Both work in the gift card email and the purchase confirmation once Gift cards sent by email is ticked under Settings → Delivery → Printable PDF. A card without a PDF, such as one picked up or sent by post, gets no button, and a link whose address is %pdf_download_url% is removed with its text.

Upgrading from v3.12 or earlier: nothing to redo. A template you had saved before is copied into every language tab the first time the new version runs, so it keeps going out to all your buyers exactly as it did.

Send test sends the template of the email and language you are on, filled with placeholder values. Save before testing — the test reads what is stored, not what is on screen.

Creating Gift Card Types

Gift card types define the look, amounts, and restrictions for your gift cards.

  1. Go to Gift Cards → Gift Card Types
  2. Click Add New Type
  3. Fill in the name, description, and select an email template
  4. Configure amounts, validity and restrictions
  5. Save, then copy the shortcode from the Shortcode column, such as [agc_gift_card_form type="3"], onto the page that sells this card

Amounts & Pricing

For each type, you can configure:

Supplements and Amelia extras: for the gift card to pay for the supplements when the recipient books, create the same extras on the service in Amelia, with no duration and not multiplied by the number of people. Amelia applies the card to the service first, then to its extras. Otherwise their value simply stays on the card as a remaining balance for a later booking.

Restrictions

Choose what a gift card type cannot be used for. In the type editor, under Restrictions (Exclusions), tick the Amelia items the card must not pay for:

Email Templates

The plugin ships with 6 built-in templates. Each one defines a primary and secondary color, and the recipient email is automatically themed to match the gift card type that was bought:

To restyle a template — colors, font, button style, email typography and branding — use the new Customize menu. Duplicate any built-in template, edit it independently and the originals stay untouched.

Changed in v1.5: the global Primary/Secondary Color settings have been removed. Email colors now follow the gift card type's preset, so each recipient gets an email matching the type they were gifted.

Success Page

After a successful purchase, the buyer lands on a redesigned success page that visually matches the recipient email — a clean 600 px white card themed by the gift card type's primary/secondary colors. Redesigned in v1.5

WordPress Shortcode

Add the gift card purchase form to any page or post with the shortcode of a gift card type, shown in the Shortcode column of Gift Cards → Gift Card Types:

[agc_gift_card_form type="1"]
The type attribute is required: it is the ID of the gift card type. Without it, or with a deleted or inactive type, the page shows an error message instead of the form. One form sells one type: to sell several, add one shortcode per type. Everything the form shows comes from the type and the settings: amounts, custom amount, colors and restrictions from the type, the custom amount limits from Gift Cards → Settings → General, the title and texts from Gift Cards → Customize → Text. The only other attribute is css_class, an extra CSS class for your own styles: [agc_gift_card_form type="1" css_class="my-form"]. Attributes such as title, amounts or min_amount, documented for earlier versions, are ignored.

Divi Builder Module

If you use the Divi theme, a native Gift Card module is available:

  1. Edit a page with Divi Builder
  2. Click Add Module and search for "Gift Card"
  3. Configure the design options (colors, fonts, spacing)
  4. Save and publish
Note: The Divi module is optional. The shortcode works with any theme.

Frontend Form

The purchase form guides customers through 3 steps:

  1. Choose Amount — select a preset or enter a custom amount
  2. Recipient Details — name, email, personal message
  3. Payment — secure checkout with Stripe (3D Secure), Square, PayPal or your WooCommerce shop

After payment, the recipient receives a beautifully designed email with their gift card code.

Invoice requests v3.16

Buyers can tick I need an invoice on the form and enter their billing details. You receive them by email and issue the invoice from your own accounting tool: the plugin does not create invoices, and the Stripe receipt is a payment receipt, not an invoice. It is off by default: turn it on under Settings → Delivery → Invoice requests, choose which billing fields are hidden, optional or required, and let a gift card type always offer it or never. The request shows in All Gift Cards and in exports, and the buyer sees a confirmation line in their purchase confirmation and on the success page.

Dashboard

The dashboard (Gift Cards → Dashboard) provides:

Rolling Balance

Since v3.0, every gift card issued by the plugin carries a rolling balance: one card pays for several Amelia bookings until its value is used up — a behavior that native Amelia coupons do not provide. Since v3.22, the customer keeps the same code until the balance is used up, so a code printed on a card sent by post keeps working v3.22. You can instead move what is left after each booking to a new code, sent by email.

How it works in practice

  1. A customer buys a $100 gift card. The recipient gets the code GIFT-A3B7-9K2M, worth $100.
  2. The recipient books a $30 service in Amelia and enters the code as a coupon. Amelia applies the full $30 discount.
  3. The plugin records the redemption in its transaction ledger. The part used is archived in Amelia as GIFT-A3B7-9K2M_1, at its original value, so Amelia keeps showing the booking as paid. The customer's code now carries the remaining $70.
  4. The customer automatically receives an email showing Used: $30 / Remaining: $70 and telling them to use the same code next time.
  5. Later, a $70 booking made with the same code uses it up. No balance email is sent: Amelia already confirms the booking.
Prefer a new code after each booking? Under Settings → Gift Card Balance → Remaining balance, choose Issue a new code for the remaining balance after each partial use. What is left then moves to a new code, which the balance email always delivers. Sites installed before v3.22 keep this choice until you change it. Either way, earlier bookings keep their amounts in Amelia's invoices and exports. The option that lowered the coupon after each booking was removed in v3.22, since it changed those amounts; sites that used it now keep the same code.

Automatic balance email

After each redemption, the plugin sends a transactional email summarizing what was just used, how much remains on the card and, when the balance got a new code, that code. It goes to the card's recipient; for a card with no recipient email, such as one handed over in person, to the customer who made the Amelia booking, or else to the buyer v3.17. Since v3.13 it is built from the same design as your other emails — your logo, colours, fonts and footer from Customize → Confirmation Page & Mail, and the accent colour of the gift card type it belongs to.

The wording itself — the greeting, the “you just used” line, the remaining-balance line and the closing instruction — is yours to edit per language under Customize → Text, in the Email — Balance Update Notification group. Under Settings → Gift Card Balance you can turn the email off (one that gives a new code is always sent) and choose whether a booking that uses up the whole balance sends one too — off by default since v3.17. Untick Send it to the buyer when neither the recipient nor the customer who made the booking has an email address to keep the buyer out of it: a buyer who gave the card away, such as one sent by post, then never receives it v3.23. An email that gives a new code still goes to the buyer when nobody else has an address, so that the code always reaches someone.

Where to see the ledger

Open Gift Cards → All Gift Cards and press Details on any gift card to see its full record: the initial purchase, buyer and recipient details, every redemption with the matching Amelia booking ID, the running balance after each event, and every email that was sent. The Logs view shows the same events across all gift cards with date/type filters.

Cancelled and deleted bookings: cancelling an Amelia booking does not give the amount back to the gift card: the booking still exists, and the audit trail stays intact. If a refund is needed, issue a new gift card instead. One exception since v3.21.1: when Amelia deletes a booking because its online payment was abandoned (the customer left the payment page), the amount goes back to the card automatically within minutes.

Manual Gift Card Creation

Create gift cards directly from the admin:

  1. Go to Gift Cards → Add New
  2. Fill in the amount, recipient details, and optional message
  3. Choose whether to send the notification email
  4. Click Create

Importing existing gift cards v3.12

Moving to Amelia from another platform? Gift Cards → Import brings your existing cards across from a CSV file — including cards your customers have already partly spent, which keep exactly the balance they have left.

Each card is recreated at its original face value, and the amount already used is recorded against it as a redemption. A card sold for 150 with 138.70 left arrives worth 138.70, and its history shows the 11.30 that was already spent. Nothing is emailed to anyone unless you ask for it.

The three steps

  1. Choose your file. A CSV with one gift card per row and a header row, separated by commas or semicolons. Exports from Squarespace, Square and Shopify are recognised automatically. A sample file is available to download.
  2. Check the columns. The detected mapping is shown so you can correct anything that is wrong, along with the import options below.
  3. Review and import. A dry run first: how many cards will be imported, skipped or rejected, the total original value, the balance still redeemable and how much was already spent — plus a per-row list of anything needing attention. Nothing is created until you press Import these gift cards, and the import then runs in batches with a progress bar.

Which columns are needed

Only the gift card code and the initial value are required. Everything else is optional: missing names are derived from the email address, and a missing remaining value is treated as unspent. Column names are matched ignoring case, spaces, underscores and hyphens, and each field accepts several common names — the full list is shown on the import screen itself.

Import options

Good to know: re-running the same file is safe — a code that already exists is skipped, never duplicated. Check that Amelia's currency matches the one in your file before importing: amounts are imported as written and never converted, and the dry run warns you if the two disagree.

Export

Export gift card data from the Dashboard (CSV report) or from Gift Cards → Logs (CSV log export). Filter by date range or status before exporting. The report ends with the columns added in recent versions: Origin (v3.15.1), Amount_Label and the billing details (v3.16), then Supplements (v3.17). Supplements are already included in Amount: do not add them twice.

Personal Data (GDPR)

Gift cards are part of WordPress's Tools → Export Personal Data and Erase Personal Data. An export lists the gift cards where the person is the buyer or the recipient, with the emails sent to them. Erasing anonymises their name, email address, message and postal address but keeps the code, the amounts and the balance: the card stays usable and your accounting records stay complete. A suggested paragraph is added to Settings → Privacy → Policy Guide.

Logs

View all system activity at Gift Cards → Logs:

Shortcode Reference

[agc_gift_card_form]

The purchase form of one gift card type.

ParameterDefaultDescription
type—Required. ID of the gift card type, shown in the Shortcode column of Gift Cards → Gift Card Types
css_class—Additional CSS class

Amounts, custom amount, colors and restrictions come from the type, the custom amount limits from Settings → General and the title from Customize → Text. The attributes title, description, amounts, allow_custom, min_amount, max_amount and template, documented for earlier versions, are ignored.

[agc_coupon_balance] v3.20

A balance check form: a customer types their code and sees the remaining balance and the expiry date. Put [agc_coupon_balance show_form="true"] on a page such as /gift-card-balance/, the address the %balance_check_url% token of the HTML emails points to. Only an exact code is answered, without any name, and lookups are rate limited. [agc_coupon_status code="…"] shows the status of a single code.

Developer Hooks

WordPress actions and filters for connecting gift cards to another system — a CRM, an accounting tool, or a second voucher platform. Add these to your theme's functions.php or a small plugin.

agc_amelia_coupon_created

Fires once per Amelia coupon, immediately after it is created and linked to the gift card. This is the hook to use when another system needs a matching code: it carries the code, the amount and the expiry date, so no database lookup is needed. It fires for online purchases and for gift cards created by hand in the admin.

ParameterTypeDescription
$coupon_idintAmelia coupon ID
$gift_card_idintGift card ID
$gift_card_dataarraycode, amount, expiration_date, gift_card_type_id — added in v3.8.0
add_action( 'agc_amelia_coupon_created', function ( $coupon_id, $gift_card_id, $data ) {
    wp_remote_post( 'https://example.com/api/vouchers', array(
        'timeout' => 15,
        'headers' => array( 'Content-Type' => 'application/json' ),
        'body'    => wp_json_encode( array(
            'name'    => $data['code'],
            'value'   => (float) $data['amount'],
            'expires' => $data['expiration_date'],
        ) ),
    ) );
}, 10, 3 );

Declare 3 as the last argument, as above, or the gift card data will not reach your callback. Listeners registered with 1 or 2 arguments keep working unchanged.

Keep the callback fast. The hook runs inside the purchase request, so a slow API call becomes a slow confirmation screen for your customer. Schedule anything lengthy with wp_schedule_single_event().

Failures are contained, and therefore silent. An exception thrown by your callback is caught and logged rather than propagated — a gift card that has been paid for must not be undone by a failing integration. The trade-off is that the customer sees nothing, so log failures on your side and reconcile.

One edge case worth knowing: if a generated code already exists in Amelia's coupons table, the plugin links the existing coupon instead of creating one, and this hook does not fire. Codes are random and checked for uniqueness, so this is very rare — but if your systems must never drift, reconcile periodically, or switch on the purchase notification email below as a second channel.

agc_gift_card_created

Fires after the gift card is stored, before the Amelia coupon exists. Use it only for work that does not depend on the coupon; otherwise prefer agc_amelia_coupon_created above.

ParameterTypeDescription
$gift_card_idintGift card ID
$gift_card_dataarrayGift card data as stored

agc_fulfilment_email (filter)

Overrides the address that receives the shop notification, ignoring the value set in Settings → Delivery. Useful for routing notifications per gift card type, or into a ticketing system's inbox.

add_filter( 'agc_fulfilment_email', function ( $email ) {
    return 'vouchers@example.com';
} );

agc_invoice_request_offered (filter)

Decides whether a purchase form shows the I need an invoice box, after the global setting (Settings → Delivery → Invoice requests) and the gift card type's own setting. It runs both when the form is displayed and when the payment is created, so returning false also drops a request sent anyway. The plugin never creates the invoice: the billing details reach you in the shop notification.

ParameterTypeDescription
$offeredboolWhether the box is offered, from the settings
$type_idintGift card type of the form, or 0 when it has none
$modestringThe type's own setting: inherit, always or never
add_filter( 'agc_invoice_request_offered', function ( $offered, $type_id, $mode ) {
    // Offer invoices on the corporate gift card type only.
    return 42 === $type_id;
}, 10, 3 );

agc_gift_card_code (filter)

Rewrites a gift card code as it is generated, for when the code has to follow a format another system expects. For the common case — simply putting the amount at the end of the code — you do not need this filter: switch on Settings → General → Append the amount to the code and every new code becomes GIFT-A3B7-9K2M-195.

ParameterTypeDescription
$codestringThe generated code, with the amount already appended if that setting is on
$contextarrayGeneration context — see the keys below
KeyTypeDescription
amountfloatThe card's face value. Any delivery fee is excluded, so this matches the coupon's deduction rather than what the buyer paid
currencystringCurrency code, uppercase. Never written into the code unless you add it yourself
gift_card_type_idintGift card type, or 0 when the purchase is not tied to one
prefixstringThe prefix actually in use, after your setting is applied
sourcestringWhere the card came from: a customer purchase, one created by hand in the admin, or a legacy form
attemptintRetry counter, starting at 1
add_filter( 'agc_gift_card_code', function ( $code, $context ) {
    if ( 'purchase' !== $context['source'] || empty( $context['amount'] ) ) {
        return $code;
    }

    return sprintf(
        'VOUCHER-%s-%s',
        (int) $context['amount'],
        strtoupper( wp_generate_password( 8, false, false ) )
    );
}, 10, 2 );

Return something that varies. This filter runs inside the loop that guarantees a code is unique, and the value you return is the one checked against the database. A filter that always returns the same string can never become unique, so the loop gives up and the purchase fails after the customer has been charged — vary your code, for example with $context['attempt'].

Stay within the allowed characters. A returned code must be 64 characters or fewer and use only letters, numbers, dots, dashes and underscores; anything else is ignored in favour of the generated code, with a note in the log. The code is never changed to upper case, because Amelia matches coupon codes exactly. These limits exist because the code is stored in two tables and appears in the buyer's confirmation link.

agc_append_amount_to_code (filter)

The code equivalent of the Settings → General checkbox, so you can switch the amount suffix on for some gift cards and not others. It receives the current setting as a boolean and returns the value to use.

agc_recipient_email_required (filter) v3.14

The code equivalent of the Settings → General → Recipient email checkbox, for example to require the address for some gift card types only. It receives the current setting as a boolean and returns the value to use. It only concerns email delivery: the address is never required for a card collected in person or sent by post.

agc_recipient_name_required (filter) v3.21

The code equivalent of the Settings → General → Recipient name checkbox, for example to require the name for some gift card types only. It receives the current setting as a boolean and returns the value to use. A card sent by post always requires the name, whatever the filter returns.

agc_email_attachments (filter) v3.20

Files attached to the customer emails: recipient (the gift card, also on a manual resend), confirmation (the buyer's receipt) and balance_updated. Five arguments: the array of absolute file paths, the email type, the gift card ID, the card's data and the email's template variables (gift_card_code, formatted_amount, formatted_expiry_date…). Return the array. The plugin's own printable PDF is added at priority 5, so a callback at the default priority sees it and can remove it.

agc_gift_card_pdf_data (filter) v3.24

What the printable PDF shows, as an array: code, amount, amount_label, supplements, recipient_name, sender_name, message, expiry, never_expires, site_name, site_url, primary_color and image. Change a value, or empty it to leave that line out. Return the array.

agc_gift_card_pdf_image (filter) v3.24

The image at the top of the PDF: a file path or a URL, '' for none. By default, the card image of Customize → Confirmation Page & Mail → Branding. JPEG prints as is; PNG, GIF and WebP are converted when the server has PHP's GD extension.

agc_gift_card_pdf_fonts (filter) v3.24

The TrueType files (.ttf) the PDF embeds: array( 'regular' => $path, 'bold' => $path ). The bundled font covers Latin and Cyrillic; supply another one for Greek, Arabic or Asian scripts.

agc_gift_card_balance_updated v3.13

Fires after a booking has drawn on a gift card, once the debit is committed. This is the hook for keeping another system in step with the remaining balance — a loyalty account, an accounting ledger, a dashboard. It is also what triggers the built-in balance email, so you can switch that off under Settings → Gift Card Balance and send your own instead.

ParameterTypeDescription
$gift_cardarrayThe gift card record, including code, recipient_email and locale — the language it was bought in
$amount_consumedfloatAmount just charged to the card
$new_balancefloatBalance remaining after this charge
$new_gift_cardarray|nullSince v3.15: the card that now carries the remaining balance (with its code and amount), or null when nothing is left. Since v3.22 its code is the same as the used card's when the customer keeps their code: compare the two to know whether a new code was issued
$contextarraySince v3.17: booking_id and customer_email, the email of the Amelia customer who made the booking (empty when unknown)
add_action( 'agc_gift_card_balance_updated', function ( $card, $used, $left, $new_card = null, $context = array() ) {
    wp_remote_post( 'https://example.com/api/balances', array(
        'timeout' => 15,
        'headers' => array( 'Content-Type' => 'application/json' ),
        'body'    => wp_json_encode( array(
            'code'      => $card['code'],
            'used'      => $used,
            'remaining' => $left,
            'new_code'  => $new_card ? $new_card['code'] : null,
            'booked_by' => isset( $context['customer_email'] ) ? $context['customer_email'] : '',
        ) ),
    ) );
}, 10, 5 );

The built-in email goes to the card's recipient; for a card with no recipient email, such as one handed over in person, to customer_email, or else to the buyer — unless Send it to the buyer when neither the recipient nor the customer who made the booking has an email address is unticked v3.23: then only an email that gives a new code falls back to the buyer. An email that gives a new code is always sent. When the booking uses up the whole balance, none is sent unless Also send it when the booking uses up the whole balance is ticked under Settings → Gift Card Balance. Callbacks written for three arguments keep working; register with 10, 5 to receive all five.

Do not throw. This runs on the commit path of the booking's database transaction. As with the hooks above, keep it quick and push anything slow onto wp_schedule_single_event().

A safety-net task re-checks balances every few minutes and repairs any redemption the live hook missed. It deliberately does not fire this action, so nobody gets emailed about a booking from weeks ago. If your integration would rather hear about those too, opt in with the agc_balance_catchup_send_usage_emails filter — return true and be aware the built-in email goes out with it.

agc_resolved_language (filter) v3.13

Decides which language a customer-facing text or email renders in. The plugin works it out on its own — the language stored on the gift card first, then Polylang, WPML, and finally the WordPress locale — so you only need this filter when your site decides language some other way.

add_filter( 'agc_resolved_language', function ( $language, $requested_locale ) {
    return 'bg';
}, 10, 2 );

Return one of en, fr, es, de, bg. Anything else is ignored and the plugin's own choice stands, so a typo degrades quietly instead of breaking an email.

agc_payment_providers (filter) v3.19

The payment methods the plugin knows, as an array of ID ⇒ class name: stripe, square, paypal, woocommerce, plus mollie, razorpay and barion, which are not offered yet (coming soon). A class you add must implement the plugin's payment gateway interface. To hide a method from buyers, prefer the next filter.

agc_payment_provider_availability (filter) v3.19

Decides whether a ticked method can be offered to buyers. It receives what the plugin found (available, reason, message, mode, currency…) and the method ID. Set available to false to hide a method from the purchase form, for example WooCommerce while Amelia's WooCommerce integration stays on for bookings. Payments already started still finish.

add_filter( 'agc_payment_provider_availability', function ( $availability, $id ) {
    if ( 'woocommerce' === $id ) {
        $availability['available'] = false;
    }
    return $availability;
}, 10, 2 );

agc_paypal_sdk_query_args (filter) v3.19

The query of the PayPal buttons script (client-id, currency, intent, components, disable-funding) and the mode (test or live). By default the buttons offer PayPal only, like Amelia's booking form: remove a value from disable-funding to show that option.

add_filter( 'agc_paypal_sdk_query_args', function ( $args, $mode ) {
    // Show the card button next to PayPal.
    $funding                 = array_diff( explode( ',', $args['disable-funding'] ), array( 'card' ) );
    $args['disable-funding'] = implode( ',', $funding );
    return $args;
}, 10, 2 );

agc_gateway_request_payload (filter) v3.19

The body sent to PayPal when a payment starts, with the method ID and the stored payment order. Use it to add a field the provider accepts. Do not change the amount, the currency or the order reference: the payment is checked against them before the gift card is issued.

agc_wc_should_issue_gift_card (filter) v3.19

Decides whether a WooCommerce order issues its gift cards now. It receives the plugin's decision, the order and what triggered the check (payment_complete, completed, status_changed or reconcile). Return true to issue on a status the default rule waits on, or false to wait until the order is completed.

agc_wc_gift_card_product_args (filter) v3.19

The hidden WooCommerce product used for gift cards, when the plugin creates it: name and tax_status (none by default, since a gift card is usually taxed when it is spent). Keep it untaxed unless the sale itself must be taxed: with prices entered without tax, buyers then pay the tax on top of the card's value; with prices entered with tax, a tax-exempt buyer pays less and gets no gift card. Diagnostics warns about a taxable product.

agc_stripe_excluded_payment_method_types (filter) v3.19

The Stripe payment methods left out of the gift card form, like in Amelia's booking form: the ones that confirm hours or days after checkout (sepa_debit, bacs_debit, us_bank_account, boleto, oxxo, konbini…). Return an empty array to offer every method enabled in your Stripe Dashboard; the gift card of a payment confirmed later is then issued by the webhook or the check of unfinished payments.

add_filter( 'agc_stripe_excluded_payment_method_types', function ( $types ) {
    // Offer SEPA Direct Debit again.
    return array_values( array_diff( $types, array( 'sepa_debit' ) ) );
} );

agc_wc_unpaid_processing_methods (filter) v3.19

The WooCommerce payment methods whose Processing status does not mean the order is paid: array( 'cod' ) by default (cash on delivery). Their gift cards are issued when the order is completed. Add the ID of any other offline method that moves orders to Processing before you are paid. It receives the list and the order.

agc_payment_start_rate_limit (filter) v3.19

How many payments one visitor (one IP address) can start in 10 minutes: 60 by default, 0 turns the limit off. Raise it if your site is behind a proxy or CDN that hides visitors' addresses, since they then all share one limit.

add_filter( 'agc_payment_start_rate_limit', function () {
    return 300;
} );

agc_payment_order_issued v3.19

Fires once a gift card has been issued for a PayPal or WooCommerce payment. It receives the payment order (order_ref, provider, amount_minor, currency…) and the card (gift_card_id, code). Stripe and Square payments do not go through an order: to act on every card, use agc_amelia_coupon_created.

add_action( 'agc_payment_order_issued', function ( $order, $card ) {
    error_log( sprintf( 'Gift card %s issued for %s payment %s', $card['code'], $order['provider'], $order['order_ref'] ) );
}, 10, 2 );

Email template filters

For when the Customize screens do not reach far enough. Each of these receives a $template_name — one of recipient, purchaser-confirmation or balance-update — so you can target a single email.

FilterDescription
agc_email_template_settingsThe resolved typography, layout, branding and section bundle, just before it reaches the template. Three arguments: the settings, the template name, the variables.
agc_email_template_sectionsThe ordered list of sections that will be rendered. Reorder, drop or add to it.
agc_email_template_section_htmlReplaces one section's markup outright. Four arguments: the HTML, the section id, the template name, the section config. Return null to keep the built-in one.
agc_email_template_custom_cssThe CSS injected into the email's style block, per template.
agc_template_pathThe absolute path of the template file about to be loaded — point it at a file in your own theme or plugin to replace an email wholesale.
add_filter( 'agc_email_template_section_html', function ( $html, $section_id, $template_name, $section ) {
    if ( 'balance' === $section_id && 'balance-update' === $template_name ) {
        return '<tr><td style="padding:20px;">' . esc_html__( 'Your own balance block', 'my-plugin' ) . '</td></tr>';
    }

    return $html;
}, 10, 4 );

These return markup that is emailed as-is, so escape anything that comes from a user. Email clients also ignore most modern CSS — stick to table layouts and inline styles, as the built-in templates do.

Purchase notification email

Not a hook, but often the simpler answer: under Settings → Delivery → Purchase notifications, switch on Notify me for every purchase to receive an email for every gift card sold, containing the code, the amount and the buyer's details. It is off by default. Physical gift cards always trigger it, since the code is never emailed to anyone else.

Common Issues

Gift Cards menu not visible

Ensure the Amelia Booking plugin is installed and activated. The Gift Cards plugin requires Amelia to function.

Payment errors

Emails not being received

Form not displaying

Diagnostics

The built-in diagnostics system (Gift Cards → Diagnostics) checks:

Each section gets a health score. Click on any failing check for remediation steps.

Debug Mode

Enable debug mode at Gift Cards → Settings → Advanced → Debug Mode.

When enabled, the plugin logs detailed information about:

Warning: Debug mode generates large log files. Only enable it for troubleshooting and disable it afterward.

FAQ

Can I use this without Amelia?

No. Gift Cards for Amelia is designed specifically to work with the Amelia Booking plugin. It creates Amelia coupons that are used during the booking process.

Is there a free version?

No. Gift Cards for Amelia is a premium plugin available for $39/year. This includes all features, 1 year of updates, and email support.

Can I use it on multiple sites?

Each license is for a single WordPress installation. Contact us for multi-site pricing.

What happens when a gift card is purchased?

  1. Customer pays with Stripe, Square, PayPal or your WooCommerce checkout
  2. Gift card record is created in the database
  3. A corresponding Amelia coupon is auto-created
  4. Recipient receives an email with the gift card code
  5. Buyer receives a confirmation email

How do recipients use their gift card?

Recipients enter their gift card code in the coupon/promo code field during the Amelia booking process. The discount is applied automatically based on the card's current balance. Since v3.0 the same code can be reused on subsequent bookings until the balance reaches zero, and the recipient receives a balance email after every redemption.