Choose a version:

Gift cards

Gift card details pages display balance, status, expiration dates, and transaction history for individual gift cards. Extensions on these pages help merchants manage gift card workflows, track usage patterns, and integrate with external loyalty or CRM systems.

Anchor to Use casesUse cases

Balance adjustments: Add or deduct gift card balances with custom approval workflows and audit logging.
Fraud detection: Display risk indicators and suspicious activity alerts based on gift card usage patterns and transaction history.
Loyalty integration: Connect gift cards to external loyalty programs, enabling point conversions and reward redemptions.
Expiration management: Help merchants extend expiration dates or send reminder notifications to customers before gift cards expire.
Transaction history export: Export detailed gift card transaction records for accounting and compliance purposes.

Shopify admin gift card pages showing all available extension target locations.

Anchor to Gift cards targetsGift cards targets

Use action and block targets to extend the gift cards details page with workflows and contextual information. Action targets open as modal overlays from the More actions menu, while block targets display as inline cards.

Extensions can query and mutate Shopify data using the direct API, or call your app's backend for custom business logic and external integrations.

Anchor to Gift card details action ,[object Object]Gift card details action target

admin.gift-card-details.action.render

Renders an admin action extension on the gift card details page. Merchants can access this extension from the More actions menu. Use this target to provide workflows that operate on gift card data, such as syncing with external systems, exporting gift card information, or managing credit terms.

Extensions at this target can access gift card data through the data property in the Action Extension API. The action renders in a modal overlay, providing space for multi-step workflows, forms, and confirmations.

Support

Components (45)

APIs (1)

Examples

jsx

import {render} from 'preact';

import {useState} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

const Extension = () => {

const [loading, setLoading] = useState(false);

const [success, setSuccess] = useState(false);

const [error, setError] = useState(null);

const [includeTransactions, setIncludeTransactions] = useState(true);

const [includeCustomer, setIncludeCustomer] = useState(true);

const handleExport = async () => {

setLoading(true);

setError(null);

const giftCardId = shopify.data.selected[0].id;

try {

const response = await fetch('https://your-app.com/api/gift-cards/export', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({

giftCardId,

includeTransactions,

includeCustomer,

}),

});

if (response.ok) {

const {downloadUrl} = await response.json();

setSuccess(true);

window.open(downloadUrl, '_blank');

shopify.close();

} else {

const {message} = await response.json();

setError(message || 'Export failed');

}

} catch (err) {

setError('Failed to connect to export service');

} finally {

setLoading(false);

}

};

return (

<s-admin-action heading="Export Gift Card to CSV">

<s-stack direction="block" gap="base">

{success && (

<s-banner tone="success" dismissible={false}>

CSV exported! Download starting...

</s-banner>

)}

{error && (

<s-banner tone="critical" dismissible={false}>

{error}

</s-banner>

)}

<s-section heading="Export Options">

<s-stack direction="block" gap="small">

<s-checkbox

label="Include transaction history"

checked={includeTransactions}

onChange={(e) => setIncludeTransactions(e.currentTarget.checked)}

/>

<s-checkbox

label="Include customer details"

checked={includeCustomer}

onChange={(e) => setIncludeCustomer(e.currentTarget.checked)}

/>

</s-stack>

</s-section>

<s-text color="subdued">

Export includes gift card balance, status, and selected details.

</s-text>

<s-button-group>

<s-button

variant="primary"

onClick={handleExport}

disabled={loading || success}

>

{loading ? 'Exporting...' : 'Export CSV'}

</s-button>

<s-button onClick={() => shopify.close()}>Cancel</s-button>

</s-button-group>

</s-stack>

</s-admin-action>

);

};

Examples

Description

Add an action extension that exports gift card details to a CSV file using your app backend. This example demonstrates calling an external API endpoint to generate and download gift card transaction history.

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [loading, setLoading] = useState(false);
  const [success, setSuccess] = useState(false);
  const [error, setError] = useState(null);
  const [includeTransactions, setIncludeTransactions] = useState(true);
  const [includeCustomer, setIncludeCustomer] = useState(true);

  const handleExport = async () => {
    setLoading(true);
    setError(null);
    const giftCardId = shopify.data.selected[0].id;

    try {
      const response = await fetch('https://your-app.com/api/gift-cards/export', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          giftCardId,
          includeTransactions,
          includeCustomer,
        }),
      });

      if (response.ok) {
        const {downloadUrl} = await response.json();
        setSuccess(true);
        window.open(downloadUrl, '_blank');
        shopify.close();
      } else {
        const {message} = await response.json();
        setError(message || 'Export failed');
      }
    } catch (err) {
      setError('Failed to connect to export service');
    } finally {
      setLoading(false);
    }
  };

  return (
    <s-admin-action heading="Export Gift Card to CSV">
      <s-stack direction="block" gap="base">
        {success && (
          <s-banner tone="success" dismissible={false}>
            CSV exported! Download starting...
          </s-banner>
        )}
        {error && (
          <s-banner tone="critical" dismissible={false}>
            {error}
          </s-banner>
        )}

        <s-section heading="Export Options">
          <s-stack direction="block" gap="small">
            <s-checkbox
              label="Include transaction history"
              checked={includeTransactions}
              onChange={(e) => setIncludeTransactions(e.currentTarget.checked)}
            />
            <s-checkbox
              label="Include customer details"
              checked={includeCustomer}
              onChange={(e) => setIncludeCustomer(e.currentTarget.checked)}
            />
          </s-stack>
        </s-section>

        <s-text color="subdued">
          Export includes gift card balance, status, and selected details.
        </s-text>

        <s-button-group>
          <s-button
            variant="primary"
            onClick={handleExport}
            disabled={loading || success}
          >
            {loading ? 'Exporting...' : 'Export CSV'}
          </s-button>
          <s-button onClick={() => shopify.close()}>Cancel</s-button>
        </s-button-group>
      </s-stack>
    </s-admin-action>
  );
};

Description

Add an action extension that syncs gift card details to an external loyalty platform using the [direct API](/docs/api/admin-extensions/2025-10#direct-api-access). This example demonstrates fetching gift card data and pushing it to an external system.

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [loading, setLoading] = useState(false);
  const [success, setSuccess] = useState(false);
  const [error, setError] = useState(null);
  const [includeTransactions, setIncludeTransactions] = useState(true);
  const [syncNotes, setSyncNotes] = useState(true);

  const handleSync = async () => {
    setLoading(true);
    setError(null);
    const giftCardId = shopify.data.selected[0].id;

    try {
      const response = await fetch('shopify:admin/api/graphql.json', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          query: `query GetGiftCard($id: ID!) {
            giftCard(id: $id) {
              id
              balance { amount currencyCode }
              initialValue { amount currencyCode }
              lastCharacters
              expiresOn
              createdAt
              customer { id email displayName }
            }
          }`,
          variables: {id: giftCardId},
        }),
      });

      const {data} = await response.json();
      
      if (data?.giftCard) {
        // Sync to external loyalty platform
        await fetch('https://your-loyalty-platform.com/api/gift-cards/sync', {
          method: 'POST',
          headers: {'Content-Type': 'application/json'},
          body: JSON.stringify({
            giftCard: data.giftCard,
            includeTransactions,
            syncNotes,
          }),
        });
        setSuccess(true);
        shopify.close();
      } else {
        setError('Gift card not found');
      }
    } catch (err) {
      setError('Failed to sync gift card');
    } finally {
      setLoading(false);
    }
  };

  return (
    <s-admin-action heading="Sync to Loyalty Platform">
      <s-stack direction="block" gap="base">
        {success && (
          <s-banner tone="success" dismissible={false}>
            Gift card synced to loyalty platform!
          </s-banner>
        )}
        {error && (
          <s-banner tone="critical" dismissible={false}>{error}</s-banner>
        )}

        <s-text>
          Sync this gift card's details to your external loyalty platform for unified tracking.
        </s-text>

        <s-section heading="Sync Options">
          <s-stack direction="block" gap="small">
            <s-checkbox
              label="Include transaction history"
              checked={includeTransactions}
              onChange={(e) => setIncludeTransactions(e.currentTarget.checked)}
            />
            <s-checkbox
              label="Sync internal notes"
              checked={syncNotes}
              onChange={(e) => setSyncNotes(e.currentTarget.checked)}
            />
          </s-stack>
        </s-section>

        <s-button-group>
          <s-button variant="primary" onClick={handleSync} disabled={loading || success}>
            {loading ? 'Syncing...' : 'Sync Gift Card'}
          </s-button>
          <s-button onClick={() => shopify.close()}>Cancel</s-button>
        </s-button-group>
      </s-stack>
    </s-admin-action>
  );
};

Anchor to Gift card details action (should render) ,[object Object]Gift card details action (should render) target

admin.gift-card-details.action.should-render

Controls the render state of an admin action extension on the gift card details page. Use this target to conditionally show or hide your action extension based on the gift card's properties, such as status, configuration, or specific business requirements.

This target returns a boolean value that determines whether the corresponding action extension appears in the More actions menu. The extension evaluates each time the page loads.

Support

Components (0)

APIs (1)

Supported components

-

Available APIs

Should Render API

Examples

jsx

export default async () => {

const giftCardId = shopify.data.selected[0].id;

try {

// Check if your external system has analytics data for this gift card

const response = await fetch('https://your-app.com/api/gift-card-analytics/check', {

method: 'POST',

headers: {

'Content-Type': 'application/json',

},

body: JSON.stringify({

giftCardId,

checkType: 'has_analytics_data',

}),

});

if (!response.ok) {

console.error('Analytics check failed:', response.status);

return { display: false };

}

const result = await response.json();

// Show action only if external analytics data exists for this gift card

return { display: result.hasAnalyticsData && result.dataPointsCount > 0 };

} catch (err) {

console.error('Error checking gift card analytics:', err);

return { display: false };

}

};

Examples

Description

Add a should-render check that calls your app backend to determine if external analytics data exists for this gift card before showing the action.

jsx

export default async () => {
  const giftCardId = shopify.data.selected[0].id;

  try {
    // Check if your external system has analytics data for this gift card
    const response = await fetch('https://your-app.com/api/gift-card-analytics/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        giftCardId,
        checkType: 'has_analytics_data',
      }),
    });

    if (!response.ok) {
      console.error('Analytics check failed:', response.status);
      return { display: false };
    }

    const result = await response.json();

    // Show action only if external analytics data exists for this gift card
    return { display: result.hasAnalyticsData && result.dataPointsCount > 0 };
  } catch (err) {
    console.error('Error checking gift card analytics:', err);
    return { display: false };
  }
};

Description

Add an action extension that conditionally displays a status dashboard action only for gift cards with a balance above a threshold, using the GraphQL Admin API to check the gift card's current balance.

jsx

export default async () => {
  const giftCardId = shopify.data.selected[0].id;
  const HIGH_VALUE_THRESHOLD = 100;

  try {
    const response = await fetch('shopify:admin/api/graphql.json', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        query: `query GetGiftCardBalance($id: ID!) {
          giftCard(id: $id) {
            balance {
              amount
              currencyCode
            }
            enabled
          }
        }`,
        variables: { id: giftCardId },
      }),
    });

    const { data } = await response.json();
    
    if (!data?.giftCard) {
      return { display: false };
    }

    const balance = parseFloat(data.giftCard.balance.amount);
    const isEnabled = data.giftCard.enabled;
    const isHighValue = balance >= HIGH_VALUE_THRESHOLD;

    // Show dashboard action only for enabled high-value gift cards
    return { display: isEnabled && isHighValue };
  } catch (err) {
    console.error('Failed to check gift card balance:', err);
    return { display: false };
  }
};

Anchor to Gift card details block ,[object Object]Gift card details block target

admin.gift-card-details.block.render

Renders an admin block extension inline on the gift card details page. Use this target to display contextual information, analytics, or status updates related to the gift card without requiring merchant interaction to open a modal.

Extensions at this target can access gift card data through the data property in the Block Extension API. Blocks appear as cards on the page and can show real-time data, insights, or quick actions, providing persistent visibility for information merchants need to see at a glance.

Support

Components (46)

APIs (1)

Examples

jsx

import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

const Extension = () => {

const [loading, setLoading] = useState(true);

const [error, setError] = useState(false);

const [externalData, setExternalData] = useState(null);

useEffect(() => {

fetchExternalData();

}, []);

const fetchExternalData = async () => {

setLoading(true);

setError(false);

const giftCardId = shopify.data.selected[0].id;

try {

const response = await fetch('https://your-app.com/api/gift-card/external-data', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({giftCardId}),

});

if (response.ok) {

const data = await response.json();

setExternalData(data);

} else {

setError(true);

}

} catch (err) {

setError(true);

} finally {

setLoading(false);

}

};

if (loading) {

return (

<s-admin-block heading="Loyalty System Data">

<s-stack direction="block" gap="base">

<s-spinner />

<s-text color="subdued">Loading external data...</s-text>

</s-stack>

</s-admin-block>

);

}

if (error) {

return (

<s-admin-block heading="Loyalty System Data">

<s-banner tone="critical" dismissible={false}>

Failed to load external data.

</s-banner>

<s-button onClick={fetchExternalData}>Retry</s-button>

</s-admin-block>

);

}

return (

<s-admin-block heading="Loyalty System Data">

<s-stack direction="block" gap="base">

<s-section heading="External Balance">

<s-stack direction="inline" gap="base">

<s-text>Loyalty Points Earned:</s-text>

<s-badge tone="success">{externalData?.loyaltyPoints || 0} pts</s-badge>

</s-stack>

</s-section>

<s-divider />

<s-section heading="Usage History">

<s-stack direction="block" gap="small">

<s-text color="subdued">Last used: {externalData?.lastUsed || 'Never'}</s-text>

<s-text color="subdued">Total transactions: {externalData?.transactionCount || 0}</s-text>

<s-text color="subdued">Linked customer: {externalData?.customerEmail || 'None'}</s-text>

</s-stack>

</s-section>

<s-link href={`https://your-app.com/dashboard/gift-cards/${shopify.data.selected[0].id}`}>

View full history in dashboard →

</s-link>

</s-stack>

</s-admin-block>

);

};

Examples

Description

Create a block extension that displays gift card usage history and balance information from an external loyalty system, demonstrating how to fetch and display data from your app backend.

jsx


import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(false);
  const [externalData, setExternalData] = useState(null);

  useEffect(() => {
    fetchExternalData();
  }, []);

  const fetchExternalData = async () => {
    setLoading(true);
    setError(false);
    const giftCardId = shopify.data.selected[0].id;

    try {
      const response = await fetch('https://your-app.com/api/gift-card/external-data', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({giftCardId}),
      });

      if (response.ok) {
        const data = await response.json();
        setExternalData(data);
      } else {
        setError(true);
      }
    } catch (err) {
      setError(true);
    } finally {
      setLoading(false);
    }
  };

  if (loading) {
    return (
      <s-admin-block heading="Loyalty System Data">
        <s-stack direction="block" gap="base">
          <s-spinner />
          <s-text color="subdued">Loading external data...</s-text>
        </s-stack>
      </s-admin-block>
    );
  }

  if (error) {
    return (
      <s-admin-block heading="Loyalty System Data">
        <s-banner tone="critical" dismissible={false}>
          Failed to load external data.
        </s-banner>
        <s-button onClick={fetchExternalData}>Retry</s-button>
      </s-admin-block>
    );
  }

  return (
    <s-admin-block heading="Loyalty System Data">
      <s-stack direction="block" gap="base">
        <s-section heading="External Balance">
          <s-stack direction="inline" gap="base">
            <s-text>Loyalty Points Earned:</s-text>
            <s-badge tone="success">{externalData?.loyaltyPoints || 0} pts</s-badge>
          </s-stack>
        </s-section>

        <s-divider />

        <s-section heading="Usage History">
          <s-stack direction="block" gap="small">
            <s-text color="subdued">Last used: {externalData?.lastUsed || 'Never'}</s-text>
            <s-text color="subdued">Total transactions: {externalData?.transactionCount || 0}</s-text>
            <s-text color="subdued">Linked customer: {externalData?.customerEmail || 'None'}</s-text>
          </s-stack>
        </s-section>

        <s-link href={`https://your-app.com/dashboard/gift-cards/${shopify.data.selected[0].id}`}>
          View full history in dashboard →
        </s-link>
      </s-stack>
    </s-admin-block>
  );
};

Description

Create a block extension that displays gift card metrics and status information. This example demonstrates fetching gift card details using the [direct API](/docs/api/admin-extensions/2025-10#direct-api-access) and presenting key data in a dashboard format.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [loading, setLoading] = useState(true);
  const [giftCard, setGiftCard] = useState(null);
  const [error, setError] = useState(false);

  useEffect(() => {
    fetchGiftCardDetails();
  }, []);

  const fetchGiftCardDetails = async () => {
    try {
      const response = await fetch('shopify:admin/api/graphql.json', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          query: `query GetGiftCard($id: ID!) {
            giftCard(id: $id) {
              id
              balance { amount currencyCode }
              initialValue { amount currencyCode }
              enabled
              expiresOn
              createdAt
              customer { displayName }
            }
          }`,
          variables: {id: shopify.data.selected[0].id},
        }),
      });
      const {data} = await response.json();
      setGiftCard(data.giftCard);
    } catch (err) {
      setError(true);
    } finally {
      setLoading(false);
    }
  };

  if (loading) {
    return (
      <s-admin-block heading="Gift Card Dashboard">
        <s-box padding="base"><s-spinner /></s-box>
      </s-admin-block>
    );
  }

  if (error || !giftCard) {
    return (
      <s-admin-block heading="Gift Card Dashboard">
        <s-banner tone="critical" dismissible={false}>
          Unable to load gift card details.
        </s-banner>
      </s-admin-block>
    );
  }

  const usedAmount = (parseFloat(giftCard.initialValue.amount) - parseFloat(giftCard.balance.amount)).toFixed(2);
  const usagePercent = ((usedAmount / parseFloat(giftCard.initialValue.amount)) * 100).toFixed(0);

  return (
    <s-admin-block heading="Gift Card Dashboard">
      <s-stack direction="block" gap="base">
        <s-stack direction="inline" gap="base">
          <s-badge tone={giftCard.enabled ? 'success' : 'critical'}>
            {giftCard.enabled ? 'Active' : 'Disabled'}
          </s-badge>
          {giftCard.expiresOn && (
            <s-badge tone="warning">Expires: {giftCard.expiresOn}</s-badge>
          )}
        </s-stack>

        <s-section heading="Balance Overview">
          <s-stack direction="block" gap="small">
            <s-text>Initial Value: {giftCard.initialValue.amount} {giftCard.initialValue.currencyCode}</s-text>
            <s-text>Current Balance: {giftCard.balance.amount} {giftCard.balance.currencyCode}</s-text>
            <s-text color="subdued">Used: {usedAmount} ({usagePercent}% redeemed)</s-text>
          </s-stack>
        </s-section>

        <s-divider />

        <s-section heading="Details">
          <s-stack direction="block" gap="small">
            <s-text color="subdued">Created: {new Date(giftCard.createdAt).toLocaleDateString()}</s-text>
            {giftCard.customer && (
              <s-text color="subdued">Customer: {giftCard.customer.displayName}</s-text>
            )}
          </s-stack>
        </s-section>
      </s-stack>
    </s-admin-block>
  );
};

Anchor to Best practicesBest practices

Display balance context: Always show both current balance and initial value when displaying gift card information. This helps merchants understand usage patterns and whether a gift card is partially used, fully depleted, or unused.
Check enabled status before operations: Gift cards can be disabled by merchants or automatically by the system. Before displaying actions like "send to customer" or "sync to external system," verify the gift card's enabled status to avoid operations on disabled cards.
Handle balance adjustments with care: When building extensions that modify gift card balances using giftCardCredit or giftCardDebit, require explicit merchant confirmation and display the resulting balance before applying changes. Gift card balance errors can create customer service issues.
Reconcile external integrations: If your extension syncs gift cards with external loyalty platforms, ensure transaction histories stay synchronized. A mismatch between Shopify's balance and the external system's balance creates confusion and potential fraud issues.
Respect expiration dates: When displaying or exporting gift card data, prominently show expiration dates if set. Merchants need this information to proactively reach out to customers before cards expire and to ensure compliance with gift card regulations in their jurisdiction.

Anchor to LimitationsLimitations

Single target per module: Each [[extensions.targeting]] entry in your TOML configuration maps one target to one module file.
Gift card code immutability: Gift card codes cannot be modified after creation. The API only exposes lastCharacters (final 4 digits) and maskedCode. The giftCardUpdate mutation has no code field.
Permanent deactivation: After you've used the giftCardDeactivate mutation, gift cards can't be re-enabled.
Transaction history pagination: Gift card transaction history returns a maximum of 250 transactions per request.
Block target visibility: Block extensions must be manually added and pinned by merchants before they appear.
Block collapse behavior: Returning null from a block extension collapses the block rather than removing it from the page. Blocks can't be fully hidden at runtime.

Was this page helpful?