Skip to Content
DocsGift card recipient flow

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 to someone else

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:

FieldLine-item propertyType
Toggle__shopify_send_gift_card_to_recipient”true” / unset
Recipient emailRecipient emailstring (validated)
Recipient nameRecipient namestring (max 255)
MessageMessagestring (max 200)
Send on dateSend onYYYY-MM-DD
Timezone offset__shopify_offsetminutes (auto-set)

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 to someone else.
  4. Fill in recipient email, name, message, and send-on date.
  5. Add to cart.

In the cart drawer, the line shows:

Gift card · $50 To: alex@example.com Send: 2026-06-15 “Happy graduation!”

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

Mercer relies on Shopify’s server-side validation for the recipient form. If a buyer submits with invalid input (bad email, send-on date out of range, etc.), the page reloads with:

  • The recipient toggle re-checked.
  • The fields re-shown with the buyer’s previously typed values.
  • A validation error message in red above the fields.

All reflected values are HTML-escaped to prevent XSS via the form drop. (This is one of Mercer’s hardened-form-drop 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 ‘See product details’ on my gift card”

That’s intentional. Quick-add is gated on gift cards because the recipient form requires a full PDP. 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

Custom LiquidFAQ