Choose a version:

gift_cards

The gift_cards schema captures gift card balance movement over time. It supports both period activity and balance-position views, especially when you need to separate balances by currency.

Anchor to Use casesUse cases

Balance movement: Show starting_gift_card_balance, gift_card_balance_net_change, and ending_gift_card_balance together for each month to see how your outstanding gift card liability grew or shrank.
Activity by currency: Group gift_cards_issued, gift_cards_adjusted, and gift_cards_disabled by gift_card_currency to see which currencies drive gift card activity.
Issued vs. sold: Compare issued_gift_card_balance and sold_gift_card_balance to separate the gift cards customers purchased from your total issued balance.

Examples

ShopifyQL

View in adminView query results in the ShopifyQL editor

FROM gift_cards

SHOW starting_gift_card_balance, issued_gift_card_balance,

sold_gift_card_balance, adjusted_gift_card_value, disabled_gift_card_value,

ending_gift_card_balance, gift_card_balance_net_change

TIMESERIES month WITH PERCENT_CHANGE

DURING this_year

COMPARE TO previous_year

ORDER BY month ASC

VISUALIZE ending_gift_card_balance TYPE line

Examples

Description
Track your outstanding gift card liability month by month this year, measured against the same months last year. This example uses [`WITH PERCENT_CHANGE`](/docs/api/shopifyql/latest/syntax/with#percent-change-columns) with [`COMPARE TO previous_year`](/docs/api/shopifyql/latest/syntax/compare-to) to quantify the year-over-year change in `ending_gift_card_balance`.
ShopifyQL
```
FROM gift_cards
  SHOW starting_gift_card_balance, issued_gift_card_balance,
    sold_gift_card_balance, adjusted_gift_card_value, disabled_gift_card_value,
    ending_gift_card_balance, gift_card_balance_net_change
  TIMESERIES month WITH PERCENT_CHANGE
  DURING this_year
  COMPARE TO previous_year
  ORDER BY month ASC
VISUALIZE ending_gift_card_balance TYPE line
```
Description
Track monthly `sold_gift_card_balance` by currency for the year to date. This example uses [`GROUP_TOTALS`](/docs/api/shopifyql/latest/syntax/with#group-total-columns) to add a per-month total column beside the per-currency bands.
ShopifyQL
```
FROM gift_cards
  SHOW sold_gift_card_balance
  GROUP BY gift_card_currency WITH GROUP_TOTALS
  TIMESERIES month
  DURING this_year
  ORDER BY month ASC
VISUALIZE sold_gift_card_balance TYPE stacked_bar
```
Description
Track the year's gift card activity as running totals, with cards issued, adjusted, and disabled accumulating month by month. This example uses [`CUMULATIVE_VALUES`](/docs/api/shopifyql/latest/syntax/with#cumulative-values) to carry each month's counts forward into a year-to-date total.
ShopifyQL
```
FROM gift_cards
  SHOW gift_cards_adjusted, gift_cards_disabled, gift_cards_issued
  TIMESERIES month WITH CUMULATIVE_VALUES, TOTALS
  DURING this_year
  ORDER BY month ASC
VISUALIZE gift_cards_issued TYPE bar
```
Description
Track weekly `adjusted_gift_card_value` split by `gift_card_currency` across last quarter. This example uses [`GROUP_TOTALS`](/docs/api/shopifyql/latest/syntax/with#group-total-columns) to add a per-week total across currencies beside the per-currency bands.
ShopifyQL
```
FROM gift_cards
  SHOW adjusted_gift_card_value
  GROUP BY gift_card_currency WITH TOTALS, GROUP_TOTALS
  TIMESERIES week
  DURING last_quarter
  ORDER BY week ASC
VISUALIZE adjusted_gift_card_value TYPE stacked_bar
```

Anchor to MetricsMetrics

Counts and calculations that let you track key business indicators. Metrics show up as the columns when queried.

Metrics you can use when querying FROM gift_cards.

Anchor to adjusted_gift_card_value adjusted_gift_card_value: Value of gift cards adjusted in the given period
Anchor to disabled_gift_card_value disabled_gift_card_value: The value removed from outstanding gift card liability when gift cards are disabled during the period included in your results.
Anchor to ending_gift_card_balance ending_gift_card_balance: The outstanding gift card liability at the end of the time period included in your results.
Anchor to gift_card_balance_net_change gift_card_balance_net_change: The change in outstanding gift card liability across the time period in your results. Positive values mean the balance grew, and negative values mean it fell.

Gift card balance net change = ending gift card balance - starting gift card balance
Anchor to gift_cards_adjusted gift_cards_adjusted: Number of gift cards adjusted in the given period
Anchor to gift_cards_disabled gift_cards_disabled: Number of gift cards disabled in the given period
Anchor to gift_cards_issued gift_cards_issued: Number of gift cards issued in the given period
Anchor to issued_gift_card_balance issued_gift_card_balance: The outstanding gift card liability added when gift cards are issued during the period included in your results.
Anchor to sold_gift_card_balance sold_gift_card_balance: The outstanding gift card liability added when gift cards are sold during the period included in your results.
Anchor to starting_gift_card_balance starting_gift_card_balance: The outstanding gift card liability at the beginning of the time period included in your results.

MONEY

A monetary amount representing currency values such as prices, revenue, costs, and discounts.

INTEGER

A whole number without decimal places, used for counts, quantities, and other discrete numeric values.

Anchor to DimensionsDimensions

Attributes of your data that let you look more granularly at aspects of the data. Group and filter by dimensions to shape the rows your query returns.

Dimensions you can use when querying FROM gift_cards.

Anchor to day day: The day gift card activity happened.
Anchor to gift_card_currency gift_card_currency: Currency code of the gift card balance
Anchor to month month: The month gift card activity happened.
Anchor to quarter quarter: The quarter gift card activity happened.
Anchor to shop_id shop_id: The unique Shopify identifier for your store. Use shop_id with shop_name to show readable store labels.
Anchor to week week: The week gift card activity happened.
Anchor to year year: The year gift card activity happened.
Anchor to shop_name shop_name: Name of your store

DAY_TIMESTAMP

A date value truncated to day precision.

STRING

A sequence of characters representing text data.

MONTH_TIMESTAMP

A date value representing the start of a month.

QUARTER_TIMESTAMP

A date value representing the start of a fiscal quarter.

IDENTITY

A unique identifier for a Shopify resource such as a customer, product, or order.

WEEK_TIMESTAMP

A date value representing the start of a week.

YEAR_TIMESTAMP

A date value representing the start of a year.

Anchor to Related schemasRelated schemas

sales: Top-line revenue including the sales that gift card redemptions paid for.
payments: Transaction-level data when you need to reconcile gift card redemptions against payment records.

Was this page helpful?