Gift card recipient flow

Mercer’s gift card PDPs include an opt-in recipient flow: the buyer can have the gift card emailed directly to a recipient on a chosen date with a personal message. This guide explains how the flow works from both the merchant and customer side, and how to configure it.

At a glance

When a customer is on a gift card PDP, the buy box shows a checkbox:

Send as a gift

When the customer checks the box, four fields appear:

• Recipient email
• Recipient name
• Message (up to 200 characters)
• Send on date (today through 90 days out)

On checkout, Shopify ships the gift card email to the recipient on the chosen date — at midnight in the buyer’s local timezone.

If the box is left unchecked (default), the gift card email goes to the buyer immediately on checkout, just like a standard purchase.

How it works under the hood

Mercer uses Shopify’s canonical line-item-property convention for gift card recipients:

Shopify reads these properties on cart submit and ships the gift card email to the recipient on the chosen date. The TZ offset is critical: without it, “Send on 2026-06-01” can drift up to 24 hours either way depending on where the buyer is. Mercer auto-populates __shopify_offset from new Date().getTimezoneOffset() client-side.

Merchant setup

There’s nothing to enable. The recipient form is automatically present on every PDP for products where product.gift_card? == true.

To make a product a gift card:

1. Shopify admin → Products → Add product.
2. Set the product type to Gift card.
3. Add gift card denominations as variants (e.g. $25, $50, $100, $200 — typically each at the same SKU prefix).
4. Save.

Mercer’s PDP detects the gift card product type and renders the recipient form. Quick-add is automatically gated on gift cards (buyers must go to the PDP to fill out the recipient form), so the collection grid quick-add modal won’t appear on gift cards.

Optional: Apple Wallet pass

If your gift card is configured to issue an Apple Wallet pass (Shopify exposes gift_card.pass_url on the gift_card template), Mercer’s gift card receipt template renders a Add to Apple Wallet button. No merchant action required; the button only appears when pass_url is non-blank.

Customer-facing flow

From the customer’s perspective:

1. Land on the gift card PDP.
2. Pick a denomination from the variant picker.
3. Optionally check Send as a gift.
4. Fill in recipient email, name, message, and send-on date.
5. Add to cart.

In the cart drawer, the line lists each stored line-item property verbatim as key: value pairs (the property keys are rendered as-is, not relabeled or quoted):

Gift card · $50 Recipient email: alex@example.com Recipient name: Alex Rivera Message: Happy graduation! Send on: 2026-06-15

Underscore-prefixed properties (__shopify_send_gift_card_to_recipient, __shopify_offset) and any blank-valued properties are hidden from this display.

The customer can edit or remove the line just like any other.

In the checkout, Shopify renders the same recipient line-item properties on the order summary. The buyer pays as usual.

After checkout:

• If the Send on date is today (or in the past — Shopify clamps to “now” if past), the recipient gets the gift card email immediately.
• If the date is in the future, Shopify queues the email for midnight in the buyer’s timezone on that date.

The buyer also receives an order confirmation containing the gift card code (in case the recipient never opens the email).

Validation behavior

Validation for the recipient form is client-side only, via native browser constraint validation. When the toggle is on, the recipient email field is marked required (gift-card-recipient.js toggles required in lockstep with the toggle), so the browser blocks add-to-cart and points at the empty field before anything is sent. Name, message, and send-on stay optional.

Add-to-cart on this theme is AJAX. There is no full-page reload on submit, and the {% form 'product' %} drop exposes no recipient field values, so:

• The toggle is not re-checked after a failed add — it starts unchecked.
• The fields are not repopulated with previously typed values — they render empty. (Value preservation across a buy-box re-render on variant change is handled separately in JS, not via server reflection.)
• There is no red server-side error banner above the fields for this form.

If a required property is still missing when the AJAX add fires (for example with JavaScript disabled), Shopify rejects /cart/add and the buyer sees a generic error toast.

The stored recipient values are HTML-escaped when they’re displayed — not on the form, but on the cart line, where each property value is output through {{ ... | escape }} (see cart-drawer-line.liquid and cart-line.liquid). That cart-line property display is one of Mercer’s hardened surfaces; see the security pass in the changelog.

Common gift card pitfalls

”The recipient form doesn’t appear on my gift card PDP”

Three things to check:

1. Is the product’s type set to Gift card in Shopify admin? Mercer reads product.gift_card? which only returns true for gift-card-type products.
2. Is the variant available (in stock, available to the active market)? An unavailable variant hides the buy box, including the recipient form.
3. Is templates/product.json the active template? If you’ve customized to use a different template for gift cards, you may have removed the recipient form.

”Quick add says ‘Choose options’ on my gift card”

That’s intentional. Quick-add is gated on gift cards because the recipient form requires a full PDP, so the quick-add control renders as a Choose options link (the products.product.quick_add_options locale string) to the PDP instead of an instant add button. Buyers click through to the PDP to fill in the recipient info.

”The send-on date snaps to today after the customer types”

Mercer’s date input has min="today" and max="today + 90 days". If the buyer types a date outside that range, the browser clamps it. This is intentional: Shopify won’t send dates more than 90 days out, and dates in the past trigger an immediate send.

”The recipient gets the email at the wrong time”

Mercer auto-populates __shopify_offset from the buyer’s browser timezone. If the buyer is in NYC (UTC-4 in summer) and picks 2026-06-15 as the send-on date, Shopify ships the email at 00:00 NYC time on June 15.

If the recipient is in a different timezone, they may receive it at an unexpected local time on their end. This is by design — the buyer picks “send on this date in my timezone”.

”The buyer’s gift card email arrives empty”

This is a Shopify-side issue, not Mercer’s. Check Shopify admin → Settings → Notifications → Gift card to confirm the email template is configured. Mercer doesn’t customize the email; it just populates the line-item properties.

What’s next

• Read FAQ for more gotchas.
• Read Section reference → Product and collection sections for general PDP composition.
• For changes to the gift card flow itself, contact support.