Shopify merchants and developers constantly look for ways to surface richer data in reports. The latest Developer Changelog update makes that easier than ever: you can now flag metafield and metaobject definitions as analytics‑queryable straight from your app’s shopify.app.toml file. This declarative approach eliminates the need to call the GraphQL Admin API for each definition, streamlines deployments, and instantly unlocks new dimensions and filters in Shopify Analytics and ShopifyQL. In this post we’ll break down what changed, who should care, and the exact steps you need to take to start leveraging this capability today.
What’s New? Declarative analytics_queryable Capability
Previously, making a metafield or metaobject usable in analytics required a GraphQL mutation (metafieldDefinitionCreate, metafieldDefinitionUpdate, metaobjectDefinitionCreate, or metaobjectDefinitionUpdate) with the analyticsQueryable flag set to true. The new release adds a capabilities.analytics_queryable field to the TOML schema. When this flag is true, Shopify automatically propagates the definition to every shop where your app is installed, and the field becomes available as a dimension or filter in the analytics UI and in ShopifyQL queries. The capability works for customer, order, product, and product‑variant metafields, and for metaobjects that contain at least one analytics‑compatible field type.
Who Needs to Pay Attention?
If you’re a Shopify app developer who builds custom metafields or metaobjects—think loyalty tiers, ingredient lists, or custom pricing rules—this update directly impacts your workflow. Merchants who rely on Shopify’s native reporting or who write ShopifyQL queries will immediately benefit from richer data without any extra setup. In short, developers get a simpler deployment path, and merchants gain deeper insights with zero extra configuration on their end.
How to Enable analytics_queryable in shopify.app.toml
Open your app’s shopify.app.toml and add the capabilities.analytics_queryable field to any metafield or metaobject definition you want to expose. Below is a minimal example for a customer metafield and a metaobject representing an ingredient. Note the boolean true value—once the app is deployed, Shopify will push these definitions to every installed shop.
toml
[customer.metafields.app.membership_level]
name = "Membership level"
type = "single_line_text_field"
capabilities.analytics_queryable = true
[metaobjects.app.ingredient]
name = "Ingredient"
capabilities.analytics_queryable = true
[metaobjects.app.ingredient.fields.name]
type = "single_line_text_field"
name = "Name"
[metaobjects.app.ingredient.fields.calories]
type = "number_integer"
name = "Calories"
After updating the TOML, run shopify app deploy as you normally would. Shopify’s deployment pipeline distributes the new definitions automatically, so there’s no manual API call or post‑install script needed. Remember to version your app (e.g., bump the version field in the TOML) so stores receive the update promptly.
Best Practices & Gotchas
• Check type compatibility – Not every metafield type is analytics‑compatible. Review the eligible field on the analyticsQueryable capability documentation to ensure your chosen type can be queried. For metaobjects, at least one field must be analytics‑compatible; otherwise the flag is ignored.
• Scope wisely – Expose only the data you truly need in reports. Over‑exposing internal flags can clutter dashboards and potentially impact performance.
• Version control – Keep your TOML definitions under source control. A typo in the capability name (e.g., capabilities.analytics_queryable vs. capabilities.analyticsQueryable) will silently be ignored.
• Test in a dev store – Deploy to a private development store first and verify that the new fields appear as dimensions in the Analytics UI and can be referenced in ShopifyQL queries like SELECT COUNT(*) FROM orders WHERE customer.metafields.app.membership_level = 'Gold';
Next Steps for Developers
Impact on Merchants
From a merchant’s perspective, the change is invisible until they open the Analytics dashboard or write a ShopifyQL query. Once the app is updated, they’ll see new filter options (e.g., “Membership level” under Customer attributes) and can slice reports by custom ingredient calories, loyalty tier, or any other analytics‑queryable field you’ve exposed. This opens the door to more granular cohort analysis, inventory forecasting, and personalized marketing without any additional app configuration.
Conclusion & Call to Action
Enabling analytics_queryable via your app’s TOML is a small change with a big payoff: richer data for merchants and a smoother workflow for developers. Update your definitions today, redeploy, and watch your customers gain deeper insight into the custom data you help them collect. Need help testing the new capability or crafting ShopifyQL queries? Drop a comment below or reach out to our Shopify developer community for hands‑on support.
