App Permissions

When you install FilterIQ, Shopify asks you to approve a set of permissions (OAuth scopes). We follow the principle of least privilege -- we only request permissions that are necessary for the app to function. This page explains every scope we request, what we access, and what we do not access.

read_products

Why we need it: We read your product data to index it for search. This is the core functionality of the app -- without access to your products, we cannot provide search or filtering.

What we access:

• Product titles, descriptions, and handles
• Tags and product type
• Vendor name
• Variant information (options, prices, SKUs, inventory quantities)
• Product images (URLs only)
• Product metafields (only the namespaces you configure for search/filtering)
• Product status (active, draft, archived)

What we do not access:

• We do not access product cost data or margin information
• We do not modify any product data through this scope (it is read-only)

write_products

Why we need it: We write to product metafields to store filter configuration data. This allows the app to associate filter settings with individual products when needed.

What we access:

• Product metafields in our app-owned namespaces:
  • searchfilters.* — the legacy app-owned namespace and current production write target for filter-related attribute data while V2 migration is in progress
  • Shopify standard taxonomy metafields (e.g. shopify.color-pattern, shopify.fabric) where the merchant has assigned a Shopify Standard Category and our V2 migration has shipped to the relevant attribute (see Changelog for per-attribute migration status)
• Native product fields where applicable (e.g. vendor for brand) only when our canonical-write feature flag is enabled by the merchant

What we do not access or modify:

• We never modify your product titles, descriptions, or handles
• We never change prices, variants, or inventory
• We never modify images or SEO fields
• We never delete products
• We do not write to or read from any other app's metafield namespace

read_product_listings

Why we need it: We read published product listings to ensure only products that are active and visible on your storefront appear in search results. This prevents draft or hidden products from showing up in search.

What we access:

• The list of products published to your Online Store sales channel
• Published status and publication dates

What we do not access:

• Product listings for other sales channels (POS, wholesale, etc.) unless you explicitly configure them

read_themes

Why we need it: We read your theme to verify compatibility with our Theme App Extension and to detect your theme's structure for optimal widget placement.

What we access:

• Theme name, ID, and role (main/unpublished)
• Theme asset list (file names only, to check for OS 2.0 compatibility)
• Theme settings schema (to detect CSS variables for style matching)

What we do not access:

• We do not read your theme's Liquid template source code
• We do not access any custom code you have added to your theme

write_themes

Why we need it: We write theme settings only to install and update our Theme App Extension block. This is how the search widget and filter sidebar appear on your storefront.

What we access:

• Theme App Extension block settings for the FilterIQ extension only

What we do not modify:

• We never modify your theme's Liquid files
• We never change your theme's CSS or JavaScript
• We never alter your theme settings (colors, fonts, layout)
• We never switch your active theme
• All writes are scoped to our app extension block

read_content

Why we need it: We read pages and blog posts to include them in search results, if you enable content search. This allows shoppers to find relevant pages (e.g., sizing guides, FAQ, care instructions) when they search your store.

What we access:

• Page titles, content, and handles
• Blog post titles, content, and handles
• Only when you have content search enabled in Settings

What we do not access:

• We do not read content unless you explicitly enable content search
• We do not access navigation menus, redirects, or script tags

read_discounts

Why we need it: We read discount rules to display accurate sale prices in search results. Without this, search result cards might show regular prices even when a product is on sale.

What we access:

• Automatic discount rules (percentage off, fixed amount, etc.)
• Discount applicability (which products or collections a discount applies to)
• Discount active dates

What we do not access:

• We do not read discount codes (manual/code-based discounts)
• We do not access customer-specific discounts
• We do not modify or create discounts

read_inventory

Why we need it: We read stock levels to power inventory-based merchandising features like "Hide Out-of-Stock" and "Bury Low Stock." These features ensure shoppers see available products first and are not shown products they cannot purchase.

What we access:

• Inventory quantities per variant per location
• Inventory tracking status (tracked vs. not tracked)

What we do not access:

• We do not access inventory adjustment history
• We do not access incoming or committed inventory
• We do not modify inventory levels

read_orders

Why we need it: We read orders only to attribute search-driven conversions in your analytics dashboard. When a shopper searches, then later places an order, we count that as a search-attributed conversion so you can see which queries actually drive revenue.

What we access:

• Order created/paid timestamps (to match against recent search sessions)
• Order line items (product IDs only — to confirm the searched-for product was purchased)
• Order total (to compute revenue-attributed-to-search)

What we do not access:

• We do not read customer names, emails, addresses, or payment details
• We do not read shipping or fulfillment data
• We do not modify orders in any way
• We never use this data for marketing or pass it to third parties

read_metaobjects

Why we need it: Shopify metaobjects let merchants model custom content (e.g. "Brand", "Material profile") that products reference. We read metaobject definitions and entries so those structured values can become first-class filter facets on your storefront.

What we access:

• Metaobject definition names and field schemas
• Metaobject entries referenced by products you've indexed for search

What we do not access:

• Metaobjects unrelated to your product catalogue
• We never modify metaobject definitions or entries

read_customer_events

Why we need it: This scope is required to install our App Pixel — a Shopify-managed JavaScript snippet that subscribes to the standard search_submitted Customer Event. The pixel runs in Shopify's strict sandbox and lets us count every storefront search reliably, regardless of which theme you use or whether our search widget is loaded.

What we access:

• The standard search_submitted event payload: the search query string and the list of product IDs returned by Shopify's native search.
• Read access to the Customer Events catalog so Shopify can validate which events our pixel is allowed to subscribe to.

What we do not access:

• We do not subscribe to any other Customer Event (no cart_viewed, no checkout_started, no marketing events).
• We do not read individual customer profiles, demographics, or contact info via this scope.
• The pixel runs in Shopify's strict sandbox: it has no access to document, window, localStorage, or third-party cookies. It cannot fingerprint visitors.

write_pixels

Why we need it: Required to register our App Pixel with Shopify (the one-time webPixelCreate mutation that activates the pixel above). Without this scope we cannot install the storefront search-tracking pixel.

What we access / write:

• We create exactly one App Pixel record per shop, named smart-search-filter-web-pixel. Its only behaviour is the search_submitted subscription described above.

What we do not do:

• We do not create custom pixels with arbitrary JavaScript.
• We do not modify other apps' pixels.
• We never inject tracking scripts directly into your theme. All pixel code runs inside Shopify's sandboxed worker.

Summary

Scope	Access Type	Purpose
read_products	Read	Index products for search
write_products	Write	Store filter config in metafields
read_product_listings	Read	Show only published products
read_themes	Read	Verify theme compatibility
write_themes	Write	Install/update Theme App Extension
read_content	Read	Include pages/blogs in search
read_discounts	Read	Accurate sale prices in results
read_inventory	Read	Out-of-stock merchandising
read_orders	Read	Attribute search-driven conversions to revenue
read_metaobjects	Read	Model custom-object filters (e.g. brand, material)
read_customer_events	Read	Subscribe to standard search_submitted Web Pixel event
write_pixels	Write	Register our App Pixel for theme-agnostic search tracking

If you have questions about our permissions or data access, contact us at support@filteriq.app.