--- title: gift_cards description: >- Reference for the ShopifyQL `gift_cards` table. Every metric and dimension, paired with worked example queries. api_version: 2026-07 source_url: html: >- https://shopify.dev/docs/api/shopifyql/latest/schemas/finance_and_payments/gift_cards md: >- https://shopify.dev/docs/api/shopifyql/latest/schemas/finance_and_payments/gift_cards.md api_name: shopifyql --- # gift\_​cards The `gift_cards` [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas) 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. ### Use cases * **Balance movement**: Show [`starting_gift_card_balance`](#giftcardsmetric-propertydetail-startinggiftcardbalance), [`gift_card_balance_net_change`](#giftcardsmetric-propertydetail-giftcardbalancenetchange), and [`ending_gift_card_balance`](#giftcardsmetric-propertydetail-endinggiftcardbalance) together for each month to see how your outstanding gift card liability grew or shrank. * **Activity by currency**: Group [`gift_cards_issued`](#giftcardsmetric-propertydetail-giftcardsissued), [`gift_cards_adjusted`](#giftcardsmetric-propertydetail-giftcardsadjusted), and [`gift_cards_disabled`](#giftcardsmetric-propertydetail-giftcardsdisabled) by [`gift_card_currency`](#giftcardsdimension-propertydetail-giftcardcurrency) to see which currencies drive gift card activity. * **Issued vs. sold**: Compare [`issued_gift_card_balance`](#giftcardsmetric-propertydetail-issuedgiftcardbalance) and [`sold_gift_card_balance`](#giftcardsmetric-propertydetail-soldgiftcardbalance) to separate the gift cards customers purchased from your total issued balance. Examples ### 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 ```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 ```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 ```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 ```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 ``` *** ## Metrics 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`. * **adjusted\_​gift\_​card\_​value** **MONEY** Value of gift cards adjusted in the given period * **disabled\_​gift\_​card\_​value** **MONEY** The value removed from outstanding gift card liability when gift cards are disabled during the period included in your results. * **ending\_​gift\_​card\_​balance** **MONEY** The outstanding gift card liability at the end of the time period included in your results. * **gift\_​card\_​balance\_​net\_​change** **MONEY** 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` * **gift\_​cards\_​adjusted** **INTEGER** Number of gift cards adjusted in the given period * **gift\_​cards\_​disabled** **INTEGER** Number of gift cards disabled in the given period * **gift\_​cards\_​issued** **INTEGER** Number of gift cards issued in the given period * **issued\_​gift\_​card\_​balance** **MONEY** The outstanding gift card liability added when gift cards are issued during the period included in your results. * **sold\_​gift\_​card\_​balance** **MONEY** The outstanding gift card liability added when gift cards are sold during the period included in your results. * **starting\_​gift\_​card\_​balance** **MONEY** 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. ```ts ``` ### INTEGER A whole number without decimal places, used for counts, quantities, and other discrete numeric values. ```ts ``` *** ## Dimensions 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`. * **day** **DAY\_TIMESTAMP** The day gift card activity happened. * **gift\_​card\_​currency** **STRING** Currency code of the gift card balance * **month** **MONTH\_TIMESTAMP** The month gift card activity happened. * **quarter** **QUARTER\_TIMESTAMP** The quarter gift card activity happened. * **shop\_​id** **IDENTITY** The unique Shopify identifier for your store. Use [`shop_id`](#giftcardsdimension-propertydetail-shopid) with [`shop_name`](#giftcardsdimension-propertydetail-shopname) to show readable store labels. * **week** **WEEK\_TIMESTAMP** The week gift card activity happened. * **year** **YEAR\_TIMESTAMP** The year gift card activity happened. * **shop\_​name** **STRING** Name of your store ### DAY\_TIMESTAMP A date value truncated to day precision. ```ts ``` ### STRING A sequence of characters representing text data. ```ts ``` ### MONTH\_TIMESTAMP A date value representing the start of a month. ```ts ``` ### QUARTER\_TIMESTAMP A date value representing the start of a fiscal quarter. ```ts ``` ### IDENTITY A unique identifier for a Shopify resource such as a customer, product, or order. ```ts ``` ### WEEK\_TIMESTAMP A date value representing the start of a week. ```ts ``` ### YEAR\_TIMESTAMP A date value representing the start of a year. ```ts ``` *** ## Related schemas * [`sales`](https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/sales): Top-line revenue including the sales that gift card redemptions paid for. * [`payments`](https://shopify.dev/docs/api/shopifyql/latest/schemas/finance_and_payments/payments): Transaction-level data when you need to reconcile gift card redemptions against payment records. ***