--- title: chargebacks description: >- Reference for the ShopifyQL `chargebacks` 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/chargebacks md: >- https://shopify.dev/docs/api/shopifyql/latest/schemas/finance_and_payments/chargebacks.md api_name: shopifyql --- # chargebacks The `chargebacks` [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas) captures disputed charges and how they compare to your successful transactions. Use it to report dispute volume, dollar amounts, rates, and the reason and resolution behind each dispute. ### Use cases * **Dispute volume**: Group [`chargebacks`](#chargebacksmetric-propertydetail-chargebacks) and [`fraudulent_chargebacks`](#chargebacksmetric-propertydetail-fraudulentchargebacks) by month to see whether disputes are trending up and how many are fraud-related. * **Dispute rate**: Show [`chargeback_rate`](#chargebacksmetric-propertydetail-chargebackrate) beside [`successful_transactions`](#chargebacksmetric-propertydetail-successfultransactions) to show the transaction base behind the rate. * **Reason breakdown**: Break down [`chargeback_amount`](#chargebacksmetric-propertydetail-chargebackamount) by [`chargeback_reason`](#chargebacksdimension-propertydetail-chargebackreason) to see which dispute reasons cost you the most. * **Rapid dispute resolution**: Group by [`is_rapid_dispute_resolution`](#chargebacksdimension-propertydetail-israpiddisputeresolution) to see what share of disputes were resolved early instead of becoming full chargebacks. Examples ### Examples * #### ##### Description Summarize last month's disputes, how many were fraudulent, and the successful transactions in the same period. This example uses \[\`WITH PERCENT\_CHANGE\`]\(/docs/api/shopifyql/latest/syntax/with#percent-change-columns) and \[\`COMPARE TO previous\_period\`]\(/docs/api/shopifyql/latest/syntax/compare-to) to show how each figure moved from the month before. ##### ShopifyQL ```shopifyql FROM chargebacks SHOW chargebacks, fraudulent_chargebacks, successful_transactions WITH PERCENT_CHANGE DURING last_month COMPARE TO previous_period ``` * #### ##### Description Compare monthly \`chargeback\_rate\` this year against the same months last year. This example uses \[\`WITH PERCENT\_CHANGE\`]\(/docs/api/shopifyql/latest/syntax/with#percent-change-columns) to add the year-over-year change column, with \[\`COMPARE TO previous\_year\`]\(/docs/api/shopifyql/latest/syntax/compare-to) setting the comparison baseline. ##### ShopifyQL ```shopifyql FROM chargebacks SHOW chargebacks, fraudulent_chargebacks, successful_transactions, chargeback_rate, fraudulent_chargeback_rate TIMESERIES month WITH PERCENT_CHANGE DURING this_year COMPARE TO previous_year ORDER BY month ASC VISUALIZE chargeback_rate TYPE horizontal_bar ``` * #### ##### Description Rank chargeback reasons by dollar volume last quarter, split by rapid-dispute-resolution status. This example uses a \[\`GROUP\_TOTALS\`]\(/docs/api/shopifyql/latest/syntax/with#group-total-columns) subtotal per reason to show which dispute types cost the most. ##### ShopifyQL ```shopifyql FROM chargebacks SHOW chargebacks, chargeback_amount GROUP BY chargeback_reason, is_rapid_dispute_resolution WITH TOTALS, GROUP_TOTALS DURING last_quarter ORDER BY chargeback_amount DESC LIMIT 20 VISUALIZE chargebacks TYPE grouped_bar ``` * #### ##### Description Chart weekly \`chargebacks\` by \`chargeback\_reason\` over last quarter. This example uses \[\`TIMESERIES week\`]\(/docs/api/shopifyql/latest/syntax/timeseries) with a \[\`stacked\_bar\`]\(/docs/api/shopifyql/latest/syntax/visualize) chart to show how each reason's share of disputes shifts week to week. ##### ShopifyQL ```shopifyql FROM chargebacks SHOW chargebacks, chargeback_amount GROUP BY chargeback_reason WITH TOTALS, GROUP_TOTALS TIMESERIES week DURING last_quarter ORDER BY week ASC LIMIT 20 VISUALIZE chargebacks 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 chargebacks`. * **chargeback\_​amount** **MONEY** The value of disputed charges across all chargeback reasons, reported in your store's currency. * **chargeback\_​rate** **PERCENT** Percentage of payments with disputed charges of any kind `Chargeback rate = chargebacks / successful transactions` * **chargebacks** **INTEGER** Number of payments with disputed charges of any kind * **fraudulent\_​chargeback\_​rate** **PERCENT** Percentage of payments with disputed charges due to reported fraud `Fraudulent chargeback rate = fraudulent chargebacks / successful transactions` * **fraudulent\_​chargebacks** **INTEGER** Number of payments with disputed charges due to reported fraud * **successful\_​transactions** **INTEGER** Number of successful payment transactions ### MONEY A monetary amount representing currency values such as prices, revenue, costs, and discounts. ```ts ``` ### PERCENT A percentage value represented as a decimal, where 0.25 represents 25%. ```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 chargebacks`. * **chargeback\_​reason** **STRING** The reported reason for the disputed charge. General is a catch-all for unspecified reasons, and Unrecognized means the customer doesn't recognize the charge on their statement. Other values include Fraudulent, Duplicate, and Product not received. * **day** **DAY\_TIMESTAMP** The day a disputed charge or successful payment transaction happened. * **day\_​of\_​week** **DAY\_OF\_WEEK** The day of the week a disputed charge or successful payment transaction happened, with values Monday through Sunday. * **hour** **HOUR\_TIMESTAMP** The hour a disputed charge or successful payment transaction happened. * **hour\_​of\_​day** **HOUR\_OF\_DAY** The hour of day a disputed charge or successful payment transaction happened, with values 0 through 23. * **is\_​rapid\_​dispute\_​resolution** **BOOLEAN** Was the dispute resolved via Rapid Dispute Resolution service * **minute** **MINUTE\_TIMESTAMP** The minute a disputed charge or successful payment transaction happened. * **month** **MONTH\_TIMESTAMP** The month a disputed charge or successful payment transaction happened. * **month\_​of\_​year** **MONTH\_OF\_YEAR** The month of the year a disputed charge or successful payment transaction happened, with values 1 through 12. * **quarter** **QUARTER\_TIMESTAMP** The quarter a disputed charge or successful payment transaction happened. * **second** **SECOND\_TIMESTAMP** The second a disputed charge or successful payment transaction happened. * **shop\_​id** **IDENTITY** The unique Shopify identifier for your store. Use [`shop_id`](#chargebacksdimension-propertydetail-shopid) with [`shop_name`](#chargebacksdimension-propertydetail-shopname) to show readable store labels. * **week** **WEEK\_TIMESTAMP** The week a disputed charge or successful payment transaction happened. * **week\_​of\_​year** **WEEK\_OF\_YEAR** The week of the year a disputed charge or successful payment transaction happened, with values 1 through 53. * **year** **YEAR\_TIMESTAMP** The year a disputed charge or successful payment transaction happened. * **shop\_​name** **STRING** Name of your store ### STRING A sequence of characters representing text data. ```ts ``` ### DAY\_TIMESTAMP A date value truncated to day precision. ```ts ``` ### DAY\_OF\_WEEK A day within a week, used for weekday-based grouping and filtering. ```ts ``` ### HOUR\_TIMESTAMP A timestamp truncated to hour precision. ```ts ``` ### HOUR\_OF\_DAY An hour within a day, typically represented as an integer from 0 to 23. ```ts ``` ### BOOLEAN A true or false value representing binary states. ```ts ``` ### MINUTE\_TIMESTAMP A timestamp truncated to minute precision. ```ts ``` ### MONTH\_TIMESTAMP A date value representing the start of a month. ```ts ``` ### MONTH\_OF\_YEAR A month number within a year. ```ts ``` ### QUARTER\_TIMESTAMP A date value representing the start of a fiscal quarter. ```ts ``` ### SECOND\_TIMESTAMP A timestamp truncated to second precision. ```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 ``` ### WEEK\_OF\_YEAR A week number within a year. ```ts ``` ### YEAR\_TIMESTAMP A date value representing the start of a year. ```ts ``` *** ## Related schemas * [`payments`](https://shopify.dev/docs/api/shopifyql/latest/schemas/finance_and_payments/payments): Transaction data upstream of these disputes. * [`payment_attempts`](https://shopify.dev/docs/api/shopifyql/latest/schemas/finance_and_payments/payment_attempts): Authorization data when you want to compare attempt-time signals with dispute outcomes. ***