Skip to Content
DestinationGift-card converter

Gift-card converter

When you migrate a store’s gift cards, legacy codes that Shopify won’t accept (too long, or sharing common prefixes) are converted to a new 16-character code with the $giftcode transform. Customers hold the old printed card, so they need the new code to redeem at checkout.

The gift-card converter is a small storefront widget you add to the store for them: a customer pastes their old code and instantly gets the new one to enter at checkout. It runs entirely in the browser, makes no network requests, and needs no app or backend.

You only need this if the store’s gift cards were migrated using $giftcode. If the source codes were already Shopify-compatible and loaded unchanged, customers redeem with their existing code and no widget is required.

What the customer sees

A titled box with one field — “Old gift-card code” — that converts as they type and shows the new code with a Copy button. Nothing they type leaves their browser.

Add it to the store

Graftport hosts the script, so the entire integration is two lines. You don’t upload or maintain any file.

<script src="https://app.graftport.com/giftcard/graftport-giftcard.js" defer></script>
<div data-graftport-giftcard></div>

The script auto-initializes every [data-graftport-giftcard] element on the page. The easiest place to drop those two lines is a Custom Liquid block in the theme editor — no code editing required.

Create a page for it

In Shopify admin, go to Online Store → Pages → Add page. Title it something customers will find, e.g. “Redeem a migrated gift card”. Save.

Open the theme editor on that page

Go to Online Store → Themes → Customize. In the top bar, switch the view to the page you just created (Pages → Redeem a migrated gift card).

Add a Custom Liquid block

In the page’s content area, Add section (or Add block) → choose Custom Liquid. Paste the two lines above into it.

Save and preview

Save, then open the page on the storefront. Paste a test code such as 971020003000000001000310001000 — you should see it convert to IHWGWDJPI0JOE32R.

Use a Custom Liquid block or a theme file — not the page’s text editor. Pasting the two lines into the rich-text body of a page removes the <script> tag when you save, and you’ll see nothing at all on the storefront. If the converter doesn’t appear, this is almost always why.

Prefer editing theme code? The same two lines work in any template, section, or theme.liquid. You can also self-host the script instead of using the hosted URL — both are covered in the snippet’s README.

Link the page from wherever customers look for help — the store’s gift card / help page, order-status pages, or the migration announcement email.

If you’d rather not give the converter its own page — or want it reachable from everywhere — put a link in the footer, menu, or gift-card page and it opens the converter in a popup instead:

<script src="https://app.graftport.com/giftcard/graftport-giftcard.js" defer></script>
<a href="#" data-graftport-giftcard-open>Migrated gift card?</a>

The script still needs to load once on that page, but the link itself can be any element you like — a link, a button, a menu item. It accepts the same options as the embedded version, so you can set the heading and helper text on the link.

The popup closes with Escape, a click outside it, or its close button, and it’s keyboard-navigable throughout.

Options

Set these as attributes on the <div> to fit the store’s voice and flow:

AttributeDefaultPurpose
data-titleMigrated gift card?Heading text.
data-help(built-in)Explanatory line under the heading.
data-note(built-in)Small print below the field.
data-redeem-url(none)If set, shows a button linking here (e.g. /cart). Omit to hide it.
data-redeem-labelContinue to checkoutLabel for that button.
data-group4Group size for the displayed code (0 = no grouping). The copied value is always the raw 16 characters.
data-labelOld gift-card codeLabel above the field.
data-placeholdere.g. 9710 2000 3000 …Placeholder inside the field.
data-result-labelYour new codeLabel above the converted code.
data-copy-labelCopyLabel for the copy button.
data-copied-text(built-in)Confirmation shown after a successful copy.
data-copy-fail-text(built-in)Shown instead when the browser blocks copying.
data-close-labelCloseAccessible name for the popup’s close button. Popup links only.
<div
  data-graftport-giftcard
  data-title="Have an old gift card?"
  data-redeem-url="/cart"
  data-redeem-label="Go to checkout"
></div>

Rewriting or translating it

Every word the customer reads is on that list, so you can match the store’s voice or run the converter in another language without any code:

<div
  data-graftport-giftcard
  data-title="Carte cadeau migrée ?"
  data-label="Ancien code"
  data-result-label="Votre nouveau code"
  data-copy-label="Copier"
></div>

The converted code itself is always 16 characters of A–Z and 0–9, and is never translated. For a multi-language store, put the text in your translated strings and render them into these attributes.

Match the store’s styling

The widget ships neutral, with light and dark support. Override any CSS variable on the container to match the theme:

<style>
  [data-graftport-giftcard] {
    --gpgc-accent: #635bff;   /* buttons / focus ring */
    --gpgc-code:   #0f766e;   /* the new-code text */
    --gpgc-radius: 8px;
    --gpgc-font:   inherit;
  }
</style>

Good to know

  • Spent cards need no action. A card migrated with a zero balance has nothing to redeem — customers with a remaining balance are the only ones who need the new code.
  • The old code isn’t stored in the shop; only the derived new code is. Redemption uses the new code at checkout.
  • No customer data is collected. Conversion happens locally in the browser.
Last updated on
ShopifyOverview