Syntax
customer.metafields.lantern.wallet
Description
The wallet metafield contains all available rewards and store credit accounts for the customer in a single JSON object. This includes discount codes, gift cards, product rewards, and store credit balances. The data is automatically updated when rewards are earned, used, or expired.
The wallet metafield contains JSON data that must be parsed using Liquid’s parse_json filter before accessing individual properties.
Properties
Type: JSON Object
Namespace: lantern
Return Values
| Scenario | Value | Type |
|---|
| Logged in with rewards | Full wallet object | JSON Object |
| Logged in without rewards | {"items": [], "storeCreditAccounts": []} | JSON Object |
| Logged out | null | null |
Wallet Structure
The wallet object contains two main arrays:
items Array (Rewards)
Each reward item contains the following properties:
| Field | Type | Description |
|---|
id | string | Unique reward identifier |
resourceCode | string | Human-readable code (for example WELCOME20) |
rewardType | string | Type of reward offered to the customer (Discount Code, Gift Card, Product, Custom, Store Credit) |
value | number | Reward value (amount or percentage) |
valueType | "Percent" or "Amount" | Whether the value is a percentage or fixed amount |
balance | number | Remaining uses for this reward |
minOrderValue | number | Minimum order value required to use this reward |
endsAt | string or null | Expiration date in ISO format, or null for no expiration |
storeCreditAccounts Array
Each store credit account contains the following properties:
| Field | Type | Description |
|---|
id | string | Unique account identifier |
balance.amount | string | Available credit amount as a string |
balance.currencyCode | string | Currency code (USD, CAD, etc.) |
createdAt | string | Account creation date in ISO format |
updatedAt | string | Account last updated date in ISO format |
Examples
Basic Wallet Display
{% assign wallet_data = customer.metafields.lantern.wallet %}
{% if wallet_data %}
{% assign wallet = wallet_data | parse_json %}
<!-- Display available rewards -->
{% if wallet.items.size > 0 %}
<div class="rewards">
<h3>Available Rewards ({{ wallet.items.size }})</h3>
{% for item in wallet.items %}
<div class="reward-item">
<span class="reward-type">{{ item.rewardType }}</span>
{% if item.resourceCode %}
<code>{{ item.resourceCode }}</code>
{% endif %}
{% if item.valueType == 'Percent' %}
<span>{{ item.value }}% off</span>
{% else %}
<span>${{ item.value }} off</span>
{% endif %}
{% if item.endsAt %}
<small>Expires: {{ item.endsAt | date: '%B %d, %Y' }}</small>
{% endif %}
</div>
{% endfor %}
</div>
{% endif %}
<!-- Display store credit -->
{% if wallet.storeCreditAccounts.size > 0 %}
<div class="store-credit">
<h3>Store Credit</h3>
{% for account in wallet.storeCreditAccounts %}
<p>${{ account.balance.amount }} {{ account.balance.currencyCode }}</p>
{% endfor %}
</div>
{% endif %}
<!-- Empty state -->
{% if wallet.items.size == 0 and wallet.storeCreditAccounts.size == 0 %}
<p>No rewards available. Keep shopping to earn more!</p>
{% endif %}
{% endif %}
{% assign wallet_data = customer.metafields.lantern.wallet %}
{% if wallet_data %}
{% assign wallet = wallet_data | parse_json %}
{% assign reward_count = wallet.items.size %}
<!-- Calculate total store credit -->
{% assign total_credit = 0 %}
{% for account in wallet.storeCreditAccounts %}
{% assign credit = account.balance.amount | plus: 0 %}
{% assign total_credit = total_credit | plus: credit %}
{% endfor %}
<div class="wallet-summary">
<h4>Your Wallet</h4>
{% if reward_count > 0 %}
<span class="reward-count">
{{ reward_count }} reward{% unless reward_count == 1 %}s{% endunless %}
</span>
{% endif %}
{% if total_credit > 0 %}
<span class="credit-balance">
${{ total_credit }} store credit
</span>
{% endif %}
{% if reward_count == 0 and total_credit == 0 %}
<span class="empty-wallet">Earn rewards by shopping!</span>
{% endif %}
</div>
{% endif %}
