Reference
Admin API in Custom Apps examines queries, mutations, versioning, cost limits, and access scopes as a store-specific workflow. Admin GraphQL operations need scopes, versioning, and calculated-cost awareness. Define the user decision, Shopify surface, app-owned state, failure model, and maintenance. The decision is Which administrative action does the app need to perform or observe?
Red flags
The primary risk is letting API mechanics define the product workflow.
Findings
This guidance applies directly to queries, mutations, versioning, cost limits, and access scopes.
For admin api in custom apps, keep the interface centered on the staff or customer decision. Embedded admin screens should preserve Shopify context, make permission and loading states clear, and avoid turning an operational task into a generic dashboard.
Use Functions for supported deterministic commerce logic, Flow for visible automation, APIs for Shopify resources, and app infrastructure for stateful external work. Send the correct access token header, request only required fields, inspect errors and userErrors, and paginate connections.
Verify webhooks, deduplicate, queue long work, use safe retries, retain attempt history, and reconcile state. HTTP 200 can contain failed GraphQL work, and one expensive query can exhaust available cost. An app must explain what an operator does when automatic recovery stops.
Budget hosting, monitoring, support, incidents, security, API version changes, dependency upgrades, and feature evolution. Record requested/actual cost, throttle status, denied scopes, mutation userErrors, and reconciliation.
Investigation
The sequence follows the actual operating model for this subject.
Compare native Shopify capability, configuration, existing apps, and process changes against queries, mutations, versioning, cost limits, and access scopes. Record why the remaining gap deserves custom ownership.
Map actors, permissions, decisions, exceptions, loading, errors, confirmation, and reversal. The central decision is Which administrative action does the app need to perform or observe?
Place deterministic commerce logic, admin UX, storefront behavior, automation, and stateful services in their supported Shopify boundaries. Send the correct access token header, request only required fields, inspect errors and userErrors, and paginate connections.
Test installation, scope denial, duplicate events, jobs, dependency outages, migrations, rollout, rollback, and offboarding. The route risk is letting API mechanics define the product workflow. HTTP 200 can contain failed GraphQL work, and one expensive query can exhaust available cost.
Ship observability, runbooks, support boundaries, API-version review, dependency updates, backups, and succession guidance. Record requested/actual cost, throttle status, denied scopes, mutation userErrors, and reconciliation.
Case frame
Which administrative action does the app need to perform or observe? The lenses below are specific to queries, mutations, versioning, cost limits, and access scopes.
Describe the staff or customer workflow behind admin api in custom apps, its frequency, current failure cost, exceptions, and decision owner. A feature list does not prove custom software is the right answer.
Choose where queries, mutations, versioning, cost limits, and access scopes belongs: embedded admin, Admin API, Storefront API, webhook processing, Flow, Function, app proxy, theme extension, or app infrastructure. Send the correct access token header, request only required fields, inspect errors and userErrors, and paginate connections.
Name what the app must store, what remains authoritative in Shopify, retention and deletion behavior, and how schema changes migrate. Avoid copying platform data without a product reason.
Assign hosting, deployments, incidents, security, API upgrades, documentation, support, and roadmap decisions. Record requested/actual cost, throttle status, denied scopes, mutation userErrors, and reconciliation.
Exhibits
| Layer | What to preserve | When |
|---|---|---|
| Gap record | Native, configured, existing-app, and process alternatives compared against the exact workflow. | Discovery |
| Product fixture | Realistic store, actor, data, permission, exception, and acceptance scenarios for queries, mutations, versioning, cost limits, and access scopes. | Design |
| Lifecycle proof | Install, denied access, duplicate, timeout, migration, rollout, rollback, and recovery evidence. HTTP 200 can contain failed GraphQL work, and one expensive query can exhaust available cost. | Pre-release |
| Ownership file | Named operational owner, dashboards, runbook, API-version schedule, support path, and cost boundary. Record requested/actual cost, throttle status, denied scopes, mutation userErrors, and reconciliation. | Handoff |
Disposition
Interview notes
It is justified when queries, mutations, versioning, cost limits, and access scopes represents a valuable, store-specific workflow that native features, configuration, established apps, or a process change cannot meet reliably—and when someone will own the resulting product. Admin GraphQL operations need scopes, versioning, and calculated-cost awareness.
Depending on the workflow, an app can use Admin or Storefront APIs, embedded admin UI, webhooks, Flow extensions, Functions, theme extensions, app proxies, checkout or customer-account extensions, and app-hosted services. Choose by execution, trust, and state requirements.
Discovery, hosting, queues, observability, backups, security, support, API upgrades, dependency maintenance, data migration, rollout, rollback, and succession are often omitted. They are part of owning the product.
Use realistic store fixtures, denied permissions, duplicate and delayed events, dependency outages, migration tests, monitoring, rollback, and operator recovery. Record requested/actual cost, throttle status, denied scopes, mutation userErrors, and reconciliation.
Devuchi
Devuchi is a subscription Shopify development service for ecommerce brands and agencies that need reliable recurring development capacity.
queries, mutations, versioning, cost limits, and access scopes can be planned against the frameworks and checks in this reference.
Cross-file references
Custom-app architecture depends on correctly scoped queries, pagination, cost limits, bulk operations, versioning, and error recovery. implement the Shopify Admin GraphQL layer.