Need to Access Full Gift Card Codes for Physical Gift Card Fulfillment

Products and Orders APIs
1

Hi everyone,

I’m working with a client who wants to sell two types of gift cards:

  1. Electronic Gift Cards – standard Shopify gift cards, sent via email with the usual gift card number, optional message, and the ability to schedule delivery for a future date.
  2. Physical Gift Cards – for an additional $10, customers can provide their shipping address, and we’ll mail them a plastic gift card with the same code printed on it so they can gift it in person.

We’ve set this up using product variants — one for the digital version, and one for the physical version (with the added cost and shipping). The online sales flow works fine.

The problem:

Once the order is placed, we need to print the actual gift card number on the physical card before shipping it. However, in Shopify Admin, we can only see the last 4 digits of the code, the rest is hidden for security. Exporting gift card data also shows only the last 4 digits.

Our goal is to be able to:

  • Generate the codes via Shopify’s normal purchase flow
  • Access the full codes after purchase
  • Export them in bulk so we can print them on stickers and attach them to pre-designed plastic gift cards for shipping
  • Avoid manually writing codes or maintaining a separate code file outside Shopify

My questions:

  • Is there any way to retrieve the full gift card codes from Shopify after they are issued?
  • Can this be done through the Shopify API (Admin API / GraphQL / REST)?
  • Is there an approved workflow for businesses that need to issue physical cards tied to Shopify’s gift card system?

I’ve searched the forum but haven’t found any discussion that addresses this exact use case. Any guidance from the Shopify team or other developers would be greatly appreciated.

Thanks in advance!

1 Like
2

Hey @Selim_Gawad :waving_hand:, thanks for reaching out.

At the moment, we generally redact gift card codes after issuance, so it’s not easily possible retrieve the full code later via Admin, CSV export, REST, or GraphQL; only maskedCode and lastCharacters are exposed.

The main generally supported moment to capture the full code is at creation time using the Admin GraphQL giftCardCreate mutation, which returns a giftCardCode value once in the response.

Because of this, the recommended workflow is generally to keep your “Digital Gift Card” as a gift card product (Shopify auto-issues and emails), but make the “Physical Gift Card” a normal shippable product; when an order is paid, have an app issue the actual gift card via giftCardCreate, capture giftCardCode, and save it to an order or line item metafield for printing.

For example, when “Physical Gift Card – $100” is purchased, your app issues a $100 gift card, stores the returned code on the line item (e.g., a private metafield), and uses that value to print a sticker; you can optionally suppress sending the email so the first reveal is the mailed card.

For bulk printing, you could then query those metafields via the Admin GraphQL API or Bulk Operations to generate a CSV for your print run. Shopify POS also supports physical gift cards with pre-printed codes, and the online equivalent pattern is programmatic issuance at payment time so you can securely capture the code.

Does splitting the product (digital = gift card product, physical = normal product) work for you, or do you need them to remain variants of a single product?

Just wanted to confirm the above with you so I can suggest some more workarounds/solutions, but you should be able to add the write/read_gift_cards access scopes to your app to enable a decent workflow.

Hope this helps - let me know if I can clarify anything on our end :slight_smile:

3

Hi Alan, I found this answer facing a similar issue: We want to sell both printed and digital gift cards. Do we absolutely need to have a gift card product and a regular product with shipping in Shopify? My main concern is the difference in how Shopify treats those sales: While the gift card product (digital gift card) sale won’t be treated as revenue, the regular product (printed gift card) sale will be treated as revenue. This seems like an utterly unclean solution to me. Is there another way of handling this? Thank you

4

Hey @fabian :waving_hand:, great question, thanks for the ping.

I’m not super familiar with their processes, but I believe the standard QuickBooks/Xero integrations sync order and payment data, but they don’t automatically pull from Shopify’s gift card liability reports. So if you sell a physical gift card as a regular product for $110 ($100 value + $10 shipping), that full amount will sync to your accounting software as revenue, even though the giftCardCreate mutation properly tracks the $100 as a liability within Shopify’s Outstanding gift card balance report.

I did do a bit of digging into this though and I have a workaround that may work. The workaround requires a little bit of dev work, but it should help things stay clean for accounting. Essentially, you’d want to sell the physical gift card as a regular product at full price, and then use giftCardCreate to issue the gift card value (and attach the gift card number generated by Shopify to that “physical product” so Shopify tracks liability on its end), then periodically query your gift cards via the Admin GraphQL API (giftCards query with read_gift_cards scope) and push an adjusting entry to QuickBooks or Xero that debits Revenue and credits Gift Card Liability for the gift card portion when you see it decrement from use by the customer.

It’s wouldn’t be easily automated, but is possible since you’re essentially reclassifying the revenue after the fact, but I think this would be a fairly clean way to get proper accounting treatment currently. Let me know if you’d like more detail on this - happy to help! :slightly_smiling_face:

5

Hi Alan,

Thank you very much for your response!

This is helpful. We do not use QuickBooks/Xero, but a local (Swiss) accounting software called Bexio with a third-party Shopify integration. The integration works very well, but might handle some things in different ways than QuickBooks/Xero perhaps. Turns out that, as far as I understand, even gift card products sold in Shopify will sync to Bexio the same way as other orders = as revenue. We then move all the sold gift cards to a different account within Bexio. So accounting-wise, things should be fairly clear even if we were to use regular products instead of gift card products.

I’m fine doing simple dev work and I have extensively edited our theme, but I don’t have any experience creating Shopify apps. Maybe I need to get into this… I used to work as a web developer, but that was years ago and I’m way out of practice, even though I did continue to write various web code here and there every now and then.

Given the accounting side may not even be that big of an issue, we could now proceed with two separate products:

  • a gift card product for digital gift cards
  • a regular product for printed gift cards – and even issue these fully manually (therefore no need for a custom app)

However, even if accounting may be fine with this solution, analytics etc. in Shopify might be somewhat messed up and I think it would be cleaner to use either only regular products for gift cards or only gift card products – not both. Also not sure if tax could be handled correctly (0% tax rate on gift cards).

If we were to use a specific app for this, capturing the full gift card code at the time of creatio using the Admin GraphQL giftCardCreate mutation would still work if we were to use regular products for all gift cards sold. If the app would differentiate based on the variant (printed or digital gift card) chosen by the customer, it would also send it to them or send an email with the full code to our team, for example, so we could issue a printed gift card with this code. Does this make sense?

6

Hey @fabian, no worries! I think your instinct is correct here. Using the giftCardCreate mutation independently of gift card products definitely works, it’s designed for manual distribution and the gift card will be properly tracked in Shopify’s liability reports. When you call that mutation, Shopify creates a proper gift card tracked in the Outstanding gift card balance report as a liability, completely independent of how the product itself was sold. The gift card code is returned only at creation time, so you’d want to capture it right then and route it to your team for printing or directly to the customer for digital orders.

If you want to keep things simple and skip building an app, you could technically do this manually through the admin. When a printed gift card order comes in, just go to Products → Gift cards → Create gift card, set the value, add a note like “Order #1234”, and you’re done. If volume picks up later, a small app listening to the orders/paid webhook that fires off giftCardCreate would be pretty straightforward to build.

One thing to double-check is the tax setup on your regular product, I believe digital gift card products aren’t necessarily included as digital products in some jurisdiction when it comes to tax (more info here) but for a regular product you may need a tax override so you’re not charging VAT on what’s essentially a cash equivalent (I’m not a lawyer, so can’t confirm specific cases, but just wanted to mention this!). On the analytics side, going all-in on regular products plus the mutation for both digital and printed cards would at least keep things uniform, even if the revenue reports won’t perfectly reflect reality.

Here’s the mutation reference if you want to dig in: https://shopify.dev/docs/api/admin-graphql/latest/mutations/giftCardCreate and if you decide to build an app later, https://shopify.dev/docs/apps/build/scaffold-app is a good starting point. Let me know if you’d like me to walk through any of this in more detail!

7

Thank you, Alan, for confirming some of my assumptions and providing further information.

I believe this might be the way to go for now – even though revenue in analytics including gift card sales is not ideal. Now of course I could exclude this from reports, but I’d have to do this for every report and not forget about it when creating new reports etc. But I guess it’s a low ‘price’ to pay in exchange for a solid solution to the gift card issue – and much cleaner than handling digital gift cards one way and physical/printed ones another.

Thank you for the hint on the tax settings: That’s exactly what I meant. Gift cards are indeed sold excluding tax here, but it should be easy to create a tax override with 0% for each country we collect taxes in and add all gift card products to a collection.

One other approach came to my mind: I once read about physical gift cards with QR code or similar that can be charged when sold. Is this purely for Shopify POS? And if so, may there be a solution with a sort of fake POS location, e.g. using POS where orders are shipped only to load these physical, pre-printed (?) gift cards which are then shipped?

Thank you for the links to create this as an app. We may start handling this manually and then create an app for it eventually. I’d gladly circle back in case some questions may arise later on.

All the best,

Fabian

8

No worries @fabian !

Great question on the physical gift cards with QR codes, and yes, that feature is specifically designed for Shopify POS in-store sales. When you purchase physical gift cards from the Shopify Hardware Store, each card comes with a unique QR code that gets “activated” with a value during an in-person sale through the POS app. You can read more about how that works here: https://help.shopify.com/en/manual/sell-in-person/shopify-pos/payment-management/gift-cards/sell-gift-cards-pos

Unfortunately, the “fake POS location” idea may not work for online orders since there’s no mechanism in online checkout to scan or select a specific physical card, you’d still need manual intervention to bridge that gap.

That said, if you want pre-printed physical cards for online sales, I did a bit of digging into this and came up with a possible workaround. You could order cards from a third-party provider with custom SKUs printed on them, then pre-create those gift cards in Shopify using the giftCardCreate mutation. The gift card object has a note field that isn’t visible to customers but is searchable in the admin and via the API, so you can use it to track the physical card SKU and assignment status. When an order comes in, you’d use giftCardUpdate to update the note with the order number and shipment details.

Gift cards don’t support metafields directly, but the note field works well enough for this kind of inventory tracking. Here are the mutation references: https://shopify.dev/docs/api/admin-graphql/latest/mutations/giftCardCreate and https://shopify.dev/docs/api/admin-graphql/latest/mutations/giftCardUpdate

For lower volume though, I’d still recommend the simpler approach we discussed, regular products plus giftCardCreate at order time, then printing and shipping cards with the generated codes. But if having pre-printed branded cards with specific codes is important to your workflow, the pre-loaded approach is definitely viable. Let me know if you’d like me to walk through any of this in more detail!