Shopify Admin Intents Now Support Settings: Direct Apps to Specific Admin Settings Pages

Table of Contents

1. Key Highlights
2. Introduction
3. What Admin Intents Are and Why Settings Support Changes the Game
4. Which Settings Intents Are Available Today
5. How Settings Intents Work Under the Hood
6. Real-World Examples: How Merchants Benefit
7. Implementation Guide: Invoking Settings Intents from Your App
8. UX Design: How to Use Settings Intents Without Disrupting Merchants
9. Security, Scopes, and Permissions
10. Testing, Verification, and Monitoring
11. Migration from Deep Links: Why and How to Move Your Flows
12. Limitations, Edge Cases, and What Developers Should Expect Next
13. Best Practices for Developers Adopting Settings Intents
14. Case Study: Turning a Setup Task into a One-Click Action
15. How to Report Feedback or Request Additional Intents
16. FAQ

Key Highlights

• Shopify’s Admin Intents feature now supports Settings, allowing apps to open specific Settings pages with a single API call and land merchants directly on the targeted settings card.
• Supported intents include Store, Order, and Locations settings (create/edit flows and defaults), reducing the need for fragile deep links and manual navigation instructions.
• The change streamlines configuration flows, improves merchant focus, and reduces friction for tasks such as creating locations or updating order processing rules; developers should adopt intent-based navigation, add fallbacks, and validate permissions.

Introduction

Apps that integrate with Shopify frequently need to guide merchants to the right spot in the admin to finish configuration or manage store options. Historically this required deep links or step-by-step instructions, both brittle and noisy for merchants. Shopify has extended Admin Intents to include Settings pages. From a single API call, an app can now open a specific Settings route inside the Shopify admin and land the merchant on the exact card they need to interact with. That removes guesswork, reduces clicks, and makes configuration flows far more reliable.

This article explains what the Settings support for Admin Intents delivers, which Settings areas are available today, how the feature works under the surface, and practical developer and UX guidance for using intents in production. It also covers migration from deep links, testing and monitoring recommendations, security considerations, and common pitfalls to avoid.

What Admin Intents Are and Why Settings Support Changes the Game

Admin Intents let apps express what action they want the merchant to take—create, edit, or review—without prescribing an exact URL. The admin interprets the intent and opens the appropriate page. Previously, intents could launch product, order, and other flows. Settings pages required deep links: full admin URLs that pointed to specific pages and sometimes to particular UI fragments. Deep links work, but they break easily when the admin UI changes, and they require apps to maintain a mapping between features and URLs.

Settings support for Admin Intents changes this pattern. Instead of generating and shipping a deep link, an app issues a Settings intent. The Shopify admin opens the appropriate Settings route inside the page stack and scrolls to the card that the intent targets. The merchant arrives at the correct place instantly, within the normal admin navigation experience. This reduces the number of integration points apps have to maintain and lowers the chances of broken navigation when Shopify iterates on the admin.

The practical implications are significant:

• Configuration workflows are smoother: merchants receive a single link or button and proceed directly to the right Settings card.
• Developer maintenance drops: apps no longer have to update deep-link mappings whenever the admin changes.
• UX consistency improves: the merchant remains within the admin page stack and experiences the expected visual context and navigation.

Which Settings Intents Are Available Today

The initial rollout targets common, high-value settings areas that apps frequently need merchants to visit. Current supported Settings intents include General store settings, Order settings, and Location-related flows. Each intent follows a naming convention that indicates the action and the area, for example edit:settings/StoreDetails.

Supported intents include:

General

• edit:settings/StoreDetails — Opens Store Details.
• edit:settings/StoreDefaults — Opens Store Defaults.
• edit:settings/OrderIdFormat — Opens Order ID Format.
• edit:settings/OrderProcessing — Opens Order Processing.

Locations

• create:shopify/Location — Opens the create Location flow.
• edit:shopify/Location — Opens the edit Location flow.
• edit:settings/LocationDefault — Opens the Location Default settings.

These intents cover both navigational edits (edit:settings/...) and resource creation flows (create:shopify/Location). The admin maps these intent names to the correct Settings page and the specific card within the page. Shopify can extend this list over time; apps should design for graceful failure when an intent is not recognized.

How Settings Intents Work Under the Hood

Invoking a Settings intent triggers the Shopify admin to open a Settings route inside a "page stack," an internal pattern the admin uses to layer pages. The page stack maintains context: the previous page remains in the stack while a new page is shown on top. This keeps the back button behavior predictable.

When an app invokes a Settings intent:

1. The app issues the intent through the Intents API (or the platform mechanism exposed by Shopify).
2. The Shopify admin receives the intent and determines the corresponding Settings route.
3. The admin opens the Settings route within the page stack.
4. The admin scrolls automatically to the targeted settings card so the merchant lands directly on the relevant section.
5. If the intent references a resource (for example, edit:shopify/Location where an ID might be included), the admin will open the edit flow for that resource.

This approach separates intent from implementation details such as internal route paths or element IDs. Shopify handles the mapping, which reduces coupling between third-party apps and the admin UI.

Because the admin manages the navigation, the merchant’s experience is identical to manually navigating to Settings and selecting the card—except that the app has eliminated the extra steps.

Real-World Examples: How Merchants Benefit

The abstract benefits become concrete when you look at how merchants and apps use Settings intents in practice.

Example 1 — Sidekick streamlines setup Sidekick, a setup and onboarding app, sends merchants a link that opens the exact Settings card where a store needs to configure an integration or set a default. Instead of telling the merchant to "go to Settings > Store > Defaults and update your currency," Sidekick links to the Store Defaults card. The merchant clicks once, finishes configuration, and returns to the onboarding flow.

Example 2 — Location creation for fulfillment apps Fulfillment or POS apps often require merchants to register physical locations. Rather than instructing merchants to navigate through Settings > Locations and click Add location, an app can open the create:shopify/Location intent. The admin opens the Add location modal or page, and the merchant completes the creation without leaving the flow.

Example 3 — Order processing rules for shipping apps Shipping and order management apps can open edit:settings/OrderProcessing to get merchants to the controls that determine how orders are auto-fulfilled or routed. This is particularly useful when app functionality depends on a specific Order Processing configuration. The merchant can update the rules, and the app can pick up the new behavior without requiring additional steps.

Example 4 — Store defaults after a policy change When new regulations or payment provider requirements demand an update to order ID formats or store defaults, an app can push an intent-based banner or prompt that lands the merchant directly on edit:settings/OrderIdFormat. Merchants can then make the necessary adjustments immediately.

These examples show that intents reduce friction in critical flows where merchants must perform administrative actions. The feature benefits both one-off tasks (create a location) and ongoing configuration steps tied to app functionality.

Implementation Guide: Invoking Settings Intents from Your App

The Intents API exposes a way to request that the Shopify admin open a given route based on a named intent. Implementation details differ based on SDKs, frameworks, and hosting models, but the overall pattern is consistent: send an intent name and optional contextual data to the Intents API and present the resulting navigation to the merchant.

High-level example (pseudo-code)

• Prepare the intent payload:
  • intent: a string such as "edit:settings/StoreDetails".
  • context: optional metadata (for analytics or to aid the admin).
  • resource identifiers: where relevant (for example, a location ID for edit:shopify/Location).
• Send the payload to the Intents API endpoint.
• Handle the response: the admin will open the appropriate Settings page. If the API returns an error because the intent is not available or the merchant lacks permissions, fall back to an alternate UX.

JavaScript pseudo-example:

// /api/trigger-intent endpoint on your app server
app.post('/api/trigger-intent', async (req, res) => {
  const { intent, resource } = req.body;

  const payload = {
    intent,
    context: {
      source: 'app_name',
      note: 'Triggered from in-app onboarding',
    },
    resource, // optional, e.g., { id: 'gid://shopify/Location/123' }
  };

  // Replace with the official Intents API call as documented by Shopify
  const result = await shopifyIntentsClient.invoke(payload);

  res.json(result);
});

Important integration considerations

• Use the official SDKs or API client provided by Shopify where available. Those libraries handle authentication and the exact API surface, which changes across API versions.
• Include context metadata where it helps your analytics and support teams identify the intent source.
• For create flows (e.g., create:shopify/Location), provide minimal context so the admin shows the correct modal or route.
• For edit flows that require an identifier, ensure the identifier format matches what the admin expects (for example, global IDs or numeric IDs depending on the API).
• Avoid hardcoding admin URLs. Rely on intent names and let the admin resolve routing.

Fallback strategies Intents are resilient, but your integration must handle cases where:

• The merchant’s admin version does not support the requested intent (for older or restricted accounts).
• The merchant lacks permission to perform the action.
• The intent name is unsupported or misspelled.

Fallback implementations should:

• Present the merchant with a human-friendly message and an alternate path (for example, a link to the relevant Settings index page).
• Offer clear instructions if the app cannot open the Settings page directly.
• Log the failure and surface it to your support or analytics system to track usage and issues.

UX Design: How to Use Settings Intents Without Disrupting Merchants

Intents improve the merchant experience only if they are used thoughtfully. Intent-triggered navigation should feel natural and minimal.

Where to place intent-based navigation

• Onboarding screens: when your app needs a merchant to configure a store setting before continuing, provide a single "Open settings" button that triggers the intent.
• Error recovery: when an operation fails because of a misconfigured store setting, display a button that takes the merchant to the exact card to fix the problem.
• Setup checklists: provide intent links for each checklist item so merchants can complete tasks in one click.

Copy and affordances

• Label the call-to-action clearly (e.g., "Open Store details" or "Add location") so merchants understand they will be taken to a Settings page.
• Indicate that the action opens the Shopify admin page stack. Merchants expect to remain in the admin; avoid surprising them by opening external windows unless necessary.
• Give a brief reason for the navigation so the merchant understands the need: “Update your order processing rules to allow automated fulfillment.”

Preserving context

• If your app opens the admin for configuration as part of a multi-step flow, provide a return path. Use your app’s UI to remind merchants how to return to the app after finishing Settings changes.
• For modal-based create flows (like adding a Location), ensure the merchant knows whether they must save changes in the admin before the app resumes any dependent workflows.

Accessibility and focus

• Rely on the admin’s native behavior for focus and accessibility. Since the admin applies the scroll and card highlight, the merchant should get appropriate focus cues.
• Ensure your prompts are keyboard-accessible and that any status messages in your app reflect the result of the Settings update.

Minimal but clear guidance

• Avoid long, prescriptive instructions when the intent lands merchants at the correct card.
• If the Settings card contains multiple options, use your app’s context to suggest the specific field or action the merchant should change.

Security, Scopes, and Permissions

Opening a Settings page does not bypass permission checks. Apps must respect the merchant’s roles and admin privileges.

Permissions model

• The Settings pages typically require authenticated admin access. The Intents API invocation should occur in a context where the merchant is signed in and has permission to view or edit the targeted Settings area.
• If the merchant lacks sufficient permissions, the admin will either refuse the intent or open the page in read-only mode. Your app should detect this and provide instructions or an alternate flow.

Least-privilege approach

• Request only the scopes your app needs to function. Intent-driven navigation does not change permissions, but it can reveal workflow gaps if your app assumes the merchant can perform edits that require elevated permissions.
• For actions that require a higher privilege level, consider explaining to merchants why permission is needed and how they can complete the setting update (for example, have an owner perform the change).

Handling declined access

• Detect denied permissions and present a clear call to action, such as a shareable note to the account owner explaining what needs to be changed.
• Provide a fallback path: either an alternate workflow that does not need the setting change, or detailed instructions for the person who can make the change.

Security best practices for developers

• Never embed admin auth tokens in client-side code.
• Use server-side invocation where the Intents API demands it and ensure tokens are short-lived and rotated.
• Validate any resource identifiers on your server to prevent injection or tampering.

Testing, Verification, and Monitoring

Testing intent-driven navigation across real merchant accounts provides confidence that the UX is stable.

Testing checklist

• Validate invocation under different merchant roles (owner, staff with limited rights) and ensure the admin reacts correctly.
• Test each supported intent for both create and edit flows.
• Test error responses when an intent is malformed or unsupported.
• Validate behavior on desktop and mobile admin interfaces; the admin may present the Settings route differently on narrow screens.

Test scenarios to consider

• Merchant already configured: app should handle idempotency. If the setting is already correct, do not demand unnecessary changes.
• Resource not found: for edit-intents with IDs, handle the case where the resource no longer exists.
• UI changes: while intents minimize fragility, monitor for changes in the Settings card layout that may affect the merchant’s ability to complete a task.

Monitoring and analytics

• Log every intent invocation with metadata: which intent, which merchant/shop, timestamp, and success/failure status.
• Correlate intent events with downstream outcomes (did the merchant complete the setup, did a later API call succeed, etc.).
• Track failed intent invocations to identify areas where fallback UX should be improved or where an unsupported intent was attempted.

Customer support signals

• Capture context about which intent was triggered when a merchant contacts support. This speeds troubleshooting and improves the accuracy of support responses.
• Include an option for merchants to report that the intent did not land them where they expected; surface these reports into a support queue.

Migration from Deep Links: Why and How to Move Your Flows

If your app currently relies on deep links into the admin Settings pages, migrating to Settings intents reduces maintenance and improves reliability.

Benefits of migrating

• Intents abstract away internal routes and element identifiers.
• Intent-based navigation adapts as Shopify changes the admin UI.
• Click-to-configure flows become easier to instrument and standardize.

Migration steps

1. Inventory your deep links: identify every flow that links merchants into Settings pages.
2. Map each deep link to an equivalent Settings intent (e.g., deep link to Settings > Store > Defaults -> edit:settings/StoreDefaults).
3. Replace the deep link with an intent invocation where possible.
4. Implement fallbacks for environments that do not support the intent.
5. Monitor for errors and refine UX messaging if the admin opens a read-only view due to permissions.

Fallback guidance

• If an intent is unsupported in a merchant’s account, provide either a link to the top-level Settings index or adaptive in-app instructions that guide the merchant step-by-step.
• Consider showing a short in-app overlay explaining why the app attempted to open a Settings page and what the merchant should do if they cannot complete it.

Handling legacy deep links

• Retire most deep links after testing, but keep a subset as fallback links while the migration stabilizes.
• Avoid sending legacy deep links in emails or external communications; prefer intent-based links that the admin will handle when opened from within the logged-in context.

Limitations, Edge Cases, and What Developers Should Expect Next

Current support covers a targeted set of Settings areas. Developers should expect the list of supported intents to expand over time, but they must design integrations defensively.

Known limitations

• Intent coverage: not every Settings page is supported yet. If your app needs an unsupported page, continue using an appropriate fallback.
• Admin UX variations: the way a settings card is presented may differ across admin versions or screen sizes. The admin will attempt to scroll and focus, but layout differences may affect exact presentation.
• Declarative intent naming: intent names are explicit strings. Typos or incorrect intent names will yield errors. Validate intent strings against the official Intents API reference.

Edge cases

• Multi-step Settings pages: some admin pages require intermediate confirmations; intents will land the merchant at the correct card but cannot complete multi-step interactions automatically.
• Resource scoping: for edit intents that require resource identifiers, ensure those identifiers remain valid and available to the merchant.
• App-specific needs: if your app requires that a certain field be set to a precise value, consider building an API-driven check after the merchant finishes their admin changes, and present a success/failure summary back in the app.

Anticipated extensions

• Broader Settings coverage: Shopify is likely to add additional settings intents as demand rises.
• Intent parameters: future enhancements may allow richer context to be passed, such as pre-filling non-sensitive fields or opening specific subsections.
• Standardized telemetry: Shopify and app developers may converge on common analytics events tied to intents to measure setup conversion rates.

Best Practices for Developers Adopting Settings Intents

These practices reduce friction and ensure robust, merchant-friendly experiences.

Design for idempotency

• Re-run checks after the merchant returns from a Settings intent to verify that required changes were applied.
• Avoid prompting merchants to perform the same action multiple times if not needed.

Use context and analytics

• Pass metadata with each intent invocation. Track which onboarding tasks drive the most completed configurations.
• Use analytics to optimize the flow: track conversions and time to complete settings changes.

Graceful error handling

• Show clear fallback instructions if the intent fails. Provide a path for merchants to report what happened.
• Don’t block the merchant from continuing entirely if a setting cannot be changed immediately; provide alternate configuration options where possible.

Communicate clearly

• Explain why the merchant is being taken to Settings and what they should expect to do there.
• After the merchant returns, present a succinct success message or next step.

Security hygiene

• Validate all incoming identifiers and data server-side.
• Ensure token exchange and API calls follow Shopify authentication patterns.

Keep dependencies minimal

• Avoid timing your app logic to assume immediate changes: the merchant may take time to update settings. Implement retry and polling strategies where necessary.

Document for support

• Update your support documentation to reference intent-driven flows so merchant-facing teams can assist when things do not behave as expected.

Case Study: Turning a Setup Task into a One-Click Action

To illustrate the practical impact, consider an app that requires the merchant to enable Order Processing settings to allow automatic tagging for fulfillment rules.

Before intents

• The app shows instructions: “Go to Settings > Orders > Order processing. Under the ‘Automatically fulfill orders’ section, add rule X.”
• Merchants navigate manually. Some get lost; others complete the step incorrectly. Support tickets spike.

After intents

• The onboarding screen displays a single button: “Open Order processing.”
• The button triggers edit:settings/OrderProcessing.
• The merchant lands precisely on the Order Processing card, enables the rule, and returns to complete onboarding.
• Conversion to configured state rises, and support tickets drop.

Quantifiable outcomes

• Faster setup: average time to complete the task falls significantly.
• Fewer support requests: the number of tickets related to locating the setting drops.
• Higher activation rate: more merchants complete the onboarding checklist.

This case study shows how intent-based navigation can turn a multistep friction point into a one-click action with measurable benefits.

How to Report Feedback or Request Additional Intents

Shopify encourages developers to provide feedback on intents and request additional Settings areas to be supported. Use the Shopify Developer Community forums and feedback channels to describe which Settings areas you need and why. Include use cases and the expected flow so Shopify can prioritize expansions that benefit a broad set of apps and merchants.

Useful information to include when filing feedback

• Business use cases that require the Settings area.
• Approximate usage numbers or customer impact (e.g., “X% of our merchants require this setting to enable feature Y”).
• Any existing deep links you rely on today and failure modes you have observed.

Responsive product teams typically prioritize high-impact requests that reduce merchant friction and support common app patterns, so detailed, data-backed feedback helps.

FAQ

Q: What exactly happens when I invoke a Settings intent? A: The Shopify admin opens the corresponding Settings route inside the admin’s page stack and scrolls to the targeted settings card. If the intent references a resource, the admin opens the create or edit flow for that resource. The admin enforces permissions and handles presentation for mobile and desktop contexts.

Q: Which Settings intents are supported today? A: Initial support covers several General settings (Store Details, Store Defaults, Order ID Format, Order Processing) and Locations (create and edit Location flows, and Location Default settings). Shopify intends to expand the list over time.

Q: How does this differ from a deep link to a Settings page? A: Intents abstract away route-specific details. Deep links point to a specific admin URL and often break when the admin UI changes. Settings intents express a desired action and let Shopify map that action to the appropriate route and card, reducing maintenance and improving robustness.

Q: What happens if the merchant does not have permission to change a setting? A: The admin enforces permissions. If a merchant lacks the required permissions, the admin will prevent edits and may present a read-only view. Your app should detect this scenario and offer a clear fallback: instructions for the account owner, a request to ask the owner to make changes, or an alternative workflow.

Q: Are there analytics or telemetry hooks when intents are invoked? A: The Intents API supports contextual metadata. Developers should log intent invocations and correlate them with follow-up events (e.g., a webhook or API check that verifies a setting change). Track success/failure and merchant completion metrics in your analytics for product and support insights.

Q: What’s the recommended fallback if an intent is unsupported? A: Present a human-friendly message and either a link to the relevant top-level Settings page or step-by-step instructions. Keep enough context in your UI so the merchant understands what to change.

Q: Can I prefill Settings fields through an intent? A: The current intents open Settings pages or create/edit flows but do not automatically perform edits on behalf of the merchant. For sensitive changes, have the merchant confirm edits directly in the admin. Future extensions could allow richer parameters; consult the official Intents API documentation for updates.

Q: Will Admin Intents break existing deep links? A: Intents should be treated as a replacement for deep links, but Shopify will not automatically rewrite existing deep links in your app. Migrate deep-link flows to intents where possible. Keep a fallback deep link for older flows temporarily while you verify behavior.

Q: How do I test intents during development? A: Use a development store with admin access and exercise intent invocations across roles. Monitor the admin behavior and handle errors. Track intent events in your app logs. Refer to Shopify’s Intents API reference and developer docs for the exact testing endpoints and SDK patterns.

Q: Who do I contact to request broader Settings coverage? A: Use the Shopify Developer Community forums and the appropriate feedback channels. Provide detailed use cases and describe the merchant impact. Concrete examples and usage numbers increase the likelihood that Shopify prioritizes the request.

Q: Where can I find the official documentation for Admin Intents? A: Consult the Admin Intents and Intents API documentation on Shopify’s developer documentation site for the authoritative API reference, supported intent names, and sample code snippets.

Q: Does using intents change my app’s required OAuth scopes? A: No. Invoking an intent does not grant additional privileges. Your app must still use only the scopes it needs. The Shopify admin will check merchant permissions before allowing edits where appropriate.

Q: How should support teams handle merchant questions about intents? A: Train support teams to recognize intent-driven flows, know the likely intent names used by your app, and understand fallback instructions for merchants who cannot complete a requested change. Provide support staff with logs and intent invocation context to speed troubleshooting.

Q: Will mobile admins support Settings intents the same way as desktop? A: The admin determines presentation based on device and screen size. The admin will attempt to open the appropriate route or modal on mobile, but the exact UI may differ. Validate flows on real mobile devices and provide alternative guidance if necessary.

Q: Are there rate limits or quotas on invoking intents? A: The Intents API is subject to Shopify’s standard API rate-limits and policies. Avoid spamming intent invocations from automated processes. Instrument your app to call intents only in response to clear user actions.

Q: What should I log when invoking an intent? A: Log the merchant/shop identifier, the intent name, timestamp, any resource IDs, the outcome (success/failure), and any user-visible messages or errors. Correlate intent logs with subsequent actions that depend on the change.

Q: How quickly does Shopify add new Settings intents? A: There’s no published cadence. Shopify evaluates requests and usage patterns. Developers should provide feedback and track the Intents API changelog to learn about new additions.

---

This article described how Settings support for Shopify Admin Intents reduces friction, lowers maintenance, and improves merchant experience. Implement intents thoughtfully, add robust fallbacks and monitoring, and migrate deep-link flows where appropriate to benefit from more resilient, intent-driven navigation.