Skip to main content

How to Build a Shopify Custom App with the Admin API

  • November 1, 2026
  • 7 min read
  • By CYPHEX
How to Build a Shopify Custom App with the Admin API
Illustrative animation with example data

This guide is for the technical lead who has to build a Shopify custom app, or brief someone who will. It covers the route Shopify recommends now, the decisions that are expensive to reverse, and the parts most tutorials skip: signature checks on webhooks, duplicate deliveries, rate limits and monitoring. If you are still deciding whether to build at all, read Shopify custom apps explained first.

API versions change every quarter, so this article writes {version} where a version belongs. Look up the current one in the Admin GraphQL reference and pin it in your code.

Why most older tutorials will not work

Search for “create a custom app Shopify” and you will find guides that start with Settings, Apps, Develop apps, inside the store admin. Shopify’s access token docs say you can no longer create apps that way, and its help page says new custom apps are created in the Dev Dashboard. The same tutorials often assume a Remix template, which Shopify has replaced with React Router. If a guide shows a screenshot from 2023, treat it as history.

Step 1: Create the app

Shopify’s scaffolding guide is short:

  1. Install the latest Shopify CLI and make a development store.
  2. Run shopify app init in an empty folder and pick the React Router template. The CLI creates the app in the Dev Dashboard and installs dependencies.
  3. Run shopify app dev. You get a local server and an HTTPS tunnel, so Shopify can reach your laptop.
  4. For a real store, choose custom distribution. The distribution docs say the choice cannot be changed afterwards, so make it on purpose.

The template includes an admin screen. If your app is a pure background integration, you do not need that screen. The same guide mentions an extension-only template for simple cases and the Dev Dashboard for API-only apps.

Step 2: Choose access scopes

Scopes are the permissions you request and the merchant approves. Request fewer than you think you need, then add more when a real call fails.

JobScope to look up
Read ordersread_orders
Change orders: tags, notes, mark paidwrite_orders
Create fulfilments, update trackinga fulfilment-order write scope (the mutation page lists which)
Create fulfilment eventswrite_fulfillments
Products and stockread_products, write_products, read_inventory, write_inventory

Every mutation page on shopify.dev lists its required scopes. Customer name, email, phone and address are gated separately by protected customer data, and a request without approval returns an error or empty fields. Find that out in week one, not on launch day.

Step 3: Authentication and tokens

The access token page lists the grant types. Three matter for most builds:

  • Token exchange for embedded apps, using the ID token from the admin session.
  • Authorization code grant for apps that live outside the admin.
  • Client credentials grant for server-side integrations that only act on stores in your own organisation, with no merchant clicking anything. Tokens last 24 hours and you ask for a new one when it expires.

Whatever you pick, keep the client secret in a secrets manager, cache the token until shortly before expiry, and never write tokens or full headers to logs. Offline tokens suit background work and webhooks. Online tokens are tied to a staff member’s session. Shopify is also moving public apps to expiring offline tokens, so read the current rules for your distribution type.

Step 4: A query, reading recent orders

Admin GraphQL requests are POSTs to https://{shop}.myshopify.com/admin/api/{version}/graphql.json with the token in an X-Shopify-Access-Token header.

# Ten most recent orders. Only the fields we need, which keeps query cost low.
query RecentOrders {
  orders(first: 10, sortKey: CREATED_AT, reverse: true) {
    nodes {
      id
      name
      createdAt
      displayFinancialStatus
      displayFulfillmentStatus
      totalPriceSet { shopMoney { amount currencyCode } }
    }
    pageInfo { hasNextPage endCursor }
  }
}

There are no customer fields in that query on purpose. For a large export, such as a full order history, use bulk operations instead of paging.

Step 5: A mutation, tagging an order

# Tag an order so staff, or a Flow workflow, can find it.
mutation AddTag($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node { id }
    userErrors { field message }
  }
}

A mutation can come back with HTTP 200 and still have failed. Read userErrors every time and log anything in it.

Step 6: Rate limits

The GraphQL Admin API charges each query a cost and drains a bucket that refills at a rate set by the store’s plan. A full bucket returns a throttle error. When we checked the rate limit docs, restore rates were 100 points per second on Standard, 200 on Advanced and 1,000 on Plus, with a 1,000-point ceiling on any single query. Check the page again before you design around those numbers.

In practice: read extensions.cost from each response and slow down when the bucket runs low, request fewer fields and smaller pages, and back off on a throttle error (Shopify suggests starting around one second). Retrying in a tight loop only makes it worse.

Step 7: Webhooks

A webhook is Shopify calling your server when something happens. The rules from the webhook overview and HTTPS delivery page:

  1. Subscribe in shopify.app.toml, using a relative path so the subscription survives tunnel URL changes.
  2. Verify the signature. Take the raw request body, compute HMAC-SHA256 with your client secret, base64-encode it and compare with the X-Shopify-Hmac-SHA256 header. Capture the raw body before any JSON parser touches it, which is the usual reason verification fails.
  3. Answer fast. Shopify allows one second to connect and five seconds in total. Return 200, put the payload on a queue, and do the work afterwards.
  4. Expect retries. A failed delivery is retried eight times over about four hours, and an API-created subscription can be deleted after repeated failures.
  5. Handle duplicates with the X-Shopify-Webhook-Id header. Ordering is not guaranteed either.
  6. Do not trust webhooks alone. Shopify says delivery is not guaranteed, so run a reconciliation job that fetches records changed since the last run using updated_at.
Webhook in -> verify HMAC -> store raw event + webhook id -> return 200
Worker     -> seen this id? skip -> do the work -> mark done
Nightly    -> query "updated since last run" -> repair anything missed

Step 8: Where to host it

OptionSuitsCatch
App platform or containers (Fly.io, Render, Cloud Run)Apps with a database and a workerIdle cost, cold starts
Serverless or edge functionsWebhook receivers, light jobsTime limits, needs a queue for slow work
Your own serverFull controlYou own patching and uptime

You need a public HTTPS endpoint, a queue or job runner and a database for state such as processed event IDs. The headless CMS webhook pipeline post uses the same pattern in another setting.

Step 9: Testing on a development store

Create paid, unpaid, partly fulfilled, refunded and cancelled orders. Replay a webhook twice and check nothing happens twice. Switch your server off for ten minutes, bring it back and confirm the reconciliation job fills the gap. Try an expired token and a revoked one. These four tests catch most of what goes wrong in production.

Step 10: Logging and monitoring

Log webhook IDs, outgoing call results and every userErrors entry, keyed by order ID. Keep names, emails and addresses out of the logs. Set alerts for a climbing error rate, a growing queue and an unusually long silence with no webhooks. Give the alerts to a named person.

Launch checklist

  • Scopes reviewed, none unused
  • Secrets in a secrets store
  • API version pinned, review date in the calendar
  • HMAC check tested with a deliberately bad signature
  • Queue, retries and duplicate handling in place
  • Reconciliation job scheduled
  • Alerts go to a person
  • Privacy review done: consent, retention, protected customer data approvals
  • Rollback plan and a written owner

Frequently Asked Questions

Should I use REST or GraphQL for the Admin API?

Use GraphQL. It is Shopify’s main Admin API and new features appear there first. Check the current docs for REST’s status before starting anything new.

Do I need an embedded admin screen?

Not if the app only syncs data in the background. Add one when staff need to change settings or see status without asking a developer. The embedded apps article covers that decision.

How often should I update the API version?

Review at least once or twice a year. Each version is supported for a limited period, so an app pinned and forgotten will break eventually.

Can webhooks replace polling completely?

No. They are quick but not guaranteed, so keep a scheduled job that catches anything missed.

What if my app handles customer data?

Request only the fields you need, get the protected customer data approvals, collect consent where required and check local privacy law. None of this is legal advice.

Conclusion

To build a Shopify custom app that survives real traffic, spend your effort on small scopes, careful token handling, cost-aware queries, verified and idempotent webhooks and a reconciliation job. The feature code is the smaller part. If you would like help with this, CYPHEX can plan and deliver it for you, with one project lead as your contact. See our Shopify services and SaaS and app development.

Stock photography provided by Pexels under the Pexels License.

Want your online store to sell more?

We can review your store and show you what to fix first to turn more visitors into buyers.

Comments

  1. Loading comments...

Leave a comment

Selling online?

Turn more visitors into orders

A faster, clearer store with better product pages and checkout. We handle Shopify and WooCommerce from setup to growth.

Step 1 of 3

Tell us what you need

Three quick steps. We reply within one business day.

What do you need help with? Pick all that apply