Skip to content
Tutorials Center
My learning

Topics

Lesson 55 of 55 ยท Practice and Review

Shopify App Development Cheat Sheet

A quick Shopify app reference: CLI commands, shopify.app.toml keys, auth flow, GraphQL patterns, webhook checklist, extension targets and a pre-submission review checklist.

This page is a lookup table, not a lesson. When you cannot remember the name of a TOML key, the header a webhook carries or the command that ships a new app version, come here. Each block links to the lesson that explains the idea in full.

Shopify changes its platform often, so treat names and flags as a memory aid and confirm them with shopify app --help and the current developer documentation before you rely on them. Examples below use the API version 2026-10; replace it with the newest stable version when you read this (see API Versioning and Deprecations).

Real Shopify code (CLI, TOML, GraphQL, extensions) cannot run on this site, so every block of it is read-only. Two runnable stand-ins at the end let you practice two habits from the sheet: verifying a webhook signature and reading a global ID and a query cost. They are plain Node and JavaScript, not Shopify code.

flowchart LR
    A["Need a command"] --> CLI["CLI table"]
    B["Need a config key"] --> TOML["TOML table"]
    C["Need an API pattern"] --> GQL["GraphQL patterns"]
    D["Need a checklist"] --> CHK["Webhook and<br/>review checklists"]

Jump to the section that matches what you are looking for.

Shopify CLI commands

Run these from the app folder unless noted.

Task Command
Check the CLI version shopify version
Create an app from a template shopify app init
Run the app locally with a tunnel shopify app dev
Link the folder to an app in your account shopify app config link
Show app info and extensions shopify app info
Generate an extension shopify app generate extension
Push config and extensions as a new version shopify app deploy
Release a version that was created without releasing shopify app release --version <name>
List app versions shopify app versions list
Stream app logs shopify app logs
Send a test webhook to a URL shopify app webhook trigger
Run a function with sample input shopify app function run
Replay a logged function run shopify app function replay
Log in or out shopify auth logout (then run any command to log in again)

The usual loop: shopify app dev while you code, shopify app deploy when a version is ready, then release it. See Creating an App with the CLI and Tooling and Setup.

shopify.app.toml keys

TOML
client_id = "your-client-id"
name = "My App"
application_url = "https://example.com"
embedded = true

[build]
automatically_update_urls_on_dev = true

[access_scopes]
scopes = "read_products,write_products"
optional_scopes = [ "read_orders" ]
use_legacy_install_flow = false

[auth]
redirect_urls = [ "https://example.com/auth/callback" ]

[webhooks]
api_version = "2026-10"

  [[webhooks.subscriptions]]
  topics = [ "app/uninstalled" ]
  uri = "/webhooks/app/uninstalled"

  [[webhooks.subscriptions]]
  compliance_topics = [ "customers/data_request", "customers/redact", "shop/redact" ]
  uri = "/webhooks/compliance"

[app_proxy]
url = "https://example.com/proxy"
subpath = "my-app"
prefix = "apps"
Key What it controls
client_id Identifies the app in your account (not a secret)
application_url The URL Shopify loads in the admin iframe
embedded Whether the app opens inside the Shopify admin
[access_scopes] scopes Permissions requested at install
optional_scopes Permissions the merchant can grant later
use_legacy_install_flow = false Opt in to managed installation (scopes come from the TOML)
[auth] redirect_urls Allowed OAuth redirect URLs
[webhooks] api_version API version used for webhook payloads
[[webhooks.subscriptions]] One subscription: topics (or compliance_topics) plus a uri
[app_proxy] Maps a storefront path to your server

Deploying the file creates an app version; see App Configuration with shopify.app.toml and Managed Installation and Access Scopes.

Authentication summary

Step Detail
Install Managed installation reads the scopes from the TOML; the merchant approves
Embedded request App Bridge adds a session token, a JWT signed with the app secret (HS256)
Verify the token Check the signature, exp/nbf, aud (your client ID) and that iss and dest share the shop domain
Get an access token Token exchange: POST to https://{shop}/admin/oauth/access_token with the session token as subject_token and the grant type urn:ietf:params:oauth:grant-type:token-exchange
Token kind requested_token_type asks for an online (user-bound) or offline (shop-bound) token
Call the Admin API Header X-Shopify-Access-Token: <token>
Background jobs Use an offline token; there is no user session

Never store the app secret or tokens in the repository; see The OAuth Authorization Code Flow, Session Tokens for Embedded Apps, Token Exchange and Access Tokens and Online vs Offline Tokens.

GraphQL patterns

The Admin API has one endpoint per shop and version:

TEXT
POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json
X-Shopify-Access-Token: <token>
Content-Type: application/json

Query with variables and a page

GRAPHQL
query Products($first: Int!, $after: String) {
  products(first: $first, after: $after, query: "status:active") {
    nodes {
      id
      title
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Mutation with userErrors

GRAPHQL
mutation Rename($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

The mutation's field names and input types change between API versions, so check the schema for your version.

Pattern Rule of thumb
IDs Global IDs look like gid://shopify/Product/123; pass them whole
Variables Never build a query string by joining user input; use variables
Pagination first + after with pageInfo.endCursor; do not use offsets
Errors A 200 response can still carry errors (query problems) or userErrors (business problems); check both
Cost Read extensions.cost (requested, actual, throttleStatus); the bucket refills at a fixed rate per second
Throttled Wait based on the restore rate, then retry with backoff
Large jobs Use a bulk operation and parse the JSONL result file

See GraphQL for Shopify Developers, Pagination with Cursors, Mutations and userErrors, Rate Limits and Query Cost and Bulk Operations.

Webhook checklist

Shopify sends these headers with every delivery:

Header Meaning
X-Shopify-Hmac-Sha256 Base64 HMAC-SHA256 of the raw body, keyed with the app secret
X-Shopify-Topic For example orders/create
X-Shopify-Shop-Domain The shop that triggered it
X-Shopify-API-Version The version of the payload
X-Shopify-Webhook-Id Identifies the delivery; use it to ignore duplicates

Checklist for every handler:

  1. Read the raw body before any JSON parsing.
  2. Compute the HMAC and compare it in constant time; reject mismatches with 401.
  3. Acknowledge with 200 quickly, then do the heavy work in a queue.
  4. Deduplicate by the webhook ID; deliveries can repeat and arrive out of order.
  5. Run a periodic reconciliation job, because webhooks are not guaranteed.
  6. Subscribe to app/uninstalled and the three privacy topics (customers/data_request, customers/redact, shop/redact).

General ideas are in Webhooks and Signatures and Idempotency; the Shopify specifics are in Webhooks in Shopify, Verifying Webhook Signatures and Reliable Webhook Handlers.

Extension types and example targets

Surface Extension type Example target or placement
Online store Theme app extension App block in a section; app embed in the page body
Admin Admin action / block admin.product-details.action.render, admin.product-details.block.render
Checkout Checkout UI purchase.checkout.block.render, purchase.checkout.cart-line-item.render-after
Thank-you page Checkout UI purchase.thank-you.block.render
Customer accounts Customer account UI customer-account.order-status.block.render
Point of sale POS UI pos.home.tile.render, pos.home.modal.render
Storefront pages App proxy A path such as /apps/my-app served by your server
Checkout rules Function Discount, delivery customization, payment customization, cart validation

Target names are versioned along with the extension API, so use the generated template and the documentation for your version. See App Extensions Overview, Theme App Extensions, Checkout UI Extensions, Customer Account and POS Extensions and Shopify Functions Overview.

Billing and review checklist

Billing at a glance: a managed-pricing plan is configured in the Partner or Dev Dashboard, while the Billing API (appSubscriptionCreate, usage records) is used when your code decides the plans. Merchants must approve a charge on a confirmation URL before it is active. Details: App Pricing Models and Billing Options and Implementing Billing with the Billing API.

Before you submit, confirm:

  • Scopes are the minimum the app needs; optional scopes cover the rest.
  • Every inbound request is verified: session token, webhook HMAC, app proxy signature.
  • The mandatory privacy webhooks respond and delete data as promised.
  • Uninstall cleans up data and cancels background work.
  • The app works on a fresh development store from install to uninstall, with no console errors.
  • The listing text, screenshots and pricing match what the app really does.
  • The server sets Content-Security-Policy: frame-ancestors for the Shopify admin and the shop domain.

See Privacy, GDPR and Mandatory Webhooks, App Security Checklist and App Store Requirements and Review.

Stand-in 1: verify a webhook signature

This Node program (it runs on the site's Node runner) reproduces the check from the webhook checklist: compute a base64 HMAC-SHA256 over the exact bytes of the body and compare in constant time. The secret and payload are made up. Real Shopify sends the header for you; here we create one so we can also show a forged and a tampered request.

Node.js HMAC check for a webhook

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The valid delivery is accepted and the other three are rejected. A real handler must hash the unparsed body: re-serializing parsed JSON can change whitespace or key order, and the signature would no longer match.

Stand-in 2: read a global ID and a query cost

Two small helpers from the GraphQL table: split a gid:// string into its parts, and use the cost block of a response to decide how long to wait. The numbers in the response are invented; the field names follow the shape of the real extensions.cost block.

JS Global IDs and throttle math

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first two IDs parse into a type and a number and the third returns null. With 150 points available and a refill of 50 per second, a 520-point query needs ceil(370 / 50) = 8 seconds, while a 100-point query can go immediately.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which header carries the signature that proves a webhook came from Shopify?

    X-Shopify-Hmac-Sha256 holds the base64 HMAC of the raw body, computed with the app secret. The access token is something your app sends, not receives.
  2. 2. An embedded app needs to call the Admin API from a background job at night. Which token fits?

    Offline tokens belong to the shop and outlive a user session. Session tokens are short-lived and only exist while a merchant has the app open.
  3. 3. A GraphQL mutation returns HTTP 200 and a non-empty userErrors list. What happened?

    userErrors report problems with the data you sent. Always check them along with the top-level errors, because 200 does not mean success.
  4. 4. Which TOML table lists the privacy topics customers/redact and shop/redact?

    Compliance topics are declared in a webhook subscription entry through the compliance_topics key, with a uri that points at your handler.

Summary

  • shopify app dev for local work, shopify app deploy to create a version, and the TOML file is the source of truth for scopes, webhooks and the app proxy.
  • Embedded requests carry a session token; exchange it for an online or offline access token and send it in X-Shopify-Access-Token.
  • Use variables, global IDs and cursor pagination in GraphQL, check both errors and userErrors, and watch the cost block.
  • Verify every webhook against the raw body, answer fast, deduplicate and reconcile.
  • Match extension types to surfaces, keep scopes minimal and walk the review checklist on a fresh development store before submitting.

You have reached the end of the track. Revisit the practice exercises or rebuild one of the projects with a variation of your own.