> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lantern.is/llms.txt
> Use this file to discover all available pages before exploring further.

# wallet

> Access customer rewards and store credit balances in a comprehensive JSON object.

## Syntax

<Tabs>
  <Tab title="Liquid">
    ```liquid theme={null}
    customer.metafields.lantern.wallet
    ```
  </Tab>
</Tabs>

## 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.

<Info>
  The wallet metafield contains JSON data that must be parsed using Liquid's `parse_json` filter before accessing individual properties.
</Info>

## 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

```liquid theme={null}
{% 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 %}
```

### Wallet Summary Widget

```liquid theme={null}
{% 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 %}
```