Shopify apps

Custom or public

A Shopify app is custom or public, chosen when it's created and shown on Settings → Shopify.

Choose Public on New app in the dashboard, or send distribution: "public" to POST /v1/apps; ib-apps create makes custom apps only. Shopify sets the production app's distribution in the Partner Dashboard, once; for a public app, Settings links to that page. The type can change until production is first installed on a store, since by then Shopify's choice is made. After that, fork the app to start one of the other type. PATCH /v1/apps/<app> with { "distribution": "public" } does the same from a key with Apps Permissions. Every install gets an expiring offline token, which public apps require; Inference Bureau renews it before each call.

For a public app, the deploy plan adds Review readiness: what Shopify's review checks, each read from the app as it stands. Shopify managed installation, privacy webhooks (and any data request still pending), session tokens on the embedded pages' routes, frame-ancestors on its pages (new Shopify apps' web/proxy.ts sends it), whether the admin pages use Polaris web components, uninstall cleanup, stores still holding a non-expiring token, charging through Shopify Billing and protected customer data. Then the steps it can't check: performance in merchants' admins, and the listing and submission. It never blocks a deploy.

Connect to Shopify

Creating a Shopify app in the dashboard leads into guided setup: create the Shopify app, install it on a store, then sync files. Each step is checked from what has actually happened, so you can leave and come back.

Each environment has its own Shopify app and its own client ID. The secret never leaves Inference Bureau: the app's code receives only the client ID, as NEXT_PUBLIC_SHOPIFY_API_KEY.

Install on a store

Settings → Installs lists the stores each environment is installed on, with the scopes each granted. Development installs on development stores; production on the merchant's. Install on a store searches the stores your Shopify sign-in can see. Inference Bureau keeps an encrypted offline token per store; it never reaches the app's code.

Apps use Shopify managed installation: Shopify installs the app with the scopes released from the dashboard, with no OAuth redirect or second approval screen, and opens it in the store's admin. That first load carries Shopify's session token, which Inference Bureau trades for the store's offline token (token exchange); that records the install and runs the install action. An app that needs the redirect keeps it with shopify: { install: "oauth" } in settings.ib.ts; installs then go through Inference Bureau's OAuth callback, and a public app's Review readiness warns, since Built for Shopify looks for managed installation.

On the Free plan, the team's production apps can be installed on five stores in all; a sixth store is refused before Shopify's approval page. Development installs and reinstalls are never refused. See Free's limits.

When the app asks for scopes a store hasn't granted, the store shows needs approval. Shopify asks the merchant to approve them the next time they open the app, and that load records the new grant and runs the reinstall action. The Update scopes link opens Shopify's approval directly; it's the way for apps that keep the OAuth redirect. Scopes a feature needs only once a merchant uses it can be asked for then instead: see optional scopes. A store shows token out of date when Shopify refused one of the app's calls for access after the install; Update scopes renews its token, and the failed call's event in Logs says which scopes the token has against the ones the app asks for.

Scopes and data models

Settings → Shopify → Edit scopes and data models is one page. Each Admin API resource has Read and Write (write implies read). Reading a resource offers its Shopify models to keep in the app's database. A summary lists the resulting scopes, the webhook topics and the models. Saving updates both Shopify apps.

Customers, orders, draft orders and checkouts are protected customer data: development stores work without approval, but production needs Shopify's approval before a merchant can install it. Settings and the deploy plan link to the app's page in the Partner Dashboard to request it. Names, emails, phone numbers and addresses need Shopify's second level of approval; without it, Shopify sends those fields empty. Orders older than 60 days need read_all_orders (All orders), which Shopify approves separately.

Synced models

A synced model is an ordinary model whose schema Inference Bureau writes and keeps filled from Shopify. Choosing one writes its api/models/<model>/schema.ib.ts into development; a model is synced exactly when that file exists, and a deploy carries it to production.

import type { ModelSchema } from "@inferencebureau/apps-sdk";

/**
 * Synced from Shopify. Inference Bureau keeps these fields current from webhooks and an hourly reconcile; rename them
 * or add fields of your own as you like (the sync finds its fields by storageKey). Removing this file stops the sync.
 */
export const schema: ModelSchema = {
  type: "ib/model-schema/v1",
  fields: {
    shopifyId: { type: "string", storageKey: "sh_id", validations: { required: true, unique: true } },
    shop: { type: "string", storageKey: "sh_shop" },
    title: { type: "string", storageKey: "sh_title" },
    handle: { type: "string", storageKey: "sh_handle" },
    status: { type: "string", storageKey: "sh_status" },
    // …vendor, productType, tags, bodyHtml, publishedAt, shopifyCreatedAt
    shopifyUpdatedAt: { type: "dateTime", storageKey: "sh_updated_at" },
  },
};

Shopify's fields have fixed storage keys (sh_*), so you can rename them or add fields of your own; a later sync only adds back Shopify fields that are missing. Deleting the schema file stops the sync and hides the records. customers/redact also deletes the customer's draft orders, checkouts, subscription contracts and B2B contacts, and returns go with their orders.

A synced field can say when it's written, with fetch in its schema. Unset, a webhook writes what its payload carries and the reconcile fills the rest. fetch: "later" isn't written from webhooks at all: the reconcile and sync runs write it, even when nothing else on the record changed. fetch: "onWebhook" has the record fetched from the Admin API when a webhook's payload doesn't carry the field, at one call per such webhook (products, collections, customers, orders and draft orders).

export const schema: ModelSchema = {
  type: "ib/model-schema/v1",
  fields: {
    // Shopify's customer webhooks don't carry these: fetch the customer when one arrives.
    numberOfOrders: { type: "number", storageKey: "sh_number_of_orders", fetch: "onWebhook" },
    amountSpent: { type: "number", storageKey: "sh_amount_spent", fetch: "onWebhook" },
    // Tags change often; leave them to the hourly reconcile.
    tags: { type: "json", storageKey: "sh_tags", fetch: "later" },
    // …
  },
};

Metafields as fields

A field of your own on a synced model can hold one of the record's metafields: give it metafield: "namespace.key" ("$app:reviews.rating" for the app's namespace). Products, variants, collections, customers, orders, draft orders, locations, companies, company locations, markets, pages, blogs and articles have them.

// Beside the synced fields: the product's metafields, refreshed by sync passes.
careGuide: { type: "string", metafield: "custom.care_guide", fetch: "onWebhook" },
rating: { type: "number", metafield: "reviews.rating" },
colors: { type: "json", metafield: "custom.colors" },
material: { type: "belongsTo", parent: { model: "shopifyMetaobject" }, metafield: "custom.material" },

Shopify sends no webhook when only a metafield changes, and the record's updatedAt doesn't move, so sync passes read metafields on their own: every backfill and sync run, the hourly reconcile for models with up to 2,500 records, and the daily one (04:00 UTC) for bigger models, in bulk past 10,000. A field with fetch: "onWebhook" is also read whenever the record's own webhook comes, at one Admin API call per webhook. Only changed values are written, through the model's update action when it has one. The fields are copies: write a metafield with metafieldsSet, and the next refresh brings its value back.

Big stores, in bulk

Products, collections, customers, orders, draft orders and inventory items are listed with Shopify's bulk operations when paging them would take more than 100 pages: about 1,000 products or orders, 2,500 customers or inventory items, or 10,000 collections. Shopify assembles the whole list on its side without using the store's rate limit, and Inference Bureau reads the file it makes, so a catalog of a million products backfills in hours instead of days. Everything else is paged as usual, at the same time.

• A bulk pass carries on across calls until it's done, from where it got to in the file. The pass's event in Logs comes when it finishes, with each bulk query's object count. The paged part has its own sync part event.
• Records are written as a paged pass writes them: the same fields, stale checks, children and actions. An order's refunds and returns are fetched by id afterwards, a few at a time.
• The hourly reconcile pages what changed since the last pass, unless that's more than 100 pages, which then goes in bulk too. A store that big isn't swept for deletes every hour. Its delete webhooks keep it current, and the 04:00 UTC pass sweeps it with a bulk query of ids.
• A store has one bulk pass at a time, and its reconcile waits for it to finish. A sync run that goes in bulk reads as running until the pass finishes it, with bulkPass naming the pass. abort stops the pass and cancels Shopify's operation.

Sync on demand

Sync a store again after fixing a synced model's action, or after an incident: Sync on the store's row in Settings → Installs, ib-apps shopify sync, or api.shopifySync.run in the app's code. A run takes one store, and:

// After fixing api/models/shopifyOrder/actions/update.ts: run it again over October's orders.
const run = await api.shopifySync.run({
  shop: "demo.myshopify.com",
  models: ["shopifyOrder"],
  since: "2026-10-01",
  force: true,        // also the orders Shopify hasn't changed since they were stored
  wait: true,         // resolve when it's done, not at once
});
console.log(run.state, run.counts?.shopifyOrder); // "succeeded", { created, updated, deleted, skipped, failed, errors }

run returns the run at once, running, unless you pass wait; follow it with api.shopifySync.get(id) or list(), and stop it with abort(id), which takes effect before its next page. Installs lists recent runs with their counts and an Abort button, and each run is a sync run event in Logs. A store runs one sync at a time. A run stops after about 13 minutes and is marked failed; start another with since for the rest. Ctrl-C in ib-apps shopify sync aborts the run it's following.

Install, reinstall, uninstall

The shopifyShop model's actions run on Shopify's events, with shop and shopify set to the store:

Without the action file, the record is created or updated directly. Only fields the schema has are passed. In development, an install waits for the dev server to start before the action runs; an install whose action couldn't run is caught up when the app's code is next up. After an install, the store is backfilled.

import { applyParams, save, type ActionOnSuccess, type ActionOptions, type ActionRun } from "@inferencebureau/apps-sdk";

/** Runs when a store installs the app: creates its shopifyShop record. */
export const run: ActionRun = async ({ params, record }) => {
  applyParams(params, record);
  await save(record);
};

/** After the record is saved: write the storefront block's message to an app-data metafield. */
export const onSuccess: ActionOnSuccess = async ({ record, shopify, logger }) => {
  if (!shopify) return;
  const { currentAppInstallation } = await shopify.graphql<{ currentAppInstallation: { id: string } }>(`{ currentAppInstallation { id } }`);
  const { metafieldsSet } = await shopify.graphql<{ metafieldsSet: { userErrors: { message: string }[] } }>(
    `mutation SetBlock($metafields: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $metafields) { userErrors { message } } }`,
    { metafields: [{ ownerId: currentAppInstallation.id, namespace: "ib_app", key: "block", type: "json", value: JSON.stringify({ message: `Installed on ${String(record.myshopifyDomain)}.` }) }] },
  );
  if (metafieldsSet.userErrors.length) logger.warn("The block's metafield wasn't saved", metafieldsSet.userErrors);
};

export const options: ActionOptions = {
  actionType: "create",
};

Privacy webhooks

Every Shopify app is subscribed to Shopify's three privacy (GDPR) webhooks, and Inference Bureau answers each with 200 as soon as it's recorded, then does the work. Each also runs a global action in the app when the file exists, with Shopify's payload as params and shop set (types: ShopifyShopRedactParams, ShopifyCustomersRedactParams, ShopifyCustomersDataRequestParams).

Each is a privacy <topic> event in Logs, under its webhook, with the customer's id, the orders named and the purge's counts; the customer's email and phone stay out of Logs. The Privacy requests view lists them. They run while the team's apps are paused (development's dev server starts for them, unbilled) and aren't billed as runs. A repeated delivery is dropped like any webhook. Shopify sends each only once, so an action that fails is tried again as a background job (source privacy, under the privacy event) for about seven hours; the event says how it ended, and one that still fails can be retried from the Queue once the app is fixed.

import type { GlobalActionRun, ShopifyCustomersRedactParams } from "@inferencebureau/apps-sdk";

/** Shopify's customers/redact: erase what the app keeps on this customer. */
export const run: GlobalActionRun = async ({ params, shop, api, logger }) => {
  const { customer } = params as unknown as ShopifyCustomersRedactParams;
  const page = await api.review.findMany({ filter: { shop: { equals: shop }, customerId: { equals: String(customer.id) } }, first: 250 });
  for (const r of page.records) await api.review.delete(r.id);
  logger.info("Erased the customer's reviews", { count: page.records.length });
};

The Admin API

Every action's context has shopify, the Admin GraphQL API for the store the run is about: the store that installed, the store a webhook came from, or the shop the caller passed. Elsewhere in the app's code, createShopifyClient(shop) gives the same client. Calls go through Inference Bureau, which adds the store's offline token, so the app's code never holds it. The store must have this environment's app installed.

import type { ActionOnSuccess } from "@inferencebureau/apps-sdk";

/** After a review is saved: read its product's title through the store the run is about. */
export const onSuccess: ActionOnSuccess = async ({ record, shopify, logger }) => {
  if (!shopify) return;
  const data = await shopify.graphql<{ product: { title: string } | null }>(
    `query Product($id: ID!) { product(id: $id) { title } }`,
    { id: record.productGid },
  );
  logger.info("Product", data.product);
};

graphql(query, variables) returns data and throws ShopifyError on GraphQL errors. Each call is a shopify event in Logs, named after the operation (graphql PublishReviews).

Shopify limits each store to a bucket of query cost points that refills every second. Calls are paced against that bucket for you:

• A throttled call is tried again after the time Shopify says the missing points take (or its Retry-After), up to 5 times. Logs shows the retries and the wait on the call's event.
• Actions run by jobs, webhooks and schedules are background work: before each call they wait until half the store's bucket is free, so merchants using the embedded admin at the same time aren't slowed down. Background calls wait up to 60 seconds; others up to 8.
• A call still throttled after that throws ShopifyError with throttled set. Pass { priority: "background" } or maxRetries to createShopifyClient to change this for your own routes.

API version

Each environment's Shopify app calls the Admin API, and gets its webhooks, at one version. Shopify releases a version each quarter (January, April, July, October) and supports it for a year; after that it answers with the oldest version it still supports, whatever the app expects. Settings → Shopify → API version shows each environment's version and when its support ends, and changes it:

• Development moves at once: its configuration is released with the new version, so its webhooks move too, and its calls follow.
• Production moves when its next deploy goes live, so the version and the code written for it arrive together. Until then it shows as waiting, and choosing its current version cancels it.

Before you switch, the page shows the upgrade plan, worked out from Shopify's schemas for both versions:

• Synced models: fields Shopify added, removed or deprecated (the reason usually names the replacement) on the types the app syncs, and whether the sync's own queries still work.
• Webhooks: topics the app subscribes to that are removed or deprecated. Payload fields aren't in the schema; the plan links Shopify's release notes for those.
• The app's code: each Admin GraphQL document in the app (string and template literals, and .graphql files, outside extensions/), checked against the new version: fields, arguments, types and enum values it refuses, and deprecated ones it still answers, with the file and line. A document built at runtime (with ${…} in it) is listed as not checked when it can't be read without its parts. For production, the code checked is development's, which the next deploy brings.
• Extensions: UI extensions and functions keep the api_version in their own shopify.extension.toml, listed with when its support ends.

From 90 days before an environment's version leaves support, Problems shows a warning with the date, and an error once it has. Each change is an api version event in Logs.

Shopify Billing

Public apps charge merchants through Shopify. The SDK's helpers run through the action's shopify client (or createShopifyClient(shop) in a route):

A plan page's Subscribe button posts to a route, which checks the session token and starts the subscription for that store. name and returnUrl are required, with a recurring price, usage charges, or both; Shopify sends the merchant to returnUrl after they approve or decline, so point it back into the app in their admin. It returns { confirmationUrl, subscriptionId, test }. replacementBehavior says what happens to a plan the store already has: APPLY_IMMEDIATELY, APPLY_ON_NEXT_BILLING_CYCLE, or STANDARD (Shopify decides: an upgrade now, a downgrade at the period's end; the default). When Shopify refuses (its userErrors, such as a usage charge past the cap) the helpers throw ShopifyBillingError, with userErrors on it.

import { createShopifyClient, requestSubscription, ShopifyBillingError, verifyShopifySession } from "@inferencebureau/apps-sdk";

/** The app's handle in the Partner Dashboard: Shopify sends the merchant back into the app in their admin. */
const APP_HANDLE = "reviews";

/** The plan page's Subscribe button: starts Pro and answers with Shopify's approval page. */
export async function POST(request: Request) {
  const session = await verifyShopifySession(request);
  if (!session) return Response.json({ error: "Open this page from the Shopify admin." }, { status: 401 });
  const store = session.shop.replace(/\.myshopify\.com$/, "");
  try {
    const { confirmationUrl, subscriptionId, test } = await requestSubscription(createShopifyClient(session.shop), {
      name: "Pro", // shown on Shopify's approval page and the merchant's bill
      returnUrl: `https://admin.shopify.com/store/${store}/apps/${APP_HANDLE}`,
      recurring: { price: { amount: 19, currencyCode: "USD" }, interval: "EVERY_30_DAYS" },
      usage: { cappedAmount: { amount: 100, currencyCode: "USD" }, terms: "$0.05 per review request email" },
      trialDays: 7,
      replacementBehavior: "APPLY_IMMEDIATELY", // a store on another plan switches now, not at the period's end
    });
    // test is true outside production and on development stores: nothing is really charged.
    return Response.json({ confirmationUrl, subscriptionId, test });
  } catch (e) {
    // Shopify refused it (userErrors), or answered without a confirmation URL.
    if (e instanceof ShopifyBillingError) return Response.json({ error: e.message, userErrors: e.userErrors }, { status: 400 });
    throw e;
  }
}

A store's trial is recorded the first time Inference Bureau sees a subscription with trial days active, from the shopifyAppSubscription sync or from currentPlan, and kept per environment through uninstalls (and shop/redact, as a billing record). A trial runs from that first start: a store that reinstalls 3 days into a 7-day trial gets 4 days, and none after a week. Gate features in the route or action that does the work with requirePlan, not only in the page. New public apps start with a plan picker: the plans in web/lib/plans.ts, the route web/app/api/billing/route.ts and the page web/app/plans/page.tsx.

Charges are test charges unless the app is in production and the store isn't a development store; development refuses a real charge outright, whatever sends it. On Scopes and data models, public apps can sync shopifyAppSubscription: each store's subscriptions to the app (name, status, test, price, interval, cappedAmount, planHandle, currentPeriodEnd), kept current by app_subscriptions/update, whether they came from the helpers or from managed pricing.

Releases

A release sends a Shopify app its configuration (app URL, scopes, webhooks, app proxy) and the extensions in extensions/ (every type it releases), as shopify app deploy would. It happens:

• right after the Shopify apps are created;
• after a sync changes development's extensions/ or settings.ib.ts (its webhooks);
• when a production deploy goes live, with production's files (and the API version chosen for it);
• when you choose Update Shopify configuration on Settings → Shopify.

Each release is a config release event in Logs. A failed one shows in Problems until a later release goes through: an error when the configuration wasn't taken (often a Shopify sign-in that needs renewing), a warning when Shopify took the configuration but refused the storefront blocks.