Shopify diagnostics

Before uploading Shopify diagnostics

Use this page when a customer-approved Shopify app sends bounded storefront and theme diagnostics into WebRiskOps for a selected project or report. Diagnostics should explain public storefront, theme and app state without requesting staff access, order history, customer records, payment data or write scopes.

• Review Shopify diagnostic evidence
• Confirm the Shopify store, project, optional report and customer account match before upload.
• Keep diagnostics limited to safe read scopes and storefront/theme context that supports the finding.
• Stop when `SHOPIFY_DIAGNOSTIC_REJECTED`, `SHOPIFY_SCOPE_UNSUPPORTED`, `UNAUTHORIZED`, `FORBIDDEN` or `VALIDATION_FAILED` applies.

Upload Shopify app diagnostics

Follow the path `Extensions → Shopify app → Diagnostic preview → Safe read scopes → Evidence upload → Project or report handoff → Use evidence or fallback`.

1. Open `/extensions` and confirm Shopify diagnostics is the selected add-on path. Result: the customer understands this route uploads storefront and theme diagnostic evidence, not staff access or commerce exports.
2. Start the diagnostic action from the customer-approved Shopify app install for the approved store. Result: the app prepares evidence only for the project the customer can manage.
3. Confirm `shop_domain` is the expected `.myshopify.com` store and `shop_name` matches the customer workspace. Result: diagnostics cannot attach to another shop or client account.
4. Confirm `granted_scopes` contains only `read_content`, `read_products` and `read_themes`. Result: order, customer, payment, gift card and write scopes stop before upload.
5. Review the preview for `diagnostics.primary_domain`, `diagnostics.published_theme_name`, `diagnostics.theme_count`, `diagnostics.product_count_bucket`, `diagnostics.checkout_profile_status`, `diagnostics.app_embed_status`, `diagnostics.visible_storefront_symptoms`, `captured_at` and `app_version`. Result: the customer sees each safe field before upload.
6. Send `POST /api/shopify-app/diagnostics` with route name `shopify-app.diagnostics.store` and a bearer token that has `shopify-app:diagnostics-upload`. Result: accepted diagnostics return `201 Created`, `status: accepted`, a diagnostic id and project/report handoff URLs.
7. When `report_id` is present, verify it belongs to `project_id` before retrying. Result: report/project mismatches fail validation and no diagnostic record is stored.
8. If app embed or checkout status is `disabled` or `not_checked`, keep that diagnostic status and continue only with supported storefront or theme evidence. Result: `SHOPIFY_SCOPE_UNSUPPORTED` explains why broader commerce diagnostics stop.
9. If the API returns `UNAUTHORIZED`, `FORBIDDEN` or `VALIDATION_FAILED`, fix the token, token ability, shop domain, scope list, project, report or payload before retrying. Result: the app does not repeat an unsafe upload.
10. If the preview includes `read_orders`, `write_products`, `read_customers`, customer records, order history, payment details or gift cards, stop and remove those scopes or fields before upload. Result: `SHOPIFY_DIAGNOSTIC_REJECTED` stays visible until unsafe data is excluded.

Diagnostic fields WebRiskOps accepts

Accepted Shopify diagnostics should stay inside public storefront and theme context.

• `project_id`, optional `report_id`, `shop_domain`, optional `shop_name`, `captured_at` and `app_version` identify the customer-approved handoff.
• `granted_scopes` must contain only `read_content`, `read_products` and `read_themes`.
• `diagnostics.primary_domain`, `diagnostics.published_theme_name`, `diagnostics.theme_count`, `diagnostics.product_count_bucket`, `diagnostics.checkout_profile_status`, `diagnostics.app_embed_status` and `diagnostics.visible_storefront_symptoms` explain the visible store state that may affect the finding.
• `shopify_diagnostic_status`, `shopify_shop_domain` and `shopify_scope_status` should show whether the upload is accepted, rejected or blocked by scope.
• `SHOPIFY_DIAGNOSTIC_READY` applies only after project ownership, report/project matching and safe scope validation pass.

Data and scopes the app must exclude

The diagnostic handoff must not become a Shopify commerce export or write-capable app install.

• Exclude `read_orders`, `write_products`, `read_customers`, `customer_records`, `order_history`, `payment_details`, `gift_cards`, write scopes, private app secrets and staff account data.
• Exclude customer records, order history, payment details, gift cards, discount codes, fulfillment records and checkout payment data.
• Reject diagnostics from a store that does not match the selected project or a report that does not belong to the selected project.
• Do not broaden Shopify scopes to work around blocked diagnostics. Use Shopify access or Safe fallback paths when storefront/theme diagnostics cannot stay bounded.

Ready and blocked Shopify diagnostic states

Use these states before diagnostics reach reports, tickets or assurance packs.

• Shopify diagnostic accepted means `SHOPIFY_DIAGNOSTIC_READY`, `status: accepted`, a diagnostic id and project/report handoff URLs point to the same customer context.
• Shopify diagnostic rejected means `SHOPIFY_DIAGNOSTIC_REJECTED` blocks unsafe scopes, unsafe fields, store mismatch or private commerce data.
• Shopify scope unsupported means `SHOPIFY_SCOPE_UNSUPPORTED` applies when the requested workflow needs order, customer, payment, gift card or write access that diagnostics should not collect.
• Token blocked means `UNAUTHORIZED` or `FORBIDDEN` requires a valid bearer token with `shopify-app:diagnostics-upload`.
• Payload rejected means `VALIDATION_FAILED` requires a valid `.myshopify.com` domain, safe `granted_scopes`, a matching report/project pair or safer diagnostic fields.

Continue after diagnostics

After diagnostics are accepted, continue to Extension and platform handoffs for the API contract or Request and response examples for copy-safe authenticated requests. Use Authentication and headers when token setup fails, Shopify access when the customer needs scoped connected access instead of diagnostics, Safe fallback paths when connected access is unsafe, and Provider connection errors when app connectivity fails.