--- title: chargebacks description: >- Reference for the ShopifyQL `chargebacks` schema. Every metric and dimension, paired with worked example queries. api_version: 2026-10 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 Currency amount such as a price, revenue, cost, or discount ```ts ``` ### PERCENT A percentage value represented as a decimal, where 0.25 represents 25%. ```ts ``` ### INTEGER Whole number without decimal places, used for counts and quantities ```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. * **order\_​id** **IDENTITY** The unique Shopify identifier for the order the disputed charge or successful payment transaction belongs to. Use [`order_id`](#chargebacksdimension-propertydetail-orderid) to filter to a specific order, or join to order details to analyze chargebacks by order attributes. Empty when the dispute or transaction is not tied to an order. * **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. * **is\_​b2b\_​order** **BOOLEAN** Whether the order is a B2B order, with values `true` and `false`. * **is\_​canceled\_​order** **BOOLEAN** Whether the order is canceled, with values `true` and `false`. * **order\_​checkout\_​currency** **STRING** The currency the buyer saw at checkout when placing the order. Values are currency codes such as USD, CAD, EUR, and GBP. * **order\_​fulfillment\_​status** **STRING** The order's fulfillment state, with values Fulfilled, Partial, Restocked, and Unfulfilled. * **order\_​includes\_​duties** **BOOLEAN** Whether the order includes duties, with values `true` and `false`. * **order\_​name** **STRING** The name or number of the order as the customer sees it. * **order\_​payment\_​status** **STRING** The order's payment state, such as Authorized, Paid, Partially refunded, or Pending. * **order\_​sales\_​channel** **STRING** The sales channel where the order was placed, shown as a channel name such as Online Store or POS. * **order\_​sales\_​channel\_​id** **IDENTITY** The unique Shopify identifier for the order's sales channel. Use [`order_sales_channel_id`](#chargebacksdimension-propertydetail-ordersaleschannelid) with [`order_sales_channel`](#chargebacksdimension-propertydetail-ordersaleschannel) to show readable channel labels. * **shop\_​name** **STRING** Name of your store ### STRING Text made of letters, numbers, or symbols ```ts ``` ### DAY\_TIMESTAMP Date with the time of day removed ```ts ``` ### DAY\_OF\_WEEK Day of the week, used to group or filter data by weekday ```ts ``` ### HOUR\_TIMESTAMP Date and time with minutes and seconds removed ```ts ``` ### HOUR\_OF\_DAY Hour of the day, shown as a whole number from 0 to 23 ```ts ``` ### BOOLEAN Value that is either true or false ```ts ``` ### MINUTE\_TIMESTAMP Date and time with seconds removed ```ts ``` ### MONTH\_TIMESTAMP Date for the start of a month ```ts ``` ### MONTH\_OF\_YEAR Month number within a year ```ts ``` ### IDENTITY Unique identifier for a Shopify resource such as a customer or order ```ts ``` ### QUARTER\_TIMESTAMP Date for the start of a fiscal quarter ```ts ``` ### SECOND\_TIMESTAMP Date and time with fractions of a second removed ```ts ``` ### WEEK\_TIMESTAMP Date for the start of a week ```ts ``` ### WEEK\_OF\_YEAR Week number within a year ```ts ``` ### YEAR\_TIMESTAMP Date for 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. ***