Skip to main content

Storefront Balance Checker

The Storefront Balance Checker lets your customers look up the remaining balance of a gift card directly on your online store. They enter the full gift card code and immediately see the balance, whether the card is still valid, and its expiry date.

It works for every gift card in your store, including cards purchased at checkout, cards created manually in the Shopify admin, and cards imported or created with this app.

Availability: Premium and Ultimate plans only.

Why Use It​

Shopify does not offer a public balance-check page. Customers who received a gift card outside a Shopify purchase, for example through a corporate gifting programme, a partner, or a printed card, have no way to see their balance other than starting a checkout. The balance checker closes that gap with a block you place on any page of your theme.

Adding the Block to Your Theme​

  1. Open the Datora Bulk Gift Cards app
  2. Navigate to Settings
  3. In the Storefront balance checker section, click Add block in theme editor
  4. The theme editor opens with the Gift card balance block added to your default page template in a new Apps section
  5. Move the block where you want it, adjust its settings (see below), and click Save

You can also add the block manually: in the theme editor, open any page template, click Add block or Add section, and choose Gift card balance under Apps.

tip

Create a dedicated page such as "Gift card balance" and add the block there. You can then print or share that page's URL with customers, for example on the gift card itself.

Customizing the Block​

All customization happens in the theme editor with a live preview. Select the block to see its settings, grouped as follows:

GroupSettings
ContentHeading, description, input placeholder, button label, hide the input label, show expiry date
LayoutAlignment (left or center), button next to or below the input, maximum width, inner padding, spacing
TypographyHeading size, text size, balance amount size (relative to your theme's font size)
StyleUse the theme's button style, show a border, border width, corner radius
ColoursBlock background, text, border, input background/text/border, button background/text, result background/text, error message
Theme editorShow a sample result while editing

Every colour is optional. Leave a colour empty and the block inherits it from your theme, so the block matches your store's look without any setup.

While you are in the theme editor, the block shows a sample balance result and a sample error message so you can style them. These samples never appear on your live store.

What Customers See​

  1. The customer enters the full gift card code. Spaces, dashes and lowercase letters are accepted.
  2. The block shows Remaining balance with the amount in the store currency, formatted for the customer's language.
  3. If the card has an expiry date and Show expiry date is enabled, the date is shown below the balance.
  4. Special cases show a message instead:
    • The card has no remaining balance
    • The card has expired (with the expiry date)
    • The card has been deactivated
    • No card was found with that code

Security​

The balance checker is designed so that it can never be used to discover other people's gift cards:

  • The full code is required. Entering only the last four characters, or any partial code, never returns a result. This is different from some other apps, which return card details for a last-four search.
  • Only the balance, status and expiry are shown. The customer's name, email address, order, internal notes and other details are never exposed.
  • Rate limiting. Lookups are limited per visitor and per store. Repeated attempts are rejected with a "Too many attempts" message.
  • Codes are never logged. The code is sent securely in the request body and is not written to any log.

Text and Translations​

The customer-facing texts in the block (labels, error messages and status messages) are provided by the app in English. The heading, description, placeholder and button label are yours to change in the block settings, so you can write them in your store's language.

For Developers: JavaScript API​

If you want to build your own balance form or trigger a balance check from your theme code, enable the Gift card balance API app embed:

  1. In the theme editor, open Theme settings (the sliders icon) and then App embeds
  2. Turn on Gift card balance API
  3. Click Save

The embed publishes window.DatoraGiftCards on every page of your storefront.

Check a balance from JavaScript​

const result = await DatoraGiftCards.checkBalance("XXXX XXXX XXXX XXXX");

if (result.ok && result.found) {
  console.log(result.formatted.balance); // "€25.00"
  console.log(result.status);            // "active" | "empty" | "expired" | "deactivated"
  console.log(result.formatted.expiresOn); // "December 31, 2027" or null
} else if (result.ok) {
  // No gift card with that code
} else {
  console.log(result.error); // "invalid_code" | "rate_limited" | "plan_required" | "unavailable" | "network"
}

checkBalance never throws. Check result.ok and result.found.

Use your own form without writing JavaScript​

Add data-datora-gift-card-balance to any form. The library wires it up automatically:

<form data-datora-gift-card-balance>
  <input name="code" autocomplete="off" autocapitalize="characters">
  <button type="submit">Check balance</button>
  <p data-datora-gift-card-balance-result></p>
</form>

While a lookup runs, the form receives the class is-loading. After a miss or an error it receives has-error. The result element is filled with a readable message.

Events​

After every lookup, the library dispatches a datora:giftcard:balance event on document with the result as event.detail. When the library is ready, it dispatches datora:giftcards:ready.

Helpers​

DatoraGiftCards.bind(form, options), normalizeCode, isValidCode, formatMoney(amount, currency), formatDate(isoDate) and messageFor(result) are available for custom integrations.

note

The Gift card balance block already includes the library. You only need the app embed when you build your own form or call the API on pages without the block.

Frequently Asked Questions​

Does the block work with my theme?​

The block works with any Online Store 2.0 theme that supports app blocks, which includes all themes in the Shopify Theme Store. It inherits your theme's fonts and colours by default.

Does it work on a password-protected store?​

Yes. Once a visitor has entered the storefront password, the balance checker works normally. This makes it easy to test before launch.

Can customers see who a gift card belongs to?​

No. The block only ever shows the balance, the status and the expiry date.

What happens if I downgrade my plan?​

The block stays in your theme but shows a "temporarily unavailable" message to customers. Remove the block from your theme or upgrade to Premium or Ultimate to restore it.

Does the balance checker count toward my monthly quota?​

No. Balance lookups do not create gift cards and do not use your quota.

Troubleshooting​

The block shows "temporarily unavailable"

  • Check that your store is on the Premium or Ultimate plan
  • If you just upgraded, open any page of the Datora app once so the new plan is picked up
  • Make sure the app proxy URL has not been changed under Settings > Apps and sales channels in your Shopify admin. The block expects the default path /apps/datora-gift-cards

Every lookup says the code was not found

  • The full code is required. The last four characters or a partial code never match
  • Check that the card exists under Products > Gift cards in your Shopify admin

"Too many attempts"

  • Wait one minute and try again. This protects your store from automated guessing

Next Steps​