--- title: returns description: >- Data about individual items returned by customers, including reasons and quantities api_version: 2026-10 source_url: html: 'https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/returns' md: >- https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/returns.md api_name: shopifyql --- # returns The `returns` [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas) captures item-level return records. It's the source for returned quantity and return status or reason context, with links back to refunds, orders, line items, staff, and app integrations. ### Use cases * **Return reasons**: Group [`returned_quantity`](#returnsmetric-propertydetail-returnedquantity) by [`return_line_item_reason`](#returnsdimension-propertydetail-returnlineitemreason) to see why customers send items back. * **Status**: Filter [`return_status`](#returnsdimension-propertydetail-returnstatus) to separate open returns still in progress from completed ones. * **Refund and order link**: Use [`refund_id`](#returnsdimension-propertydetail-refundid), [`order_id`](#returnsdimension-propertydetail-orderid), and [`line_item_id`](#returnsdimension-propertydetail-lineitemid) to connect returned quantities to refund and order detail. * **Attribution**: Break down [`returned_quantity`](#returnsmetric-propertydetail-returnedquantity) by [`return_app_name`](#returnsdimension-propertydetail-returnappname) or [`staff_id`](#returnsdimension-propertydetail-staffid) to see which apps or staff process returns. Examples ### Examples * #### ##### Description Track weekly \`returned\_quantity\` across the current quarter as a line. This example uses \[\`WITH TOTALS\`]\(/docs/api/shopifyql/latest/syntax/with#total-columns) to add a quarter-total column. ##### ShopifyQL ```shopifyql FROM returns SHOW returned_quantity TIMESERIES week WITH TOTALS DURING this_quarter ORDER BY week ASC VISUALIZE returned_quantity TYPE line ``` * #### ##### Description Compare \`returned\_quantity\` for last month with a percent-change column. This example uses \[\`COMPARE TO previous\_period\`]\(/docs/api/shopifyql/latest/syntax/compare-to) to benchmark last month against the month before. ##### ShopifyQL ```shopifyql FROM returns SHOW returned_quantity WITH PERCENT_CHANGE DURING last_month COMPARE TO previous_period ``` * #### ##### Description Rank return reasons by \`returned\_quantity\` over the last 90 days, the top 25 as horizontal bars. This example uses \[\`WITH TOTALS\`]\(/docs/api/shopifyql/latest/syntax/with#total-columns) to add an all-reason total. ##### ShopifyQL ```shopifyql FROM returns SHOW returned_quantity GROUP BY return_line_item_reason WITH TOTALS SINCE -90d UNTIL today ORDER BY returned_quantity DESC LIMIT 25 VISUALIZE returned_quantity TYPE horizontal_bar ``` * #### ##### Description Split weekly \`returned\_quantity\` by \`return\_status\` across this quarter as stacked bands. This example uses \[\`COMPARE TO previous\_quarter\`]\(/docs/api/shopifyql/latest/syntax/compare-to) to align each week with the matching week a quarter earlier. ##### ShopifyQL ```shopifyql FROM returns SHOW returned_quantity GROUP BY return_status TIMESERIES week DURING this_quarter COMPARE TO previous_quarter ORDER BY week ASC VISUALIZE returned_quantity TYPE stacked_area ``` *** ## 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 returns`. * **returned\_​quantity** **INTEGER** The total quantity of individual items returned in your results. ### 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 returns`. * **day** **DAY\_TIMESTAMP** The day a returned item was added to a return. * **day\_​of\_​week** **DAY\_OF\_WEEK** The day of the week a returned item was added to a return, with values Monday through Sunday. * **hour** **HOUR\_TIMESTAMP** The hour a returned item was added to a return. * **hour\_​of\_​day** **HOUR\_OF\_DAY** The hour of the day a returned item was added to a return, with values 0 through 23. * **is\_​unverified\_​return\_​line\_​item** **BOOLEAN** Values are `true` when the return hasn't been verified yet and `false` otherwise. * **line\_​item\_​id** **IDENTITY** The unique Shopify identifier for the original order line item associated with the returned item. * **minute** **MINUTE\_TIMESTAMP** The minute a returned item was added to a return. * **month** **MONTH\_TIMESTAMP** The month a returned item was added to a return. * **month\_​of\_​year** **MONTH\_OF\_YEAR** The month of the year a returned item was added to a return, with values 1 through 12. * **order\_​id** **IDENTITY** The unique Shopify identifier for the order that included the returned item. Use [`order_id`](#returnsdimension-propertydetail-orderid) to filter to a specific order, or use it with [`order_name`](#returnsdimension-propertydetail-ordername) to show readable results. * **quarter** **QUARTER\_TIMESTAMP** The quarter a returned item was added to a return. * **refund\_​id** **IDENTITY** The unique Shopify identifier for the refund connected to the returned item. Use [`refund_id`](#returnsdimension-propertydetail-refundid) to filter returns tied to a specific refund. * **return\_​app\_​id** **IDENTITY** The unique Shopify identifier for the app or integration that created the return. Use [`return_app_id`](#returnsdimension-propertydetail-returnappid) to filter to a specific app, or use it with [`return_app_name`](#returnsdimension-propertydetail-returnappname) to show readable labels. * **return\_​app\_​name** **STRING** Name of the app or integration that created the return * **return\_​customer\_​note** **STRING** Values are free-text notes the customer writes when requesting the return. * **return\_​id** **IDENTITY** The unique Shopify identifier for the return that contains the returned item. Use [`return_id`](#returnsdimension-propertydetail-returnid) to filter to a specific return. * **return\_​line\_​item\_​id** **IDENTITY** The unique Shopify identifier for the individual returned item line. Use [`return_line_item_id`](#returnsdimension-propertydetail-returnlineitemid) to filter to a specific item within a return. * **return\_​line\_​item\_​reason** **STRING** The reason selected for the returned item, such as Changed my mind, Damaged or defective, Too small, or Received the wrong item. * **return\_​name** **STRING** Display name of the return * **return\_​note** **STRING** Values are free-text notes staff add while processing the return. * **return\_​status** **STRING** The status of the return that contains the returned item. Values are Closed, Open, Canceled, Requested, and Declined. * **second** **SECOND\_TIMESTAMP** The second a returned item was added to a return. * **shop\_​id** **IDENTITY** The unique Shopify identifier for your store. Use [`shop_id`](#returnsdimension-propertydetail-shopid) to filter to a specific store, or use it with [`shop_name`](#returnsdimension-propertydetail-shopname) to show readable labels. * **staff\_​id** **IDENTITY** The unique Shopify identifier for the staff member associated with the order. Use [`staff_id`](#returnsdimension-propertydetail-staffid) to filter to a specific staff member, or use it with [`staff_member_name`](#returnsdimension-propertydetail-staffmembername) to show readable labels. * **week** **WEEK\_TIMESTAMP** The week a returned item was added to a return. * **week\_​of\_​year** **WEEK\_OF\_YEAR** The week of the year a returned item was added to a return, with values 1 through 53. * **year** **YEAR\_TIMESTAMP** The year a returned item was added to a return. * **product\_​title\_​at\_​time\_​of\_​sale** **STRING** The product name as it appeared when the item was sold. * **product\_​type\_​at\_​time\_​of\_​sale** **STRING** The product type or category assigned when the item was sold. * **product\_​variant\_​compare\_​at\_​price** **MONEY** The compare-at price of the product variant when the item was sold, in your store's currency. * **product\_​variant\_​price** **MONEY** The price of the product variant when the item was sold, in your store's currency. * **product\_​variant\_​sku\_​at\_​time\_​of\_​sale** **STRING** The SKU of the product variant when the item was sold. * **product\_​variant\_​title\_​at\_​time\_​of\_​sale** **STRING** The variant name as it appeared when the item was sold. * **product\_​vendor\_​at\_​time\_​of\_​sale** **STRING** The vendor assigned to the product when the item was sold. * **shop\_​name** **STRING** Name of your store * **collective\_​supplier** **STRING** Supplier of the product sourced through Shopify Collective * **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`](#returnsdimension-propertydetail-ordersaleschannelid) with [`order_sales_channel`](#returnsdimension-propertydetail-ordersaleschannel) to show readable channel labels. * **is\_​shop\_​referral\_​order** **BOOLEAN** Whether the order was referred from the Shop app or shop.app, with values `true` and `false`. * **order\_​landing\_​page\_​path** **STRING** Path of the first page of the user session that resulted in the order * **order\_​landing\_​page\_​url** **STRING** First page of the user session that resulted in the order * **order\_​marketing\_​event\_​id** **IDENTITY** Shopify identifier for the marketing event associated with the order * **order\_​referrer\_​domain** **STRING** Domain of the site that led to the order * **order\_​referrer\_​name** **STRING** The readable name of the site that led to the order. * **order\_​referrer\_​path** **STRING** Path of the site that led to the order * **order\_​referrer\_​site** **STRING** Site that led to the order * **order\_​referrer\_​source** **STRING** The referrer type that led to the order, such as organic or email. * **order\_​referrer\_​url** **STRING** External page that referred a customer and led to the order * **order\_​utm\_​campaign** **STRING** UTM name of the campaign associated with the order * **order\_​utm\_​content** **STRING** The UTM content value associated with the order, often used to distinguish ads, links, or content variations. * **order\_​utm\_​medium** **STRING** The UTM medium associated with the order, such as email, social, or paid search. * **order\_​utm\_​source** **STRING** The UTM source associated with the order, such as Google, Facebook, or a newsletter. * **order\_​utm\_​term** **STRING** The UTM term associated with the order, often used for paid search keywords or other tracked terms. * **number\_​of\_​products\_​bought\_​together** **INTEGER** Total unique products in the same order * **number\_​of\_​variants\_​bought\_​together** **INTEGER** The number of unique product variants in the same order, with each SKU counted a single time. * **products\_​bought\_​together** **ARRAY\** The product names that appear in the same order. * **products\_​bought\_​together\_​ids** **ARRAY\** The Shopify product identifiers for products in the same order. * **variants\_​bought\_​together** **ARRAY\** The product variant labels that appear in the same order, such as size, color, or style combinations. * **company\_​id** **IDENTITY** The unique Shopify identifier for the company. Use [`company_id`](#returnsdimension-propertydetail-companyid) with [`company_name`](#returnsdimension-propertydetail-companyname) to show readable company labels. * **company\_​name** **STRING** Name of the company that placed the order * **company\_​location\_​id** **IDENTITY** The unique Shopify identifier for the company location. Use [`company_location_id`](#returnsdimension-propertydetail-companylocationid) with [`company_location_name`](#returnsdimension-propertydetail-companylocationname) to show readable company location labels. * **company\_​location\_​name** **STRING** Company location or branch that placed the order * **referring\_​channel** **STRING** Marketing channel that referred the customer to place the order * **referring\_​medium** **STRING** The marketing medium that referred the customer to place the order, such as email, social, or search. * **referring\_​platform** **STRING** The marketing platform that referred the customer to place the order, such as Google, Facebook, or Instagram. * **traffic\_​type** **STRING** The type of traffic that led to the order, such as organic, paid, or direct. * **order\_​marketing\_​event\_​target** **STRING** The platform or channel where the marketing activity was deployed, such as Email, Facebook, Google, or Instagram. * **order\_​marketing\_​event\_​type** **STRING** The type of marketing activity that led to the order, such as Ad, Affiliate, Newsletter, or Retargeting. PLA means Product Listing Ads, and SEO means Search Engine Optimization. * **market** **STRING** Market you've defined in Shopify, like a geographical market or customer group * **markets** **ARRAY\** Markets or customer segments associated with the order * **order\_​cancellation\_​reason** **STRING** The reason specified for the order cancellation, such as Customer, Other, Fraud, or Inventory. * **order\_​risk\_​level** **STRING** The fraud risk level Shopify assigned to the order, with values Low, Medium, High, None, and Pending. * **order\_​is\_​shopify\_​protect\_​covered** **BOOLEAN** Whether the order has met Shopify Protect fulfillment requirements, including proper shipping and tracking, with values `true` and `false`. * **order\_​is\_​shopify\_​protect\_​eligible** **BOOLEAN** Whether the order qualifies for Shopify Protect, with values `true` and `false`. * **order\_​is\_​shopify\_​protect\_​protected** **BOOLEAN** Whether the order has full Shopify Protect coverage against fraud, with values `true` and `false`. * **order\_​tag** **STRING** Tag associated with the order * **order\_​tags** **ARRAY\** Set of tags associated with the order * **activation\_​platform** **STRING** Marketing platform that activated this marketing activity * **agentic\_​referring\_​channel** **STRING** The AI agent or assistant that referred the session to your online store, with values ChatGPT, Google AI Mode and Gemini, Microsoft Copilot, and Shop. * **channel\_​handle** **STRING** Name of the marketing channel or platform that drove the marketing engagement * **marketing\_​activity\_​id** **IDENTITY** The unique Shopify identifier for the marketing activity. Use [`marketing_activity_id`](#returnsdimension-propertydetail-marketingactivityid) with [`marketing_activity_title`](#returnsdimension-propertydetail-marketingactivitytitle) to show readable activity labels. * **marketing\_​activity\_​status** **STRING** Current status of the marketing activity (such as Active or Paused) * **marketing\_​activity\_​title** **STRING** Name of the marketing activity * **marketing\_​activity\_​url\_​parameter\_​key** **STRING** URL parameter key for the marketing activity * **marketing\_​activity\_​url\_​parameter\_​value** **STRING** URL parameter value for the marketing activity * **marketing\_​app\_​name** **STRING** The app that created the marketing activity. * **marketing\_​automation\_​id** **IDENTITY** Unique ID that Shopify uses to identify the marketing automation * **marketing\_​campaign** **STRING** The campaign-level detail for the attributed online store visit: the marketing activity title when the visit is matched to a marketing activity, otherwise the UTM campaign, otherwise the traffic type for direct or organic visits. * **marketing\_​channel** **STRING** The normalized marketing channel for the attributed online store visit. For visits matched to an integrated ad activity, this is its marketing product, such as Google Ads or Meta Ads. Other matched activities use the integration's app name. Visits without a matched activity use the referring channel. * **marketing\_​delivery\_​channel** **STRING** Channel through which the marketing activity is delivered * **marketing\_​event\_​id** **IDENTITY** Unique identifier for the associated marketing event * **marketing\_​platform** **STRING** The marketing platform that created the marketing activity, shown as a platform name. * **page\_​host** **STRING** The host name of the session landing page. * **page\_​path** **STRING** The path of the session landing page. * **page\_​url** **STRING** The URL of the first page viewed in the session. * **referrer\_​url** **STRING** External page that led to an online store session * **utm\_​campaign** **STRING** UTM name of the campaign associated with the session * **utm\_​content** **STRING** The UTM content value associated with the session, often used to distinguish ads, links, or content variations. * **utm\_​medium** **STRING** The UTM medium associated with the session, such as email, social, or paid search. * **utm\_​source** **STRING** The UTM source associated with the session, such as Google, Facebook, or a newsletter. * **utm\_​term** **STRING** The UTM term associated with the session, often used for paid search keywords or other tracked terms. * **staff\_​member\_​name** **STRING** Name of the staff member associated with the order ### 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 ``` ### IDENTITY Unique identifier for a Shopify resource such as a customer or order ```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 ``` ### QUARTER\_TIMESTAMP Date for the start of a fiscal quarter ```ts ``` ### STRING Text made of letters, numbers, or symbols ```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 ``` ### MONEY Currency amount such as a price, revenue, cost, or discount ```ts ``` ### ARRAY A list of values. The element type appears inside angle brackets, such as ARRAY\. ```ts ``` ***