Documentation

Complete guide for installing, configuring, and using Gift Cards for Amelia (v2.0.0).

Requirements

• WordPress 5.0 or higher
• PHP 7.4 or higher
• Amelia Booking Plugin v9+ — any license (Starter, Standard, Pro, or Premium). Requires the Finance module (coupons).
• A Stripe or Square account — for payment processing
• SSL certificate — required for payments (HTTPS)

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 — go to Gift Cards → Types and create your first type
4. Add the form to a page — insert [agc_gift_card_form] on any page
5. Test a purchase — use test mode to verify everything works

Payment Setup

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

Square Setup

Square is also supported as a payment provider:

1. Go to Gift Cards → Settings → Payments
2. Select Square as your payment provider
3. Enter your Square Application ID and Access Token
4. Click Save & Verify to test the connection

General Settings

Navigate to Gift Cards → Settings → General to configure:

• Default Currency — auto-detected from your site, changeable
• Expiration Period — default 365 days, or tick Gift cards never expire to issue cards with no expiry date at all. Required where expiring gift cards are prohibited, such as Canada. The same choice is available per gift card type, which overrides this default.
• Code Format — prefix and pattern for gift card codes (e.g., GC-XXXXXXX)
• Suggested Amounts — pre-defined amounts shown in the purchase form (editable since v1.1)
• Custom Amounts — allow customers to enter any amount within a min/max range
• Hide exclusions on the form — keep the « Not valid for the following » list off the public form (still shown on the success page and confirmation email). Added in v1.4.

Text & Language Presets

Every label, button and message on the public form and emails is editable. Open Gift Cards → Settings → Text and either translate strings one by one, or apply a one-click language preset:

• English — default
• French — added in v1.2
• Spanish — added in v1.2
• German — added in v1.3
• Bulgarian — added in v3.13

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.

Email Settings

Configure email delivery at Gift Cards → Settings → Email:

• From Name — sender name for emails
• From Email — sender email address
• Reply-To Email — where replies go
• Enable/disable specific email types (purchase confirmation, recipient notification, etc.)

Advanced Settings

• Debug Mode — enable detailed logging for troubleshooting

Customize Menu

Gift Cards → Customize brings every visual setting in one place. The menu has two tabs: Visual Template for the public purchase form, and Mail for the recipient and purchaser emails. Both tabs offer a live preview that reflects your changes as you edit. New in v2.0

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.

• Duplicate / edit / delete templates without touching the originals
• Primary & secondary colors per template, with a live preview of the form
• Font — pick from 5 web-safe fonts (Arial, Georgia, Helvetica, Times New Roman, Verdana)
• Button style — 3D, Flat or Outline. Applied globally to step badges, amount selectors and action buttons.
• Visibility — disable templates you don't use to keep the gift card type selector tidy

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:

• Classic — serif heading, generous spacing, traditional look
• Minimal — sans-serif, tight spacing, thin colored band
• Bold — large header, heavy weight, prominent type

Typography

• Sizes in pixels — base, heading, code block
• Weights, line-height, letter-spacing
• Optional Google Fonts URL — paste a @import URL; web-safe fallbacks always render if a mail client blocks the font

Layout

• Drag-and-drop sections — reorder header, greeting, message, code, details, summary, restrictions, footer
• Per-section visibility — hide what you don't need
• Per-section spacing — fine-grained padding/margin control

Branding

• Logo upload — JPG/PNG up to 500 KB (200×80 px recommended)
• Free-form footer HTML — for legal mentions, contact info or seasonal offers
• Social links — Twitter / X, Facebook, Instagram, LinkedIn, YouTube, TikTok
• Custom CSS — for fine adjustments not covered by the controls above

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

HTML Email tab v3.13

When the visual controls are not enough, this tab lets you replace the email body 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.

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.

Send test sends the template of the sub-tab 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 → Types
2. Click Add New Type
3. Fill in the name, description, and select an email template
4. Configure amounts and restrictions
5. Save

Amounts & Pricing

For each type, you can configure:

• Suggested Amounts — pre-set buttons (e.g., $25, $50, $100, $200)
• Custom Amount — allow free-form entry with min/max limits
• Currency — override the default currency per type

Restrictions

Restrict gift cards to specific Amelia services:

• Services — limit to specific services
• Packages — limit to specific packages
• Events — limit to specific events

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:

• Spa & Wellness — calming greens
• Restaurant & Gastronomy — warm browns / oranges
• Beauty Salon — elegant pinks
• Fitness & Sport — energetic blues
• Health & Medical — professional teals
• Generic — versatile purples

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.

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

• Prominent code box with a working copy-to-clipboard button
• Structured summary table — amount, recipient, expiration, restrictions
• Themed personal message and restrictions blocks
• Coupon-pending banner if the Amelia coupon is still being created
• How-to-use instructions and next-steps preserved from previous versions

WordPress Shortcode

Add the gift card purchase form to any page or post:

[agc_gift_card_form]

With Parameters

[agc_gift_card_form
    title="Buy a Gift Card"
    description="Give the perfect gift"
    amounts="25,50,100,200"
    allow_custom="yes"
    min_amount="10"
    max_amount="500"
    currency="EUR"
    css_class="my-custom-class"
]

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

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 Stripe or Square checkout with 3D Secure support

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

Dashboard

The dashboard (Gift Cards → Dashboard) provides:

• Sales Overview — total revenue, number of cards sold, average value
• Transaction History — filterable list of all transactions
• Email Stats — delivery rates, open rates
• Quick Actions — create manual cards, export data

Rolling Balance

Since v3.0, every gift card issued by the plugin carries a rolling balance. Recipients reuse the same code across multiple Amelia bookings until the value is fully consumed — a behavior that native Amelia coupons do not provide.

How it works in practice

1. A customer buys a $100 gift card. The recipient gets a code with an initial balance of $100.
2. The recipient books a $30 service in Amelia, enters the code as a coupon. Amelia applies the full $30 discount.
3. The plugin records the redemption in its transaction ledger and updates the underlying Amelia coupon so the new available value is $70.
4. The recipient automatically receives an email showing Used: $30 / Remaining: $70.
5. Later, the recipient books a $50 event using the same code. Balance becomes $20, and another balance email is sent.
6. When the balance reaches $0, the coupon is closed.

Automatic balance email

After each redemption, the plugin sends a transactional email to the recipient summarizing what was just used and how much remains on the card. 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. Branded since v3.13

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. You can also turn the email off entirely under Settings → Gift Card Balance.

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.

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.

• GIFT CODE — the code your customers already hold. Required, and kept exactly as written, including its capitalisation.
• INITIAL VALUE — what the card was originally worth. Required. May carry a currency code or symbol (226.00 CAD, $150.00) and either decimal separator.
• REMAINING VALUE — what is still on the card. Leave it out and the card is imported unspent.
• USAGE — FULL, PARTIAL or DEPLETED. Used to mark a card as fully spent when there is no remaining-value column.
• PURCHASER EMAIL, RECIPIENT EMAIL, PURCHASER NAME, RECIPIENT NAME, PURCHASE DATE, LAST ACTIVITY, MESSAGE — all optional.

Import options

• Expiry — imported cards carry no expiry date by default, since they were sold under your previous system's terms. You can instead set a number of days from the import, or one fixed date for every card.
• Fully spent cards — off by default. Switch it on to import zero-balance cards too, so an old code presented at the counter is recognised as spent rather than reported as unknown.
• Gift card type — attach a type to apply its service, package and event restrictions to every imported card.
• Name when missing — used when your file has no name column.
• Emails — off by default, and worth leaving off: these people already received their card from your previous system.

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.

Logs

View all system activity at Gift Cards → Logs:

• Filter by action type, date range, user, or gift card
• View detailed log entries with timestamps
• Export logs in CSV format
• Log stats: total entries, entries by type, error rate

Shortcode Reference

[agc_gift_card_form]

Main purchase form with Stripe integration.

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.

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.

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_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.

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_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.

add_action( 'agc_gift_card_balance_updated', function ( $card, $used, $left ) {
    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,
        ) ),
    ) );
}, 10, 3 );

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.

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.

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

• Verify your Stripe or Square API keys are correct
• Ensure your site has an SSL certificate (HTTPS)
• Check that webhooks are configured
• Try enabling Test Mode first

Emails not being received

• Check your spam/junk folder
• Verify the "From Email" address in settings
• Test with the built-in email test tool: Gift Cards → Settings → Email → Send Test
• Consider using an SMTP plugin like WP Mail SMTP

Form not displaying

• Check for JavaScript errors in the browser console
• Ensure the shortcode is typed correctly: [agc_gift_card_form]
• Clear any caching plugins

Diagnostics

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

• System Requirements — PHP version, WordPress version, required extensions
• Plugin Dependencies — Amelia status, payment connection
• Database — table integrity, orphaned records
• Email — delivery capability, template integrity
• Performance — response times, cache status

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:

• Payment requests and responses
• Stripe and Square payment processing
• Email sending
• Coupon creation in Amelia

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 via Stripe or Square
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.