Skip to content
threada Docs

Shopify App Store

This guide defines the Shopify App Store path as a documented customer-pull follow-on outside the active Zapier-to-ServiceNow public listing wave. It is a design and launch-control document, not evidence that a Shopify App Store app has been built or approved.

Current Status

Shopify App Store is planned as a customer-pull public store follow-on. Threada already has governed Shopify action proposal payloads for shopify_refund and shopify_update_order in the public API action model. No Shopify public app, Partner Dashboard distribution setting, managed install or OAuth flow, embedded admin UI, GraphQL Admin API implementation, App Store listing, protected customer data approval, listing approval, or reviewer development-store evidence has been observed in this repository.

Do not submit or market a public Shopify App Store listing until the chosen Shopify app package is built, installable in a reviewer-safe Shopify store, validated end to end, linked to a listing, and accepted by Shopify App Review.

The existing Shopify action payloads remain tenant-specific governed action work. They should not be described as the public Shopify App Store app.

The enterprise-safe first package should be a public embedded Shopify app for one narrow order-operations workflow: update a Shopify order’s internal note or approved tags from a governed Threada WorkItem. That surface aligns with the live shopify_update_order action proposal payload and avoids starting with refund processing, checkout changes, product catalog writes, fulfillment automation, customer export, or broad order-history access.

Refunds can follow after order update is installed, reviewable, scoped, and audited. A refund capability must use Shopify’s GraphQL Admin API refund flow, process refunds only through the original payment processor unless Shopify’s approved store-credit flow applies, include idempotency, and preserve explicit merchant approval and audit evidence in Threada.

Positioning

Threada for Shopify should let support and operations teams make governed order updates from Threada work without bypassing Threada policy, approval, idempotency, and audit controls.

The narrow v1 app should stay focused:

  • Install Threada into a Shopify store through a Shopify public app install flow.
  • Bind the Shopify shop to a Threada tenant, pack, queue, or workspace mapping.
  • Update a Shopify order note or approved tags only from an approved Threada action proposal.
  • Show clear setup-required, approval-pending, succeeded, and failed states in Threada and in the embedded Shopify app surface where appropriate.
  • Provide public setup/support documentation that explains least-privilege Shopify scopes, protected customer data handling, disconnect, and uninstall behavior.

The v1 app must not claim that Shopify can execute arbitrary third-party actions through Threada. Direct external execution remains inside Threada’s governed Work, Studio, MCP, A2A, or first-party runtime paths.

Source Of Truth

Do not duplicate request or response schemas in this document. Public WorkItem shape and governed action proposal behavior are documented in Threada Public API and its generated OpenAPI artifact at /openapi/public-api.openapi.yaml. The committed source copy is docs/developers/public-api.openapi.yaml.

When a first-class Shopify App Store package exists, the Shopify Partner Dashboard public app configuration, distribution method, app TOML/config, OAuth or managed-install settings, selected scopes, embedded UI, GraphQL Admin API mutations, install/uninstall behavior, tenant mapping, listing metadata, reviewer setup notes, protected customer data approval, and Shopify approval result must become the source of truth for the public listing.

App Surface

Governed Order Update

The first reviewable capability should update a Shopify order note or approved tags from a Threada WorkItem. The implementation should use Shopify’s public app install path and GraphQL Admin API, then let Threada create a governed action proposal that writes to an order only after the configured policy and approval path permits it.

Inputs should map to the live shopify_update_order payload fields for order_id, note, and tags. If the GraphQL implementation uses a mutation that overwrites tag state, the app must read or merge safely, or use a tag-specific mutation where appropriate, so a Threada proposal cannot accidentally delete existing merchant tags. Do not expose arbitrary order field writes in the public listing until a tenant can review, allowlist, audit, and safely roll back those fields.

Outputs must give the Threada user a clear success, setup-required, approval-pending, or failed state and preserve the Shopify order reference when one is returned. Do not return only a generic success message; reviewers need to see the install-to-action-to-order journey.

Refund Follow-On

Threada already exposes a governed payload type for Shopify refunds. A Shopify App Store listing can reference refund capability only after the public Shopify app proves the required scopes, protected customer data posture, refund eligibility checks, explicit approval, idempotency, audit behavior, reviewer flow, and GraphQL Admin API implementation.

The refund implementation must not process refunds outside Shopify or the original payment processor. If store-credit refunds are offered, the implementation must use Shopify-supported refund or return processing flows and explain that behavior in review notes and public support documentation.

Setup And Tenant Mapping

The app must bind an installed Shopify shop to a Threada tenant, pack, queue, or workspace mapping before claiming production readiness. If setup is incomplete, Threada should show a clear setup-required response instead of silently dropping the request or attempting an unauthenticated Shopify write.

Reviewer setup notes must include the exact Shopify development store, Shopify staff user, Threada tenant, test pack or queue, install URL or App Store listing URL, expected order note or tag behavior, and cleanup instructions. Credentials, tokens, cookies, raw order exports, and customer data must stay out of repo evidence and screenshots.

Marketplace Package Requirements

Shopify’s App Store requirements, distribution, app review, authentication, and GraphQL Admin API documentation route public listings through a public app, Shopify-owned install surface, embedded admin experience, App Bridge/session token posture, least-privilege scopes, GraphQL-only Admin API implementation for new public apps, listing metadata, reviewer credentials, demo screencast, and review approval.

Required package work before submission:

  • Shopify Partner Dashboard public app with production distribution selected, app listing page, app metadata, logo, URLs, and support/contact details.
  • Embedded Shopify admin UI that is operational through the UI, uses the latest Shopify App Bridge where required, and does not depend on third-party cookies or local storage for authentication.
  • Shopify managed install and token exchange for an embedded app, or an approved authorization-code flow only if the app is intentionally standalone. The app must authenticate immediately after install and reinstall, redirect merchants to app UI after permission grant, and avoid manual myshopify.com domain entry during install.
  • GraphQL Admin API implementation for all Shopify reads and writes used by the public app. Do not build a new public app on the REST Admin API.
  • Least-privilege scope set for the v1 surface. For order-note/tag v1, start with the narrow order access needed for the GraphQL mutations and avoid read_all_orders, customer fields, products, fulfillment, checkout, payment, discount, user, or admin scopes unless the public v1 needs them.
  • Optional scope handling for features that not every merchant needs.
  • Protected customer data access request and data protection details if order, customer, refund, transaction, shipping, fulfillment, email, phone, name, or address data is accessed.
  • Mandatory privacy/compliance webhooks, including customer data request, customer redact, and shop redact topics where required, plus app uninstall and scope-update handling for operational cleanup.
  • Server-side token exchange or OAuth callback, state/session validation, token storage in Secret Manager or approved managed identity storage, rotation posture, disconnect, uninstall, scope-change handling, and revocation handling.
  • Tenant/shop install mapping, setup-required behavior, governed order-update proposal creation, execution, idempotency, audit trail, and failure handling.
  • Order field allowlist and safe tag behavior.
  • Public support, privacy, terms, security/data-handling, and setup documentation.
  • App Store listing copy, app card subtitle, categories/tags, logo/screenshots, demo screencast, pricing setup through Shopify App Pricing or Billing API if the app charges merchants, test instructions, reviewer development-store access, emergency developer contact, and cleanup instructions.
  • Completed Shopify App Store review-page mandatory fields and automated checks before pressing submit.
  • Shopify App Review approval before public-readiness claims.

Explicit Non-Goals

  • No public Shopify App Store claim until a first-class Shopify public app exists and Shopify App Review passes.
  • No custom app install link, private app token, API key, or manually provisioned tenant secret as the public App Store install path.
  • No REST Admin API implementation for a new public app.
  • No unmanaged direct Shopify writes from the App Store app.
  • No checkout bypass, off-platform payment, third-party POS, lending, marketplace/classifieds, product-copying, browser-extension-required, or agency-brokering positioning.
  • No broad order-history, customer, product, fulfillment, checkout, payment, discount, user, admin, or protected-customer-data scopes unless the exact v1 capability requires them and the implementation is validated end to end.
  • No refund capability in public copy until GraphQL refund processing, idempotency, protected-data posture, explicit approval, and reviewer evidence exist.
  • No packaged Shopify knowledge sync claim until an authenticated, tenant-scoped, auditable sync path exists and is reviewed.
  • No customer-data screenshots, raw order exports, Shopify store dumps, OAuth tokens, cookies, or private tenant payloads in App Store screenshots or review evidence.
  • No positioning as a generic “AI agent executes any Shopify action” app. Public copy must stay anchored to governed order work, setup, and review.

Review Gates

Implemented:

  • Public API action types include shopify_refund and shopify_update_order.
  • Public BFF mapping code converts Shopify refund and order-update payloads into governed action requests and proposal views.
  • Public API docs and generated OpenAPI are published.

Missing:

  • Chosen v1 public Shopify app surface and product UX.
  • Shopify Partner Dashboard public app, production distribution method, app listing, app metadata, logo, URLs, and reviewer setup path.
  • Embedded Shopify admin UI, App Bridge/session-token posture, managed install or approved OAuth path, token storage, disconnect, uninstall, and scope-change handling.
  • GraphQL Admin API implementation for order note/tag update.
  • Tenant/shop mapping, setup-required, approval-pending, success, failure, idempotency, and audit behavior.
  • Order field allowlist and safe tag behavior.
  • Protected customer data request, privacy/compliance webhooks, data protection details, and public privacy/support documentation for Shopify merchants.
  • App Store listing copy, screenshots, demo screencast, pricing setup if needed, test instructions, setup notes, reviewer access, emergency developer contact, and cleanup instructions.
  • Shopify App Store review-page mandatory fields and automated checks.
  • Shopify App Review evidence and approval report.

Blocked:

  • Public Shopify App Store submission is blocked until the first-class Shopify public app exists, runtime behavior is implemented and testable, GraphQL Admin API and scopes are least-privilege, protected customer data requirements are handled, review gates pass, and reviewer setup is complete.

Launch Checklist

  1. Choose the v1 Shopify surface. Recommended first: embedded public app with governed order note/tag update from a Threada WorkItem.
  2. Create the Shopify public app with production distribution, app metadata, logo, URLs, embedded UI, App Bridge/session-token posture, and least-privilege scopes.
  3. Implement managed install/token exchange or the approved standalone OAuth flow, Secret Manager storage, token rotation posture, disconnect, uninstall, and scope-change handling.
  4. Implement tenant/shop mapping, setup-required behavior, governed order-update proposal creation, execution, idempotency, audit trail, and failure handling.
  5. Build GraphQL Admin API order note/tag update with order field allowlists and safe tag behavior.
  6. Add protected customer data request details, mandatory privacy/compliance webhooks, and public setup/support documentation.
  7. Create App Store listing copy, categories/tags, pricing setup if required, sanitized screenshots, and demo material for install, setup, proposal, approval, execution, resulting Shopify order update, and disconnect.
  8. Prepare Shopify reviewer credentials, development store, setup notes, and cleanup instructions through Shopify-approved channels.
  9. Complete the Shopify App Store review-page mandatory fields and automated checks.
  10. Submit through Shopify App Review and resolve all review issues before claiming Shopify App Store readiness.

Official Sources