Shopify Dev Dashboard: Function Run Logs Now Visible Based on App Access Scopes

Table of Contents

1. Key Highlights
2. Introduction
3. How run-log visibility is determined
4. Which scopes control what you see
5. Requesting and managing scopes: what to do and when
6. Protected customer data: approval, handling, and developer responsibilities
7. Practical debugging workflows using the Dev Dashboard run logs
8. How to request new scopes dynamically (practical steps)
9. Operational and product decisions: when to ask for scopes and when not to
10. Security, privacy, and compliance: rules to follow when accessing run logs
11. Developer workflows and team responsibilities
12. Migration checklist for existing apps and stores
13. Troubleshooting: Why you might not see run logs
14. Example scenarios and sample implementations
15. Communicating scope requests to merchants: templates and principles
16. Long-term considerations for app ecosystems and merchants
17. Checklist: ensure you see run logs when you need them
18. FAQ

Key Highlights

• Function run logs in the Shopify Dev Dashboard are now visible to apps automatically when the app has the access scopes required by the function's input query.
• Developers must request the correct access scopes—regular, protected customer data, or optional—during installation or dynamically, and handle sensitive data according to Shopify’s requirements.
• Follow a clear checklist for scope requests, use optional scopes for temporary debugging, and adopt strict logging and retention practices to protect customer privacy and simplify support.

Introduction

Developers building Shopify apps no longer need to ask merchants to manually share function run logs. The Dev Dashboard displays a function’s run details to an app whenever that app holds the access scopes required by the function’s input query. That change reduces friction for debugging and support, but also shifts more responsibility to developers to request only necessary scopes and to handle any visible data appropriately.

This article explains how the new visibility rule works, which scopes matter, how to request scopes (including optional and protected customer data scopes), practical debugging workflows, and the security, privacy, and operational practices teams should adopt. The guidance is practical: step-by-step checks, sample OAuth and scope requests, example scenarios, and troubleshooting advice to ensure you can reliably view run logs when you need them.

How run-log visibility is determined

Function run logs are exposed to your app according to the access scopes granted by the merchant. The key rule: the Dev Dashboard checks the function’s input query to determine which fields the function received; if your app has the GraphQL Admin API scopes required to read those fields, the corresponding run details are shown.

What that means in practice:

• If a function’s input includes non-sensitive fields (for example, product IDs or line item quantities) and your app has the corresponding read scopes, you will see the run details automatically.
• If the input query includes protected customer fields—names, addresses, or other personally identifiable information (PII)—your app must have the approved protected customer data scopes in addition to the standard read scopes.
• If your app lacks the necessary scope for any field referenced in the input query, the Dev Dashboard will not surface that run detail.

This behavior enforces the same least-privilege access expectations that the GraphQL Admin API implements for apps, but applied to visibility inside the Dev Dashboard.

Which scopes control what you see

Scopes in Shopify control what your app can query via the Admin APIs. For run logs, the same scopes determine what parts of a function’s input and output your app can view in the Dev Dashboard. Scopes fall into three practical categories:

• Standard API scopes: These are the typical read and write scopes such as read_products, write_orders, read_orders. They grant access to non-protected resource data.
• Protected customer data scopes: Certain customer fields require explicit protected-data approval from Shopify as well as merchant consent. Examples include customer addresses and other PII elements. Shopify’s protected-customer-data flow requires additional review and data-use justification during app submission or an approval step for the requested fields.
• Optional (dynamic) scopes: These can be requested dynamically after installation, and merchants can grant or revoke them without reinstalling the app. Optional scopes are appropriate for ad-hoc needs like debugging or temporary features.

Practical mapping examples

• A function that ingests cart contents and product metadata will surface logs if your app has read_products or read_product_listings privileges (depending on which fields the input query references).
• A function whose input query includes customer.addresses or customer.email will require the corresponding protected customer data scope before those fields appear in the run log.
• A run that contains only non-customer order IDs and line items will be visible as long as read_orders (or equivalent) is present.

If you need a concrete reference, Shopify’s access scopes documentation explains how to declare and request scopes: https://shopify.dev/docs/api/usage/access-scopes. For protected customer data procedures and approvals, see: https://shopify.dev/docs/apps/launch/protected-customer-data.

Requesting and managing scopes: what to do and when

To ensure you can see run logs for functions your app depends on, follow a measured scope strategy that prioritizes the minimum permissions necessary and uses optional scopes where appropriate.

1. Request core scopes during installation Declare the scopes your app consistently needs in the OAuth flow or in your app manifest. For example, include read_orders or read_products in your installation authorization request if your app needs to handle those resources routinely.

Typical OAuth authorize URL (example): GET /admin/oauth/authorize?client_id={API_KEY}&scope=read_products,read_orders&redirect_uri={REDIRECT_URI}&state={STATE}

When merchants approve these scopes at installation, your app can access those fields consistently and the Dev Dashboard will show run details that reference them.

2. Request protected customer data scopes when required Protected customer fields require an approval process. If your app must access customer addresses, names, or other sensitive attributes, prepare the justification and follow Shopify’s protected customer data documentation (https://shopify.dev/docs/apps/launch/protected-customer-data). That process normally requires:

• Detailing why each protected data field is needed.
• Showing how the data will be stored, processed, and deleted.
• Demonstrating adherence to Shopify policies and applicable regulations.

After Shopify approval and merchant consent, those fields will be visible in run logs.

3. Use optional scopes for temporary or debugging access When you need a scope intermittently—such as for diagnosing a problem in a merchant store—request it as an optional or dynamic scope. Shopify supports requesting new scopes dynamically after installation. This triggers a consent prompt for the merchant; they can grant or revoke the optional scope at any time without reinstalling the app.

Dynamic scope request example (conceptual):

• Redirect merchant to the OAuth authorize endpoint with the new scope parameter.
• Merchant approves the scope; your app obtains the additional access token or updated token.
• The Dev Dashboard will then surface run logs that include fields protected by the newly granted scope.

Guidance for optional scopes:

• Use optional scopes only for short-lived needs.
• Provide a clear explanation to the merchant when requesting an optional scope (what you need, why, how long).
• Revoke or stop using the optional scope as soon as the issue is resolved.

4. Verify scopes after grant Once a scope is granted, the run details become visible the next time you access the log. If visibility does not appear, perform the troubleshooting checklist (below).

Protected customer data: approval, handling, and developer responsibilities

Protected customer data is a special category. Fields that reveal PII—addresses, full names, sometimes phone numbers and emails—require more than the typical read scope. Shopify requires both merchant consent and an approval process for developers.

Approval and justification

• Document exactly which protected fields your app needs.
• Explain the use case: why the app must access that exact field as part of its core functionality.
• Describe how the data will be stored, who can access it internally, and when and how it will be deleted.
• Show compliance measures: encryption at rest and in transit, limited retention, access controls, and audit logs.

Operational obligations after approval

• Follow Shopify’s rules for deletion and data minimization. If an end user requests deletion, you must honor it and remove the data from your systems.
• Encrypt sensitive values and restrict exposure to a minimal set of engineers with a business need.
• Avoid logging PII into third-party logging systems unless explicitly required and consented to by the merchant. If you must persist logs that contain PII, treat those logs with the same protections as production customer records.

Impact on run logs

• Once you have Shopify approval and merchant consent, protected fields referenced in a function’s input query will be visible in the Dev Dashboard.
• Developers must still follow safe logging practices. Just because a field is visible does not mean it should be written into persistent logs or forwarded.

Practical debugging workflows using the Dev Dashboard run logs

Run logs are effective for diagnosing errors in functions, understanding data flows, and validating inputs and outputs during feature rollout. Here are recommended workflows that leverage the new visibility behavior while limiting access scope creep.

Scenario: A discount function returns unexpected results for certain customers

• Likely inputs: cart items, customer ID, customer tags, shipping address.
• First check: Does your app have read_orders/read_customers or the protected customer data scopes needed to see the shipping address and customer tags in the run log?
• If not present: Request the minimal additional scope. Use an optional scope if this is a one-off debugging session.
• Once scope is granted: Inspect the Dev Dashboard run log for the function invocation. Confirm whether the input query included the customer address or tags and whether those values match expectations.
• Resolve: If you find incorrect input (e.g., missing customer tags), fix the function or upstream logic. If behavior is caused by missing data, document and apply data validation before invoking the function in future.

Scenario: A fulfillment function times out on a subset of orders

• Likely inputs: order ID, line items, shipping zone.
• Check scopes: Ensure your app has read_orders. If the input query references customer addresses, confirm protected customer scopes as above.
• Diagnostic steps:
  • Use the run log to view execution time, function input size, and any error payloads.
  • If the function produces verbose logs, prefer ephemeral optional scopes or debug mode to avoid long-term exposure of internal traces.
  • Reproduce in a development or staging store when possible and capture the minimal failing order payload.

Best practices for debugging

• Reproduce errors in a development store with sanitized data when possible.
• Use optional scopes for debug sessions in merchant stores.
• Add structured, levelled logging inside your functions (info, warn, error), but avoid logging PII.
• Use unique run identifiers in function output so errors reported by merchants can be matched quickly to Dev Dashboard entries.
• Rotate any credentials and limit staff access following a debug session that required expanding permissions.

How to request new scopes dynamically (practical steps)

Shopify lets apps request new permissions after installation. This is the right mechanism for optional scopes.

Step-by-step:

1. Build the authorize URL with additional scopes you need. Include the merchant’s shop domain and your client ID, redirect URI, and state.
2. Redirect the merchant to that URL. Shopify will display a consent screen for the new scope(s).
3. On merchant approval, Shopify redirects back to your redirect URI with a code. Exchange that code for an access token as you did at installation.
4. Update your app to use the expanded token for subsequent API calls.

Developer UX tips:

• Provide a concise explanation on the consent page about why you request the new scope and how long you’ll use it.
• Offer an alternative: allow merchants to send sanitized example payloads if they are uncomfortable granting additional access permanently.
• Keep the number of required steps minimal: an opaque or confusing flow discourages merchants from granting the scope, which can delay debugging.

Reference: manage access scopes and request new access scopes dynamically: https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes#request-new-access-scopes-dynamically

Operational and product decisions: when to ask for scopes and when not to

Developer teams must make conscious product decisions about what to request at install time and what should be optional.

Guiding principles:

• Request only what you need for core functionality at installation.
• Use optional scopes for administrative or debugging features that are not central to the app’s value proposition.
• Treat protected customer data as a high bar: only request it if a feature cannot function without it.
• Explain clearly to merchants the specific benefit that granting each additional scope delivers.

Examples of reasonable defaults

• An inventory sync app should request product and inventory read/write scopes at install, because core functionality depends on these permissions.
• A marketing analytics app that can function without customer addresses should avoid protected customer data at install and request it only if the merchant opts into advanced customer-level reporting.

Merchant-facing language examples When requesting an optional scope for debugging, provide a short explanation like: "We need temporary access to customer shipping addresses to diagnose a checkout issue for your store. This scope will only be used for debugging and will be revoked once the problem is fixed."

This kind of transparency increases merchant trust and reduces hesitancy around granting temporary access.

Security, privacy, and compliance: rules to follow when accessing run logs

Visibility of run logs brings sensitivity because logs may surface customer data. Your development and security processes must reflect that.

Logging hygiene and PII

• Avoid logging full customer data unless required. Mask or redact PII fields when possible (e.g., show last 4 digits of a phone number).
• If your logs must contain PII for debugging, mark them as sensitive and restrict access.
• Prefer ephemeral storage for debug logs. Delete debug logs automatically after a short retention period (e.g., 7–30 days depending on your policy and merchant agreements).

Encryption and access control

• Encrypt sensitive data at rest and in transit.
• Limit employee access to PII to those with a business need. Maintain an access control list and use role-based access control (RBAC).
• Log access to sensitive logs for internal auditing.

Retention and deletion

• Implement policies for retention and deletion consistent with Shopify rules and applicable laws (GDPR, CCPA, etc.).
• If a merchant or customer requests data deletion, ensure corresponding logs are purged or redacted to honor the request.
• Keep a record of deletion actions to demonstrate compliance if necessary.

Breach readiness

• Maintain an incident response plan that covers unauthorized access to logs containing PII.
• Communicate breach steps to merchants and affected customers according to legal obligations.

Compliance and app review implications

• If your app requests protected customer data, Shopify reviews your use case and may require specific safeguards.
• Be prepared to provide Shopify with technical details about storage, encryption, deletion policies and to demonstrate that only necessary staff can access the data.

Developer workflows and team responsibilities

Integrating run-log visibility into your engineering and support flows requires a few organizational adjustments.

Support teams

• Train support staff to ask for minimal information and to advise merchants about optional scope requests.
• Provide a scripted merchant education flow: explain the scope, why it’s needed, and how long it will be used.

Engineering teams

• Add tooling to check token scopes programmatically. This helps you decide whether missing run logs are a permission issue.
• Add telemetry that correlates function run failures with missing scope errors to accelerate root-cause analysis.
• Use feature flags to toggle verbose debug logging that may require optional scopes so you can avoid permanent permission expansion.

Product managers

• Catalog use cases that require protected customer data and evaluate whether those features justify the approval effort.
• Create a policy that defines which scopes are requested at install and which are optional, backed by merchant-facing explanations.

Security and compliance

• Schedule periodic reviews of what scopes the app currently holds and whether any can be removed.
• Audit internal access to logs that include protected data and retain audit logs for compliance records.

Migration checklist for existing apps and stores

If you maintain apps that will rely on the new Dev Dashboard visibility behavior, follow this checklist to avoid surprises.

1. Inventory your functions

• Identify each function whose run logs you need to access.
• List the fields referenced in each function’s input query.

2. Map fields to scopes

• For each field, identify the GraphQL Admin API scope required to read it.
• Mark fields that require protected customer data approval.

3. Update installation manifest or OAuth flow

• Add consistent, required scopes to the install request.
• Plan optional scopes for ad-hoc or debugging needs.

4. Prepare protected data justification

• If your app needs protected fields, prepare the required documentation and data security plan for Shopify review.

5. Implement dynamic scope request flow

• Add an in-app flow to request optional scopes from merchants when needed, with clear merchant messaging.

6. Update logging practices

• Adopt redaction and retention policies.
• Ensure that any logs that might become viewable do not leak credentials or more PII than necessary.

7. Test end-to-end

• Install the updated app in a development store and simulate runs that include the targeted input fields.
• Verify that after granting scopes, the Dev Dashboard displays the expected run details.

8. Communicate to merchants

• Explain why the app requests new scopes, how those scopes will be used, and how to revoke them.

Troubleshooting: Why you might not see run logs

If you expect to see run details but don’t, run through these checks.

1. Confirm the input query fields

• Ensure the particular run actually included the fields you think it did. Function input queries vary by invocation.

2. Check your app’s effective scopes

• Programmatically inspect the access token or the app’s installed scopes. Ensure the token includes the scope needed to read the referenced fields.

3. Verify protected customer data approval

• If the fields are customer PII, confirm your app received Shopify approval for the relevant protected data scopes and that the merchant granted consent.

4. Re-request scopes dynamically (optional)

• If the scope is optional and not yet granted, trigger the dynamic OAuth flow and ask the merchant to approve it.

5. Confirm merchant hasn’t revoked scopes

• Merchants can revoke optional scopes or uninstall apps. Confirm the app is still installed and the merchant did not revoke the permission.

6. Use a development store to reproduce

• If merchant consent is constrained, reproduce the same function input against a development store where you control scopes and can iterate quickly.

7. Watch for caching or UI delays

• In some cases, the Dev Dashboard may take a short time to reflect newly granted permissions. Reopen the log or refresh after a brief wait.

8. Inspect API errors

• If you see errors in your app that indicate permission denied or insufficient scope in API responses, handle those errors and surface clear messages to your support team.

Example scenarios and sample implementations

The following examples illustrate common real-world cases and practical code/flow snippets.

Example A: Discount function needs customer tags for eligibility rules

• Function input query includes customer.tags.
• Required scopes: read_customers and protected customer data scope for tags if tags are considered customer-protected in your use case.
• Flow:
  1. At install, request read_customers only if customer-level features are core.
  2. If tags are an advanced feature used rarely, request the protected scope dynamically during merchant troubleshooting.
  3. Provide merchant-facing text: "Grant temporary access to customer tags so we can determine why certain discounts are not applying."

Example B: Shipping-cost calculator needs customer address to determine zone

• Function input query includes customer.addresses[0].country_code.
• Required scopes: protected customer data for address fields.
• Flow:
  1. If shipping calculation requires addresses for core functionality, request and document protected data approval up front.
  2. Otherwise, fall back to asking merchants to provide a sample address or request optional scope for diagnosis.

Sample OAuth authorize URL for requesting dynamic scopes (GET example) https://{shop}.myshopify.com/admin/oauth/authorize?client_id={API_KEY}&scope=read_customers,read_orders&redirect_uri={REDIRECT_URI}&state={STATE}

After merchant approval, exchange the code for an access token as usual.

Sample GraphQL Admin API check for scopes (conceptual)

• Use the admin API to query whether protected fields are accessible by trying a minimal read; handle permission errors gracefully and present a clear prompt asking for the additional scope.

Note: Do not log the entire customer object in persistent logs. Mask or redact fields whenever possible.

Communicating scope requests to merchants: templates and principles

Merchant trust matters. Poor wording or opaque requests reduce consent rates. Use the shortest possible message that explains the value and duration.

Consent message templates

Temporary debug request: "We need temporary access to customer shipping addresses to diagnose a checkout problem you reported. This access will be used only for troubleshooting and will be revoked after we confirm the fix."

Feature opt-in: "To enable advanced customer-level reporting, this app requires access to customer names and addresses. Your data will be encrypted, accessed only by authorized staff, and can be deleted upon request."

Principles for communication

• State the value clearly (what problem you will fix).
• Specify duration (temporary vs ongoing).
• Offer an alternative (merchant can share a sanitized sample payload).
• Provide a clear revocation path (how to remove or revoke the scope).

Long-term considerations for app ecosystems and merchants

The change that surfaces run logs based on granted scopes simplifies developer support and reduces friction. It also reinforces the importance of permission hygiene.

For developers:

• Plan for fewer merchant support interactions regarding logs. That saves time but increases the need for a strong permission model.
• Invest in tooling to monitor what scopes your app currently holds.
• Treat optional scopes as part of your product’s security lifecycle—plan for revocation and auditing.

For merchants:

• Expect some apps to request optional or protected scopes for debugging.
• Insist on clear explanations and temporary access whenever possible.
• Use Shopify’s app management controls to review and revoke scopes that are no longer needed.

For Shopify:

• This change streamlines troubleshooting across the platform and aligns Dev Dashboard visibility with existing API access controls.
• It encourages safer scope usage: visible data corresponds to authorized scopes.

Checklist: ensure you see run logs when you need them

• Inventory function input queries and map required fields to scopes.
• Add consistent required scopes to your installation OAuth flow.
• Identify protected customer data needs and prepare Shopify approval documentation where necessary.
• Implement a dynamic scope request flow for optional scopes.
• Build merchant-facing consent messages explaining why the extra access is needed.
• Enforce logging hygiene—mask/redact PII and limit retention.
• Test in development stores and reproduce runs with expected inputs.
• Set up alerts for run failures and automated reports to tie failures to missing scopes.
• Document in your support playbook how to request scopes from merchants and how to respond when run logs are not visible.

FAQ

Q: Why don’t I see a function run log in the Dev Dashboard even though the function ran? A: The Dev Dashboard shows only the run details that your app has permission to read. Confirm the function’s input query includes the fields you expect, then verify your app has the GraphQL Admin API scopes required to read those specific fields. If a field is protected customer data, ensure Shopify approval and merchant consent have been obtained.

Q: What is a protected customer data scope and when do I need it? A: Protected customer data scopes control access to PII such as customer addresses or other sensitive customer information. Request these scopes when your app’s feature cannot function without the actual customer data (not just an ID). Shopify requires additional justification and may review your data handling procedures before granting approval.

Q: How do I request a scope dynamically without making the merchant reinstall the app? A: Use Shopify’s dynamic scope request flow: redirect the merchant to the OAuth authorize endpoint with the additional scope parameter. After the merchant approves the new scope, exchange the returned code for an updated token and begin using the expanded permissions.

Q: Should I use optional scopes for debugging? A: Yes. Optional scopes are suitable for temporary, ad-hoc needs such as debugging. They allow merchants to grant and revoke permissions without reinstalling the app. Use them with clear merchant messaging and revoke access or stop using the scope after debugging concludes.

Q: Are run logs a permanent record I should store? A: Treat run logs with care. Avoid storing PII from run logs permanently. If logs include sensitive information, store them only temporarily, restrict access, encrypt them, and purge them according to your retention policy and legal obligations.

Q: How do I convince a merchant to grant an optional or protected scope? A: Provide a concise explanation of exactly what you need, why it’s required, how long you will use it, and how you’ll protect the data. Offer alternatives like submitting a sanitized payload. Transparency and a clear, limited scope usually increase merchant consent.

Q: What should my internal team do after being granted protected customer data access? A: Limit access to authorized personnel, encrypt stored sensitive data, maintain audit logs that record who accessed it and why, and implement deletion workflows that honor merchant and customer deletion requests.

Q: If a merchant revokes a scope mid-debug, what happens? A: Your app will no longer be able to read the fields guarded by that scope. Any future attempts to access those fields will fail with a permissions error. Build error handling to inform your support team and the merchant that the session ended and, if needed, start a re-authorization flow.

Q: Where can I get more detailed technical instructions for scopes and protected customer data? A: Shopify’s developer documentation is the authoritative resource:

• Access scopes: https://shopify.dev/docs/api/usage/access-scopes
• Protected customer data: https://shopify.dev/docs/apps/launch/protected-customer-data
• Request new access scopes dynamically: https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes#request-new-access-scopes-dynamically

Q: Will the Dev Dashboard expose data to other apps or third parties? A: The Dev Dashboard surfaces run details only to the app that holds the appropriate access scopes. Other apps do not gain visibility unless they have separately been granted the necessary scopes by the merchant.

Q: How long after granting a scope will I see run logs? A: Once the merchant grants the scope, run details that reference the newly accessible fields will be visible the next time the function runs and the Dev Dashboard refreshes its logs. If you still do not see the expected data, follow the troubleshooting checklist.

Q: Any quick tips to reduce merchant friction when requesting scopes? A:

• Ask only for what you need.
• Phrase the request around problem resolution.
• Offer to revoke access after debugging.
• Provide a clear privacy and deletion promise.

Adopt these practices to reduce friction and accelerate support.

---

The Dev Dashboard update simplifies access to function debug data but also raises the bar on how apps request and handle permissions. Treat scope requests as product design decisions: ask only for what is essential, keep merchants informed, enforce strict data protection controls, and use optional scopes for temporary needs. Following the checklist and best practices above will reduce support time, improve merchant trust, and ensure your team sees the function run logs it needs—securely and responsibly.