Examples

Start from a recipe

Every example is a recipe on New app: choose it under Start from and the app begins with the example's files. A Shopify recipe's scopes are filled in on the connect step and its admin pages decide whether they're Polaris; a web recipe decides the starter. The setup page lists what's left to do and the keys the app reads. ib-apps create <name> --recipe reviews and recipe: "reviews" to POST /v1/apps do the same; the ids are the folder names below (reviews, wishlist, quiz, tagger, notion-sync, bundler, parcel-globe). A Shopify recipe lies over the starter, replacing files of the same path and dropping the starter's storefront block; a web recipe replaces the starter, keeping the coding-agent guidance. Everything stays editable.

Load an example by hand

To put an example over an app you already have: connect Shopify (for a Shopify example), then pull the app, copy the example over it, and sync:

ib-apps pull --app <app>
cp -R examples/apps/reviews/. <app>/
cd <app> && ib-apps dev

ib-apps dev pushes everything to development. Saving extensions/ releases the block to the development Shopify app by itself; Logs show a succeeded config release.

Reviews

Shoppers write reviews from a block on the product page. The brand approves or rejects each one in the Shopify admin, and approved reviews appear on the product page, rendered by Shopify with the page: no script loads them.

export async function POST(request: Request) {
  const proxy = await verifyProxyRequest(request);
  if (!proxy) return Response.json({ error: "Not found" }, { status: 404 });
  // …validate the form: 1–5 stars, lengths, a honeypot field…
  const api = createClient();
  // One review per shopper per product: a signed-in customer by id, a guest by email.
  const existing = await api.review.findFirst({ filter: { shop: { equals: proxy.shop }, productGid: { equals: productGid }, status: { in: ["pending", "approved"] }, ...who } });
  if (existing) return Response.json({ error: "You've already reviewed this product. Thanks!" }, { status: 409 });
  try {
    await api.review.run("create", { shop: proxy.shop, params: { productGid, shop: proxy.shop, rating, title, body, authorName, authorEmail, customerId: proxy.customerId } });
  } catch (e) {
    // The model's validations have the last word; their problems go back beside the fields.
    if (e instanceof ApiError && e.status < 500) return Response.json({ error: e.message, problems: Object.fromEntries(e.problems.map((p) => [p.field, p.message])) }, { status: 400 });
    throw e;
  }
  return Response.json({ ok: true, status: "pending" }, { status: 201 });
}

Setup after loading:

1. On Settings → Shopify → Edit scopes and data models, give Products Write: writing product metafields needs write_products. Optionally tick the shopifyProduct model, so reviews link to synced products and the queue shows product titles. Save.
2. On Installs, use Update scopes for each store already installed, or install on a development store. The install or reinstall creates the metafield definitions.
3. In the theme editor, add Product reviews to the product template. It finds the app proxy by itself.

Try the reviews app

• Submit a review from a product page. The form says it'll appear once approved, and Logs show review.create.
• Open the app in the Shopify admin (or Preview): the review is under Waiting. Approve it. Logs show review.approve and a graphql PublishReviews call, and the product page shows the review and the stars on reload.
• Rejecting an approved review takes it down; the summary's count and average follow.
• The same shopper (customer, or email for guests) can't review a product twice while a review is waiting or live.

Wishlist

Signed-in customers save products with a heart on product pages and keep them on a wishlist page rendered in the store's own theme. It needs no Shopify scopes: wishlists live in the app's records, and product details come from Liquid on the storefront.

export const schema: ModelSchema = {
  type: "ib/model-schema/v1",
  fields: {
    shop: { type: "string", storageKey: "wlShop", validations: { required: true } },
    customerId: { type: "string", storageKey: "wlCustomer", validations: { required: true } },
    productGid: { type: "string", storageKey: "wlProduct", validations: { required: true, regex: { pattern: "^gid://shopify/Product/\\d+$" } } },
    productHandle: { type: "string", storageKey: "wlHandle", validations: { required: true, regex: { pattern: "^[a-z0-9][a-z0-9-]*$" } } },
    variantGid: { type: "string", storageKey: "wlVariant" },
    addedAt: { type: "dateTime", storageKey: "wlAddedAt" },
    key: { type: "string", storageKey: "wlKey", validations: { required: true, unique: true } },
  },
};

After loading, add Add block → Apps → Wishlist button to a product template in the theme editor.

Try the wishlist app

• As a guest, the block says "Sign in to save", and /apps/<subpath>/wishlist asks you to sign in.
• Signed in, the heart fills when tapped and stays filled on reload. Logs show the proxy request and a wishlistItem.create run; tapping again runs wishlistItem.delete.
• The wishlist page lists saved products with image, title and price in the theme's look, and pages on past 20.
• Saving the same product from two tabs at once leaves one record: the unique key refuses the second.

Both answer customers/redact and customers/data_request in their own actions, as a public app must for Shopify's review: Inference Bureau deletes synced data itself, but only the app knows which of its own records hold a customer's data. Without email set up, a data request's action fails and is retried for a few hours, then the privacy event in Logs says to answer by hand. The wishlist has no tests yet; the other four do (see Testing actions).

Product tagger

The merchant writes rules on the admin page ("products that mention merino get the tag Wool"); every product created or changed gets its rules' tags, and Tag every product applies them to the whole catalog. It shows webhook triggers, a long job split into pages, and work that's safe to repeat under Shopify's rate limits. Scopes: read_products, write_products.

export const settings: AppSettings = {
  type: "ib/settings/v1",
  platform: "shopify",
  webhooks: [
    { topic: "products/create", action: "tagProduct", includeFields: ["admin_graphql_api_id", "title", "body_html", "vendor", "product_type", "tags"] },
    { topic: "products/update", action: "tagProduct", includeFields: ["admin_graphql_api_id", "title", "body_html", "vendor", "product_type", "tags"] },
  ],
};

Product quiz

The merchant writes questions in the admin and points each answer at products; shoppers take the quiz from a theme block and land on their matches, rendered in the theme. It needs no Shopify scopes: the block renders from an app-data metafield, and the app proxy does the rest.

{%- liquid
  assign quiz = app.metafields.quiz.definition.value
  assign proxy = app.metafields.ib_app.proxy_path.value
-%}
{%- if quiz.questions.size > 0 and proxy != blank -%}
<form class="ibq" method="post" action="{{ proxy | escape }}/quiz">
  <input type="hidden" name="return_to" value="{{ request.path | escape }}">
  {%- for q in quiz.questions -%}
    <fieldset><legend>{{ q.text | escape }}</legend>
      {%- for a in q.answers -%}
        <label><input type="radio" name="q_{{ q.id | escape }}" value="{{ a.id | escape }}" required> {{ a.text | escape }}</label>
      {%- endfor -%}
    </fieldset>
  {%- endfor -%}
  <button type="submit" class="button">{{ block.settings.submit_label | escape }}</button>
</form>
{%- endif -%}

Notion sync

Every product gets a page in the merchant's Notion database, updated as it changes and archived when it's deleted. It shows a synced model's own actions driving an outside API, jobs that run one at a time per store, and retrying only what the outside API says to retry. Scope: read_products, with the shopifyProduct model synced.

// api/models/shopifyProduct/actions/update.ts
export const onSuccess: ActionOnSuccess = async ({ record, api }) => {
  // One sync per store at a time: under Notion's rate limit, and two quick edits can't both make the page.
  await api.enqueue("syncProduct", { productGid: record.shopifyId }, { shop: record.shop, concurrencyKey: `notion:${record.shop}`, retries: 8 });
};

Bundler

Product bundles: a variant the store sells, expanded at checkout into the variants it's made of, with an optional discount. It shows a Shopify Function in an app: written in extensions/, built with the Shopify CLI and released by Inference Bureau with the rest of the app, fed by metafields the app's actions write, and turned on for each store on install. Scopes: write_products, write_cart_transforms.

// extensions/bundler/src/cart_transform_run.js: a bundle line becomes its components at checkout.
export function cartTransformRun(input) {
  const operations = [];
  for (const line of input.cart.lines) {
    const bundle = line.merchandise.bundle?.jsonValue; // $app:bundles.components on the variant
    const items = (bundle?.components ?? []).map((c) => ({ merchandiseId: c.variantId, quantity: c.quantity }));
    if (!items.length) continue;
    operations.push({ lineExpand: { cartLineId: line.id, expandedCartItems: items, price: { percentageDecrease: { value: bundle.discountPercent } } } });
  }
  return { operations };
}

Parcel globe (a Shop Mini)

A Shop Mini runs inside the Shop app and brings its own backend. This one is a web app on Apps: buyers paste a tracking number and watch the parcel cross a 3D globe, hub by hub. It shows a bearer token from another platform turned into a session, a role that scopes every read to one user, courier and geocoder calls kept out of requests, an hourly schedule, and CORS for a page that lives at localhost on any port. The Mini itself (React, Tailwind, three and @react-three/fiber, all on Shop's approved list) is in the example's mini/ folder.

// web/lib/mini.ts (excerpt): the Mini's bearer token is a temporary Shop token. Shop is asked about it once.
const hash = tokenHash(token);
const session = await api.miniSession.findFirst({ filter: { tokenHash: { equals: hash } }, select: { expiresAt: true, buyer: { select: { id: true, publicId: true, userState: true } } } });
if (session && new Date(session.expiresAt).getTime() > Date.now()) return buyerFrom(session.buyer);

const v = await verifyShopToken(token); // userTokenVerify, with the Mini's API key
if (!v) return null;
const { record: buyer } = await api.miniBuyer.upsert({ on: "publicId", values: { publicId: v.publicId, userState: v.userState, lastSeenAt: now } });
await api.miniSession.create({ buyer: buyer.id, tokenHash: hash, expiresAt: v.expiresAt ?? inFifteenMinutes });

Setup after loading: set SHOP_MINIS_API_KEY (written to the Mini's .env by npx shop-minis setup) and SHIP24_API_KEY on Settings → Environment variables; in mini/, put the app's address in src/config.ts and in manifest.json's trusted_domains, then npx shop-minis dev.

Each example's README has the setup and what to check.

For the patterns these use, see Storefront blocks and app proxy and Embedded admin pages.