At 09:00 on launch day, the old platform shows 4,218 active gift cards. The migration file contains 4,147 rows, several currencies, duplicate last-four values, and no reliable way to contact every person holding a physical card. Importing the file is not the decision. The decision is how the store will keep every valid customer promise redeemable exactly once.
Shopify treats gift cards as currency-like value. Cards are redeemable only in the store that issued them, Shopify does not natively transfer them between stores, and the standard export exposes only the final four code characters. A migration therefore needs a liability register, a route for each cohort, a controlled change window, and proof from real redemption paths before the old system closes.
Treat each balance as value, identity, and liability
A gift card row can represent prepaid customer funds, a no-payment goodwill issue, a refund, or a legacy store-credit balance. Those instruments may share a monetary amount while having different owners, expiry rules, accounting treatment, channels, and customer expectations. Converting them all into the same Shopify object can simplify the file while changing the promise.
| Source cohort | Promise to preserve | Main migration risk | Decision owner |
|---|---|---|---|
| Sold digital gift card | Remaining value, code access, currency, expiry | Wrong balance or duplicate redemption | Finance and ecommerce operations |
| Sold physical card | Card remains usable without known recipient identity | No safe reissue destination | Retail operations |
| Goodwill or promotion card | Approved value and eligibility | Unfunded or over-broad value | Support and finance |
| Refund credit | Value and refund trace | Broken link to the original transaction | Finance and support |
| Legacy store credit | Account-bound value and customer identity | Changing it into a bearer-style card | Finance, legal, and customer accounts |
Shopify distinguishes gift cards from customer store credit. Store credit is attached to a customer account and has its own permissions, currency, expiry, and B2B behavior. Do not convert one instrument into the other merely because both can fund a purchase. First document the commercial promise and obtain accounting or legal review for any change in expiry, transferability, tax treatment, or holder rights.
The migration control is simple to state: no cohort is ready until the team can name the value holder, source of truth, target instrument, redemption route, and closure evidence.
Build a currency-separated liability register
Start with one immutable source extract and retain its timestamp, row count, and file hash. Record balances in their issued currencies rather than converting them for convenience. A correct aggregate can conceal a missing high-value card, a duplicated small card, or an invalid currency route. Reconcile every cohort and currency independently.
| Register field | Why it matters | Acceptance rule |
|---|---|---|
| Source record ID and status | Prevents a row from being created twice | Unique, stable, and traceable to the extract |
| Issued and current balance | Separates original value from remaining liability | Non-negative and expressed in source currency |
| Full-code availability | Determines preserve, reissue, or coexistence route | Never inferred from masked data |
| Purchaser, recipient, or holder path | Determines safe delivery and support lookup | Known, unknown, or intentionally unassigned |
| Target object and target ID | Creates an auditable source-to-target map | One approved target per eligible source record |
| Exception code and owner | Keeps mismatches out of silent manual fixes | Named owner, action, due point, and evidence |
Full codes need stricter custody than ordinary migration columns. Limit access, avoid pasting them into tickets or general spreadsheets, encrypt files at rest and in transfer, and remove temporary copies after the approved retention point. Shopify returns a created code at creation time, then masks it in ordinary administration. The mapping and customer-delivery design must be decided before a batch is created.
Choose one migration route for each cohort
Shopify's current GraphQL Admin API can create a gift card with an optional code, specified value, expiry, customer, recipient, and note. That capability does not make code preservation the default. The source must provide the full code, the code format and uniqueness must pass a target test, the app needs the correct gift-card scope, and the security team must approve how codes are handled.
| Route | Use when | Control | Rollback or exit |
|---|---|---|---|
| Preserve code | The full source code is available and target creation accepts it | Pilot collisions, balance, expiry, currency, and both channels | Stop the batch before source deactivation |
| Reissue new code | A reachable holder can receive a replacement securely | Map old record to new ID, control notification, and prevent double use | Pause delivery and keep the old card redeemable |
| Temporary coexistence | Physical cards or unknown holders cannot be reissued safely | Validate old card in the source, then honor it through a controlled support or POS path | Extend the source window while exceptions resolve |
| Manual exception | A record is disputed, malformed, expired, or legally sensitive | Quarantine it with a named finance or legal decision | No target value until approval is recorded |
Do not treat the last four characters as a unique customer key. Different codes can share the same suffix, and physical cards are often held by someone other than the purchaser. If only masked data survives, the safer route is usually controlled reissue to a verified holder or temporary coexistence, not guessing the missing code or automatically attaching value to the purchaser account.
Freeze writes, create value, then replay the delta
A long migration can be wrong even when every imported row matches its original export. Customers may redeem cards, staff may issue refunds, and support may create new value after the extract. Set a source watermark, define which system accepts writes during each phase, and record every later credit, debit, issue, expiry edit, cancellation, and reactivation decision as a delta.
- Approve cohorts, route rules, code custody, notification policy, exception owners, and per-currency acceptance totals.
- Take the source snapshot, record the exact watermark, and begin a write-ahead delta log for every later balance event.
- Create a small target pilot without notifying customers; save source-to-target IDs and every returned user error.
- Reconcile pilot balances and test redemption before expanding in bounded batches with a stop threshold.
- Replay the delta through idempotent operations so the same event cannot change a target balance twice.
- Open the approved target route, monitor both systems, resolve exceptions, then close the source only after sign-off.
Reconcile this invariant separately for every currency and cohort: eligible source liability after the final delta equals verified target liability plus approved source-retained liability plus documented exceptions.
Prove redemption behavior, not record creation
A successful API response proves that Shopify accepted a record. It does not prove that the intended holder received the code, the card is redeemable in the intended market, the POS recognizes it, a partial redemption leaves the right balance, or a refund returns value correctly. Use a controlled test cohort and inspect both customer behavior and finance records.
| Test | Expected evidence | Stop condition |
|---|---|---|
| Online full redemption | Correct card accepted once and order records the payment | Wrong currency, rejection, or remaining balance |
| Partial and mixed tender | Residual balance and other payment allocation agree | Negative, rounded, or unexplained residual |
| Shopify POS redemption | Same approved cohort works at intended retail locations | Channel mismatch or staff workaround |
| Refund after redemption | Value returns through the approved instrument and amount | New untracked liability or blocked reload |
| Duplicate event replay | Second delivery produces no second credit or debit | Balance changes twice |
| Customer support lookup | Staff can resolve a holder with permitted evidence | Full-code exposure or ambiguous match |
Include expiry and deactivation edge cases. Shopify documents deactivation as permanent, and a deactivated card cannot be re-enabled or reloaded. A refund may also behave differently depending on the payment route. These are reasons to test exact journeys with finance and support, not to generalize from one successful purchase.
Close the old system only with a signed liability receipt
The source can close when the team can explain every eligible record, every balance delta, every target object, every retained balance, and every exception. Keep the receipt versioned with the source and target timestamps, counts, balance totals, currency, batch IDs, test evidence, owners, and approval. This is the evidence finance and support will need when a holder returns months later.
- ✓Every eligible source record has one approved target, retained-source, or exception state.
- ✓Counts and balances reconcile independently for each currency, cohort, and status.
- ✓Post-snapshot events were replayed once and the delta log is closed at a named watermark.
- ✓Online, POS, partial redemption, refund, duplicate replay, and support journeys passed.
- ✓Customer communications match the chosen route and expose no full codes outside the approved channel.
- ✓Finance, ecommerce operations, retail, support, and the migration owner signed the closure receipt.
Start this week with a read-only source extract and a ten-record cohort sample: one active digital card, one partially redeemed card, one physical card, one refund balance, one goodwill issue, one expired record, one deactivated record, one unknown holder, and two currencies if the store uses them. Do not create target value yet. Success is a complete route and evidence rule for each record. Stop if code custody, currency, holder identity, or liability ownership remains unclear.
Frequently asked questions
Can gift cards be transferred directly from another platform to Shopify?
Can we keep the same gift card codes during a Shopify migration?
What if the old platform exports only the last four code characters?
Should legacy store credit become a Shopify gift card?
When should customers be notified about replacement gift cards?
How long should the old gift card system remain available?
Sources
- Shopify Help Center: Migrate to Shopify, accessed September 8, 2026
- Shopify Help Center: Gift cards considerations and overview, accessed September 8, 2026
- Shopify Help Center: Managing created gift cards, accessed September 8, 2026
- Shopify Help Center: Store credit, accessed September 8, 2026
- Shopify Admin GraphQL API: giftCardCreate, version 2026-07, accessed September 8, 2026
- Shopify Admin GraphQL API: GiftCard object, version 2026-07, accessed September 8, 2026
- Shopify developer changelog: Local currency support for gift cards, accessed September 8, 2026
- Shopify Gift Card and Store Credit Service Terms, accessed September 8, 2026
