Gift Card Balances

Customers who hold a Square gift card can see what is left on it without asking you. Add the Gift Cards tab to My Account, drop the [sws_gift_card_balance] shortcode wherever you like, or read the same data from a theme template.

Balances are read live from Square every few minutes, so a card spent at the counter this morning shows its real balance on the website this afternoon.

Requirements

• SquareSync for Woo Pro 10.3.5 or higher
• Enable Square Gift Cards switched on under WooCommerce → Settings → Payments → Square
• The customer must be logged in

Where a customer's cards come from

Square, on its own, only lists a gift card against a customer once something has linked the two — and a card bought on your website is not linked to the buyer. A store that asked Square alone would show almost every customer an empty page.

So three sources are searched and merged:

1. Linked to their Square customer record — cards bought at the POS, or attached to the customer by hand in the Square Dashboard.
2. Bought on this site — any gift card on one of their WooCommerce orders, including guest orders placed on the same email address before they registered.
3. Emailed to them — cards somebody else bought on your site and sent to their account's email address.

A card the customer bought and emailed to somebody else is deliberately not shown. The recipient holds that number, not the buyer.

Add the My Account tab

Go to WooCommerce → Settings → Payments → Square and tick Gift Cards in My Account. A "Gift Cards" tab appears in the customer's account area, listing each card with its balance, its status and its number.

Permalinks are refreshed automatically the first time you switch it on.

The shortcode

[sws_gift_card_balance]

Options:

Examples:

[sws_gift_card_balance format="table" show_code="reveal"]
[sws_gift_card_balance format="total" title="Your gift card credit"]
[sws_gift_card_balance state="active" hide_empty="true" show_code="none"]

Card numbers

A gift card number is a bearer credential — anybody who can read it can spend the card — so it is masked by default:

• masked — ••••••••••••9356
• reveal — masked, with a "Show number" toggle that needs no JavaScript. This is what the My Account tab uses.
• full — the number printed outright
• none — balances only

Spent and expired cards

Used-up and deactivated cards stay in the list by default, showing a $0.00 balance and a status of "No balance" or "Deactivated" — a customer looking for a card they cannot find needs to see that it is spent, not that it vanished. Each row also carries a sws-gift-card-spent or sws-gift-card-inactive class so a theme can dim them.

To list only spendable cards:

[sws_gift_card_balance state="active" hide_empty="true"]

format="total" always sums spendable money only, whatever is on screen.

From a theme template

// Every card the current customer holds.
$cards = sws_get_customer_gift_cards();
 
foreach ($cards as $card) {
    printf(
        '<li>%s — %s (%s)</li>',
        esc_html($card['gan_masked']),
        esc_html($card['balance_formatted']),
        esc_html($card['state'])
    );
}
 
// Or just the combined spendable balance, as a float in store currency.
$credit = sws_get_gift_card_balance();

Each card is an array with:

Both helpers only ever return the current customer's cards. Passing another user's id returns nothing unless the caller is a shop manager or administrator, so a template that reads a user id off the query string cannot be turned into a data leak.

Performance

Each customer's list is resolved once and cached for five minutes, so a My Account page render is not one Square request per card. The cache is dropped automatically when one of their orders completes, so a card they just bought appears straight away. If Square is unreachable the list comes back empty rather than holding the page open.

Filters

See the filters reference for sws_customer_gift_cards, sws_gift_card_balance_html, sws_gift_card_status_label, sws_gift_card_account_cache_ttl, sws_gift_card_account_include_gifted, sws_gift_card_account_include_received, sws_gift_card_account_order_limit, sws_gift_card_account_max_lookups, sws_gift_card_account_retry_budget, sws_gift_card_account_tab_shortcode, sws_gift_card_account_enabled and sws_gift_card_account_can_view.