· 1 observation
Technical updates · 1
Package or technical metadata updated
View technical comparison →Khadin Akbar v1.4.1
Develop Shopify Apps
From the developer
Not specified in the available declarations: limitations, pricing & account requirements.
Help me build a production-ready Shopify app.
Developer declarations; not independently tested. Listing last checked Nov 19, 2026. Package observed Nov 19, 2026.
From the marketplace listing
A comprehensive open-source Shopify app engineering toolkit with 32 focused skills for routing, APIs, authentication, billing, webhooks, extensions, UX, accessibility, performance, App Store listings, and acquisition.
Language: English · Automatically detected from descriptions.
· 1 observation
Package or technical metadata updated
View technical comparison →· 2 observations
Package or technical metadata updated
View technical comparison →· 2 observations
Package or technical metadata updated
View technical comparison →Package or technical metadata updated
View technical comparison →Finding similar plugins… Results will appear here automatically.
Browse plugins →---
name: admin-graphql
description: "Build Shopify Admin GraphQL queries and mutations for products, orders, customers, inventory, and more. Covers cost-aware rate limiting, cursor pagination, bulk operations, global resource identifiers, and version-safe API usage."
---
## When to Use This Skill
Use **Admin GraphQL API** when you need to:
- Manage products, variants, collections, and pricing (preferred over REST for any business logic)
- Query or modify orders, fulfillments, and refunds
- Create or update customers and customer accounts
- Adjust inventory across multiple locations
- Create metafields and metaobjects for custom data
- Set up webhooks for event subscriptions
- Perform bulk operations on large datasets (1000+ records)
- Access the latest Shopify features (GraphQL-only endpoints)
**GraphQL vs REST comparison:**
| Feature | GraphQL Admin | REST (Deprecated) |
|---------|--------------|-------------------|
| Rate Limiting | Cost-based; standard restore rate is 100 points/sec | Request bucket; standard restore rate is 2 requests/sec |
| Pagination | Cursor-based (Relay pattern) | Offset/limit (deprecated) |
| Field Selection | Precise (fetch only needed fields) | Fixed response shape (wasteful) |
| Batch Operations | Native bulk operations (JSONL) | Multiple sequential requests |
| Latest Features | Current platform features | Some newer features are GraphQL-only |
| Status | Required for new public apps | Legacy since October 1, 2024 |
---
## API Endpoint & Authentication
**Endpoint:** `https://{shop}.myshopify.com/admin/api/2026-07/graphql.json`
**Authentication:**
```javascript
const headers = {
'Content-Type': 'application/json',
'X-Shopify-Access-Token': process.env.SHOPIFY_ACCESS_TOKEN,
};
```
---
## Cost-Based Rate Limiting
Shopify uses calculated query costs. The standard GraphQL Admin API restore rate is 100 points per second; Advanced, Plus, and enterprise plans have higher rates. A single query can't exceed 1,000 requested points. Read `extensions.cost.throttleStatus` instead of hard-coding one bucket size.
**Handling throttling:**
```javascript
async function executeWithRetry(query, variables, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
const response = await fetch(endpoint, {
method: 'POST',
headers,
body: JSON.stringify({ query, variables }),
});
const data = await response.json();
if (data.errors?.some(e => e.extensions?.code === 'THROTTLED')) {
const waitTime = Math.pow(2, attempt - 1) * 1000;
console.log(`Throttled. Waiting ${waitTime}ms...`);
await new Promise(resolve => setTimeout(resolve, waitTime));
continue;
}
return data;
}
throw new Error('Max retries exceeded');
}
```
---
## Cursor-Based Pagination
```graphql
query GetProducts($first: Int, $after: String) {
products(first: $first, after: $after) {
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
title
}
}
}
}
```
**JavaScript iteration:**
```javascript
const allProducts = [];
let hasNextPage = true;
let endCursor = null;
while (hasNextPage) {
const data = await executeQuery(GET_PRODUCTS, {
first: 50,
after: endCursor,
});
const { edges, pageInfo } = data.products;
allProducts.push(...edges.map(e => e.node));
hasNextPage = pageInfo.hasNextPage;
endCursor = pageInfo.endCursor;
}
```
---
## 30 Essential Operations
### Product Management
**1. Create Product**
```graphql
mutation CreateProduct($input: ProductInput!) {
productCreate(input: $input) {
product {
id
handle
title
status
}
userErrors {
field
message
}
}
}
```
**2. Update Product**
```graphql
mutation UpdateProduct($input: ProductInput!) {
productUpdate(input: $input) {
product {
id
title
updatedAt
}
userErrors {
field
message
}
}
}
```
**3. Create Variants (Bulk)**
`Preview of the first 4,000 characters. Read full instructions →
---
name: admin-rest
description: "Use the legacy REST Admin API only when maintaining an existing integration. Covers common resources, the 40-request bucket with a 2-request-per-second standard restore rate, and migration to GraphQL. New public apps must use the GraphQL Admin API."
---
## When to Use REST API (Rarely)
**LEGACY API WARNING:** Shopify has classified the REST Admin API as legacy since October 1, 2024. Since April 1, 2025, new public apps must use the GraphQL Admin API exclusively. Shopify has not published a blanket December 2026 shutdown date for every REST resource.
Use REST API ONLY for:
- Maintaining existing legacy applications built before 2024
- Simple read-only queries from archived systems
- Temporary compatibility layers during GraphQL migration
- Systems that cannot be updated to use GraphQL
**MIGRATE TO GRAPHQL FOR:** All new features, bulk operations, cost efficiency, and latest Shopify functionality.
---
## REST vs GraphQL Comparison
| Feature | REST (Legacy) | GraphQL (Current) |
|---------|---------------|-------------------|
| Rate Limiting | 40-request standard bucket, restored at 2 requests/sec | Cost-based; restore rate varies by plan |
| Pagination | Limit/offset (inefficient) | Cursor-based (Relay) |
| Field Selection | Fixed response (bloated) | Precise fields only |
| Bulk Operations | Sequential requests | Native JSONL bulk |
| Latest Features | Some newer features are GraphQL-only | Current platform features |
| Support Window | Versioned; verify the selected version and resource | Versioned; verify the selected version |
| Status | Maintenance only | Production active |
---
## API Endpoint Structure
**Base URL:** `https://{shop}.myshopify.com/admin/api/2025-10/`
**Authentication (Header):**
```bash
curl -X GET "https://store.myshopify.com/admin/api/2025-10/products.json" \
-H "X-Shopify-Access-Token: {access_token}"
```
The examples below use `2025-10` for compatibility with older integrations. Before deploying, select a currently supported API version from Shopify's version schedule and test the exact resources you use.
---
## Rate Limiting
**REST limits:**
- Standard limit: a 40-request bucket per app and store
- Standard restore rate: 2 requests per second
- Shopify Plus: limits are typically 10 times the standard limit
- Read `X-Shopify-Shop-Api-Call-Limit` and honor `Retry-After`; Shopify can reduce limits temporarily
**Rate limit headers:**
```
X-Shop-API-Call-Limit: 30/40
X-Inventory-API-Call-Limit: 20/40
Retry-After: 2
```
**Handling 429 (Too Many Requests):**
```javascript
async function executeWithRetry(url, options, maxRetries = 5) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get('Retry-After')) || Math.pow(2, attempt - 1);
console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}
```
---
## Common Legacy REST Resources
### Products
**1. List Products**
```bash
GET /admin/api/2025-10/products.json?limit=50&status=active
```
Response:
```json
{
"products": [
{
"id": 123456789,
"title": "Wireless Headphones",
"handle": "wireless-headphones",
"status": "active",
"vendor": "TechBrand",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2025-10-15T14:30:00Z"
}
]
}
```
**2. Get Single Product**
```bash
GET /admin/api/2025-10/products/{id}.json
```
**3. Create Product**
```bash
POST /admin/api/2025-10/products.json
```
Body:
```json
{
"product": {
"title": "New Product",
"product_type": "Electronics",
"vendor": "MyVendor",
"status": "active"
}
}
```
**4. Update Product**
```bash
PUT /admin/api/2025-10/products/{id}.json
```
Body:
```json
{
"product":Preview of the first 4,000 characters. Read full instructions →
--- name: app-accessibility description: "Use when auditing or building accessibility in a Shopify embedded app — WCAG 2.1 AA, keyboard navigation, focus management in Modal/SaveBar/ResourcePicker, screen reader support (NVDA/JAWS/VoiceOver), color contrast within Polaris tokens, ARIA usage, alt text, i18n + a11y, and Built for Shopify accessibility gates. Triggers: 'accessibility shopify app', 'a11y shopify', 'WCAG 2.1 AA', 'screen reader shopify', 'keyboard nav shopify app', 'focus management modal', 'polaris contrast', 'color contrast shopify', 'aria label polaris', 'shopify accessibility audit', 'built for shopify accessibility'." --- # Shopify Embedded App Accessibility (WCAG 2.1 AA) Accessibility is a Built for Shopify gate and a legal requirement (ADA Title III, European Accessibility Act took effect 2025-06-28). Audited apps fail BFS review when keyboard navigation breaks inside iframes, focus indicators are stripped, alt text is missing on product imagery, or color contrast drops below 4.5:1. This skill is the checklist for every embedded app feature. ## 1. When to Use Trigger this skill when: - Building any new screen, Modal, SaveBar, or form in an embedded app - Auditing an existing app before Built for Shopify submission - Investigating a merchant complaint about keyboard or screen reader usage - Reviewing a PR that touches focus, ARIA, color, or alt text - Deciding whether to override a Polaris token (almost never — see Section 6) - Adding i18n / RTL support that touches reading order, aria-label strings, or lang attributes - Pairing with `polaris-ui` (component usage) or `app-bridge` (Modal/SaveBar) — this skill is the a11y overlay on top of both Do NOT use this skill for storefront / theme accessibility — that is a separate domain (`shopify.dev/docs/storefronts/themes/best-practices/accessibility`). ## 2. WCAG 2.1 AA Criteria Applied to Shopify Apps Shopify Polaris targets WCAG 2.1 A and AA by default. Embedded apps inherit that baseline only if you use Polaris components correctly and do not override semantics, contrast, or focus. The criteria that matter most for admin apps: **Perceivable** - 1.1.1 Non-text Content (A) — every image, icon-only button, and chart needs a text alternative - 1.3.1 Info and Relationships (A) — use semantic HTML; `<Text as="h2">` not `<Text variant="headingMd">` on a paragraph - 1.3.5 Identify Input Purpose (AA) — use `autoComplete` on email, name, address, tel inputs - 1.4.3 Contrast Minimum (AA) — 4.5:1 for text under 18pt, 3:1 for large text - 1.4.11 Non-text Contrast (AA) — 3:1 for form borders, focus rings, icons that convey state - 1.4.10 Reflow (AA) — content must reflow at 320 CSS px width; no horizontal scroll inside the iframe - 1.4.12 Text Spacing (AA) — line height 1.5x font-size, paragraph spacing 2x; Polaris defaults pass **Operable** - 2.1.1 Keyboard (A) — every interactive element reachable and operable via keyboard - 2.1.2 No Keyboard Trap (A) — except in Modal, focus must be able to leave any region - 2.4.3 Focus Order (A) — DOM order matches visual order; do not reorder with positive `tabindex` - 2.4.7 Focus Visible (AA) — never set `outline: none` without a replacement - 2.5.5 Target Size (AAA, but BFS-watched) — interactive targets at least 44x44 CSS px **Understandable** - 3.1.1 Language of Page (A) — `<html lang="en">` set at the embedded app's HTML root, not the Shopify admin's - 3.2.2 On Input (A) — changing a `<Select>` value must not auto-submit or auto-navigate - 3.3.1 Error Identification (A) — TextField `error` prop populated; never rely on red border alone - 3.3.2 Labels or Instructions (A) — every TextField has a non-empty `label` **Robust** - 4.1.2 Name, Role, Value (A) — custom widgets must expose accessible name + role + state - 4.1.3 Status Messages (AA) — Toasts and Banners must be announced (Polaris Toast uses `role="status"` automatically) ## 3. Top 20 Accessibility Failures in Embedded Apps | # | Failure | Fix | |---|--------
Preview of the first 4,000 characters. Read full instructions →
---
name: app-auth
description: "Implement OAuth 2.0, Token Exchange, Managed Installation, App Proxy, and webhook verification for Shopify apps. Support online/offline tokens, session storage (Prisma, Redis, Memory), and multi-auth patterns. Covers admin API, public apps, custom apps, and customer account authentication. Triggers include: 'Shopify authentication', 'OAuth 2.0', 'Token Exchange', 'Managed Installation', 'App Proxy', 'Webhook signature', 'HMAC verification', 'Admin API auth', 'Customer Account API', 'Session storage', 'Online token', 'Offline token', 'Remix auth', 'shopify auth'."
---
# Shopify App Authentication
Shopify provides multiple authentication flows depending on your app type and use case. The modern standard is **Token Exchange** (2024+) for server-rendered apps, **Managed Installation** for headless apps, and **OAuth 2.0 Authorization Code Grant** for legacy/custom implementations. All flows result in an access token for the Shopify GraphQL Admin API.
## Authentication Flows Overview
### 1. Token Exchange (Recommended for 2024+)
**Use Case:** Server-rendered apps (Remix, Next.js with SSR), Shopify CLI apps
**Flow:** Merchant installs app → Shopify generates temporary exchange token → App exchanges for access token
**Security:** No client secret exposed; uses PKCE-style rotation per request
**Token Lifetime:** Access tokens are short-lived; refresh tokens rotate automatically
**Token Exchange Diagram:**
```
1. Merchant clicks "Install" in Shopify Admin
2. Shopify redirects: https://your-app.com/auth/callback?code=EXCHANGE_TOKEN
3. App validates HMAC, exchanges code for access token (private, server-side only)
4. Shopify Admin API grants scopes; token stored in session/database
5. Token auto-refreshes on next request if expired
```
**Remix Implementation (Token Exchange):**
```typescript
// shopify.app.ts (App Configuration)
import { shopifyApp } from '@shopify/shopify-app-remix/server';
import { restResources } from '@shopify/shopify-api/rest/admin/2026-07';
import { PrismaSessionStorage } from '@shopify/shopify-app-session-storage-prisma';
import { prisma } from '~/db.server';
const shopify = shopifyApp({
apiKey: process.env.SHOPIFY_API_KEY || '',
apiSecret: process.env.SHOPIFY_API_SECRET || '',
scopes: process.env.SCOPES?.split(',') || [
'write_products',
'read_products',
'write_orders',
'read_orders',
'write_customers',
'read_customers',
'write_discounts',
'read_discounts',
'write_fulfillments',
'read_fulfillments',
'write_inventory',
'read_inventory',
],
appUrl: process.env.SHOPIFY_APP_URL || 'http://localhost:3000',
auth: {
path: '/auth',
callbackPath: '/auth/callback',
},
webhooks: {
path: '/webhooks',
},
isEmbeddedApp: true, // Polaris admin dashboard
sessionStorage: new PrismaSessionStorage(prisma),
restResources, // Includes REST API helpers
});
export default shopify;
```
**Environment Variables (.env):**
```bash
SHOPIFY_API_KEY=your-public-api-key-from-partner-dashboard
SHOPIFY_API_SECRET=your-private-api-secret
SHOPIFY_APP_URL=https://your-domain.ngrok.io # or prod URL
SCOPES=write_products,read_products,write_orders,read_orders
```
**Auth Routes (routes/auth.$.tsx - Catch-all route):**
```typescript
import { redirect } from '@shopify/remix-oxygen';
import { authenticate } from '~/shopify.server';
export const loader = async ({ request }) => {
const { authenticate } = await import('~/shopify.server');
return authenticate.admin(request); // Token Exchange happens here
};
```
**Callback Handling (routes/auth.callback.tsx):**
```typescript
import { json } from '@shopify/remix-oxygen';
import { authenticate } from '~/shopify.server';
export const loader = async ({ request }) => {
const { session } = await authenticate.admin(request);
// Session contains:
// - session.accessToken (valid for API calls)
// - session.shop (merchant's shop domain)
// - session.scope (granted scopes)
/Preview of the first 4,000 characters. Read full instructions →
---
name: app-billing
description: "Implement recurring, usage-based, one-time, and hybrid Shopify app billing. Covers appSubscriptionCreate, appUsageRecordCreate, trials, capped amounts, replacement behavior, test mode, current revenue-share rules, and pricing tiers."
---
# Shopify App Billing
Shopify apps can charge merchants through Shopify's billing system. Charges are collected via the merchant's Shopify payment method and appear on their bill. Three models are supported: **recurring** (fixed monthly/annual), **usage-based** (pay-per-action), and **one-time** (one-off charges). You can also combine them (hybrid).
## Revenue Share Model
For developers eligible for Shopify's standard rates:
- You keep **100% of the first $1,000,000 USD in lifetime gross app revenue earned from January 1, 2025**.
- Above that threshold, Shopify's revenue share is **15%**, so you keep **85%** before other fees and taxes.
- All billing is separately subject to a **2.9% processing fee**, applicable sales tax, and potentially regional regulatory fees.
- Shopify applies special eligibility rules to very large developers and aggregates revenue across associated developer accounts. Verify the current policy before financial modeling.
This means your pricing directly affects what you keep:
```
App charges $10 while eligible for the 0% revenue-share tier
├─ Merchant pays: $10.00
├─ Processing fee: $0.29, before tax or regional fees
└─ Developer amount before tax/regional fees: $9.71
App charges $100 above the $1M lifetime threshold
├─ Merchant pays: $100.00
├─ Revenue share: $15.00
├─ Processing fee: $2.90, before tax or regional fees
└─ Developer amount before tax/regional fees: $82.10
```
**Planning rule:** Model revenue share, processing fees, taxes, refunds, and cost to serve separately; don't assume gross charges equal payout.
## Billing Models
### 1. Recurring (Fixed Interval)
**Use Case:** Subscription model (e.g., "Pro plan $99/month")
**Charging:** First charge immediate on approval; subsequent charges on anniversary date
**Cancellation:** Merchant can cancel anytime; charged through current period end
**appSubscriptionCreate Mutation:**
```graphql
mutation CreateRecurringSubscription {
appSubscriptionCreate(
input: {
trialDays: 7
lineItems: [
{
plan: {
appRecurringPricingDetails: {
interval: MONTHLY # or ANNUAL
price: { amount: "9.99", currencyCode: "USD" }
}
}
}
]
returnUrl: "https://your-app.com/billing/confirm"
}
) {
appSubscription {
id
confirmationUrl # Merchant must visit this URL to approve
lineItems {
id
plan {
pricingDetails {
... on AppRecurringPricingDetails {
interval
price { amount currencyCode }
}
}
}
}
status # PENDING, ACTIVE, DECLINED, EXPIRED, FROZEN, CANCELLED
currentPeriodEnd
trialDays
trialEndsOn
}
userErrors {
field
message
}
}
}
```
**Remix Implementation (Recurring Billing):**
```typescript
import { json, redirect } from '@shopify/remix-oxygen';
import { authenticate } from '~/shopify.server';
export const action = async ({ request }) => {
if (request.method !== 'POST') return json({ error: 'POST only' }, { status: 405 });
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(`
mutation CreateRecurringSubscription($input: AppSubscriptionInput!) {
appSubscriptionCreate(input: $input) {
appSubscription {
id
confirmationUrl
status
currentPeriodEnd
lineItems {
id
plan {
pricingDetails {
... on AppRecurringPricingDetails {
interval
price { amount currencyCode }
}
}
}
Preview of the first 4,000 characters. Read full instructions →
---
name: app-bridge
description: "When asked to build Shopify admin apps, use App Bridge 4.x web components, shopify global API, session tokens, JWT validation, and migrations from 3.x. Covers CDN setup, all 8 web components, resource picker API, React hooks, backend JWT validation, and 5 worked examples."
---
# Shopify App Bridge 4.x: Web Components, Sessions & Admin Apps
## When Asked...
- **"Build a Shopify admin app"** → Use App Bridge 4.x with web components; load via CDN with data-api-key; use shopify global object for actions
- **"Add save/cancel buttons"** → Use `<ui-save-bar>` web component with data-primary-action and data-secondary-action attributes
- **"Show a confirmation modal"** → Use `<ui-modal>` web component with data-open attribute and slot-based content
- **"Display success message"** → Use `shopify.toast()` method with title, message, duration, isError flags
- **"Let user pick products/customers"** → Use resource picker API: `shopify.resourcePicker({ type: 'product' })`
- **"Validate backend requests"** → Exchange session token for JWT; verify JWT signature with Shopify's public key
- **"Upgrade from App Bridge 3.x"** → Follow migration checklist: remove AppProvider, update component usage, use web components directly
## App Bridge 4.x Architecture
App Bridge 4.x is a **web components-first framework**. The major shift from 3.x:
- **No AppProvider needed** — directly use web components and shopify global object
- **Native web components** — built-in elements like `<ui-modal>`, `<ui-save-bar>`, `<ui-toast>` instead of React/Vue wrappers
- **shopify global object** — replaces AppBridge context; provides toast(), modal(), navigate(), loading(), idToken(), etc.
- **Session tokens** — automatic JWT exchange for backend authentication
- **CDN-first delivery** — loaded via script tag with data-api-key; works in any HTML/framework
## Installation & CDN Setup
### CDN Script (Recommended for Admin Apps)
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Shopify Admin App</title>
</head>
<body>
<div id="app"></div>
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"
data-api-key="YOUR_PUBLIC_API_KEY"
data-host="{{ request.host }}">
</script>
<script>
// shopify global object is now available
console.log(shopify);
</script>
</body>
</html>
```
**data-api-key**: Your Shopify public app API key (from shopify.app configuration)
**data-host**: Base64-encoded host parameter (usually `{{ request.host }}` in server templates)
### npm Package (for React/Node.js apps)
```bash
npm install @shopify/app-bridge @shopify/app-bridge-react
```
```typescript
import { initializeApp } from '@shopify/app-bridge';
const app = initializeApp({
apiKey: process.env.REACT_APP_SHOPIFY_API_KEY,
host: new URLSearchParams(location.search).get('host'),
});
console.log(window.shopify);
```
## shopify Global Object API
The **shopify global** provides the primary API for app interactions:
```typescript
// Toast notifications
shopify.toast({
title: 'Success',
message: 'Settings saved',
duration: 3000,
isError: false,
});
// Modal dialogs
shopify.modal.show({
title: 'Confirm Action',
message: 'Are you sure?',
buttons: [
{ label: 'Cancel', type: 'secondary' },
{ label: 'Delete', type: 'primary', isDestructive: true },
],
});
// Navigation
shopify.navigate({ name: 'Admin::Product::Index' });
shopify.navigate({ url: '/admin/products/new' });
// Loading state
shopify.loading.dispatch(true);
shopify.loading.dispatch(false);
// Session token (JWT for backend calls)
const idToken = await shopify.idToken();
// Current app environment
shopify.environment // 'Admin' | 'Checkout' | 'Mobile' | 'POS'
shopify.config // { apiKey, host, theme }
// Deep linking
shopify.actions.Admin?.navigate({ path: '/products' });
```
## Web Components API
App Bridge 4.x provides 8 nativPreview of the first 4,000 characters. Read full instructions →
--- name: app-listing-optimization description: "Optimize your Shopify App Store listing to maximize install velocity and conversion. Covers ranking factors, title/tagline formulas, description structure, screenshot strategy, A/B testing, and a 30-item pre-submission checklist. Triggers include: 'How do I optimize my Shopify app listing?', 'What's the App Store ranking algorithm?', 'How should I write my app title and description?', 'What makes a good app screenshot?', 'How do I increase app install velocity?', 'Will my app title get rejected?', 'How do I improve my app store SEO?', 'What's the best pricing plan layout?', 'How do I A/B test my listing?', 'App Store listing checklist', 'Help me optimize my app listing', 'Why is my app not getting installs?'." --- ## When to Use This Skill You're building a Shopify app and need to maximize discoverability and conversion from listing visit → install → trial activation → paid customer. This skill guides you through the mechanics of Shopify App Store ranking, listing copy psychology, visual assets, and pre-submission validation. Use this when: - You have an MVP ready for App Store submission - Your app is live but getting <10 installs/week - You want to optimize pricing presentation - You need to understand what the Shopify algorithm actually rewards - You're A/B testing your listing --- ## The Shopify App Store Ranking Algorithm: What Actually Matters Shopify's search ranking is **opaque but pattern-driven**. Your ranking is determined by these factors (approximate weights): | Factor | Weight | What It Means | How to Optimize | |---|---|---|---| | **Install Velocity** | 35% | Installs per week in past 30 days | Pre-launch with waitlist, drive first-week traffic, ask beta customers to install day 1 | | **Uninstall Rate** | 25% | % of installs that uninstall | Focus on retention, quick onboarding, bug fixes | | **Rating + Review Recency** | 20% | 5-star ratings + freshness of reviews | Ask satisfied customers for reviews within 48h of install | | **Title Keyword Match** | 10% | Does your title contain the searched keyword? | Use problem + benefit in title | | **Category Fit + Specificity** | 10% | Is the app in the right category? | Choose most specific category available, don't try multiple | **Critical insight:** Install velocity is 35% of the ranking algorithm. This means a 3-day launch sprint where you drive 50 installs beats slow organic growth. Your ranking in week 1 determines your visibility for months. **Conversion benchmarks (typical):** - App Store listing visit → install: **3-8%** (varies by category, copy quality) - Free install → trial activation: **40-65%** (depends on onboarding clarity) - Trial → paid conversion: **15-35%** (depends on price fit + product quality) --- ## Listing Copy Architecture: The Formula That Works ### 1. App Title (50 Characters Max) **Formula:** [Brand Name] - [Problem Solved] or [Brand Name] - [Primary Benefit] **Rule:** Use ONE primary keyword. Don't cram. | Example | Why It Works | Why It Fails | |---|---|---| | ✅ Printful - Print on Demand Fulfillment | Brand + problem clarity | N/A | | ❌ Printful Print on Demand Fulfillment App | Too long (50 char limit) | Exceeds character limit | | ✅ Gorgias - AI Customer Support | Brand + key benefit | N/A | | ❌ Gorgias Customer Support Software for Shopify Stores | Way too long | Loses all ranking benefit | | ✅ Loop Returns - Reverse Logistics | Brand + problem solved | N/A | | ❌ Loop | Ambiguous, no keyword | Zero SEO value | **SEO Psychology:** Shopify's algorithm matches the title keyword against search queries. If a merchant searches "print fulfillment," your title "Printful - Print on Demand Fulfillment" matches TWO keywords. You rank higher than "Printful" alone. ### 2. Subtitle / Tagline (150 Characters Max) **Formula:** [Action] + [Problem] + [Specific Benefit] or [Outcome] **Rule:** Speak directly to the merchant's pain, not features. | Example | Works? | Why | |---|---|-
Preview of the first 4,000 characters. Read full instructions →
--- name: app-naming description: "Use when naming a new Shopify app, evaluating an app name candidate, running a trademark check, optimizing the app name for App Store SEO, or brainstorming brand candidates. Triggers: 'name my shopify app', 'app naming', 'app store SEO', 'trademark check', 'brand my app', 'what should I call my shopify app', 'brand domain', 'shopify app name', 'rename my app', 'is this app name taken', 'trademark Shopify'." --- # Shopify App Naming & Trademark Strategy ## Frontmatter Triggers When users ask: - "What should I name my Shopify app?" - "Is [name] a good app name?" - "How do I check if my app name is trademarked?" - "What naming patterns work for Shopify apps?" - "Should I trademark my app name?" - "Help me generate app name ideas" - "Will Shopify reject my app name?" Then execute this skill. --- ## When to Use This Skill **Use this skill when:** - You've chosen a niche/problem to solve but need a name - You want to validate naming choices before building - You're unsure if your name will pass Shopify's review - You're torn between multiple name options - You want to ensure trademark safety before launch **Don't use this skill for:** - Naming internal projects (not going to Shopify App Store) - Personal website names (different rules apply) - Broader brand positioning (see Marketing skill instead) --- ## The Naming Minefield: What Shopify Will Reject ### Hard Rejects (Automatic Rejection) Shopify **will reject** your app if the name contains: 1. **"Shop" or "Shopify"** (Shopify's protected trademark) - ❌ "ShopPrinter" (Rejected) - ❌ "Shopify Bundle Builder" (Rejected) - ✅ "Bundle Blitz" (Approved) 2. **Brand names without permission** (Stripe, PayPal, Twilio, etc.) - ❌ "Stripe Invoicer" (Rejected) - ❌ "PayPal Direct Sync" (Rejected) - ✅ "Invoice Pro" (Approved) 3. **Generic/overused terms** that confuse identity - ❌ "Store Manager" (too generic, high competition) - ❌ "Sales Tool" (meaningless) - ✅ "Profit Dashboard" (specific problem, brandable) 4. **Acronyms that are registered trademarks** - ❌ "CRM Pro" (CRM is trademarked in some contexts) - ❌ "API Dashboard" (API is too generic) - ✅ "Pipeline Manager" (clear, branded) 5. **Offensive, vulgar, or discriminatory language** - ❌ Any slurs or explicit content - ✅ Professional language only ### Soft Rejects (Likely Rejection) Shopify **will likely reject** if the name: - **Sounds too similar to existing apps** (Judge.me vs Judge Pro vs Judge.ai) - Research: Search "Shopify app [your proposed name]" before committing - **Is hard to spell or pronounce** - Merchants won't search for it - You'll get 50% fewer organic installs - Example: "Zycphlax" vs "Smart Bundle" - **Has zero brand personality** (feels like generic software) - ❌ "App Tool" (no personality) - ✅ "Printful" (memorable, branded, implies speed) - **Implies features you don't have** - ❌ "Smart AI Optimizer" (if you have zero AI) - ✅ "Bundle Builder" (honest about what you do) --- ## The Naming Formula That Works ### Core Formula: [Action Verb] + [Problem Area] + [Differentiator] **Anatomy breakdown:** | Component | Purpose | Examples | |-----------|---------|----------| | **Action Verb** | Shows what the app DOES | Recover, Loop, Seal, Print, Collect, Automate, Boost, Convert | | **Problem Area** | What problem it solves | Returns, Subscriptions, Bundles, Referrals, Support, Analytics | | **Differentiator** | Why it's better/different | AI-first, Fast, Smart, Pro, Ultimate, Direct, Real-time | ### Real App Analysis Using the Formula | App Name | Formula Breakdown | Why It Works | |----------|-------------------|-------------| | **Printful** | Print (action) + Fulfillment (problem) + Full (completeness) | Implies speed, handles everything, memorable | | **Gorgias** | Handle (implied) + Support (problem) + AI-First (diff) | Suggests quick response, modern approach | | **ReConvert** | Recover (action) + Purch
Preview of the first 4,000 characters. Read full instructions →
--- name: app-niche-finder description: "Find profitable, underserved Shopify app niches. Identifies gaps in the App Store by analyzing competitor density, merchant pain signals, and buildability constraints. Returns ranked ideas with TAM, competition score, and first-mover advantage assessment. Triggered on: 'shopify app idea', 'find niche', 'app store opportunity', 'underserved category', 'gap analysis', 'competitor with bad reviews', 'app idea validation', 'what shopify app should I build', 'shopify app niche', 'find a profitable app idea'" --- ## When to Use This Skill Call this when: 1. **Finding a problem to solve:** Merchant identifies pain in own store, needs to verify market viability 2. **Validating category fit:** Founder has app idea, wants to assess competition density 3. **Generating ideas from scratch:** Founder has skills but no clear problem direction 4. **Competitive analysis:** App exists, needs to understand gap analysis before building **Do NOT use this if:** - You're building in oversaturated categories (email, basic pop-ups, product reviews) - The idea requires deep ML infrastructure one founder can't handle - Shopify is likely to ship natively (Shopify's roadmap moves fast) --- ## The 3-Step Gap-Finding Framework **Step 1: Low-App-Count Category** Search Shopify App Store for the problem category. Count competitors doing similar thing well. - **Tier 1 opportunity:** 0-3 real competitors (established, but not saturated) - **Tier 2 opportunity:** 4-6 competitors (some fragmentation, room for differentiation) - **Red flag:** 8+ competitors all with 4.5+ rating (category is won) **Step 2: High-Merchant-Pain Signal** Find evidence merchants actively complain about this problem. - **App Store reviews:** Low-star reviews on competitor apps (what's missing?) - **Reddit r/shopify:** Search for problem keyword, count complaint posts - **Shopify Community:** Same search—frequency of "how do I fix this?" posts - **Twitter merchant complaints:** Search "Shopify [problem]" + filter recent - **Built for Shopify gaps:** Check what gaps exist in official Shopify integrations **Step 3: Buildable-by-One-Person** Can a solo founder build this in 4 weeks to MVP? - **Yes:** Webhook-based tools, dashboard apps, simple automations - **Maybe:** Requires API integration learning curve (Stripe, Twilio, etc.) - **No:** ML models, real-time data processing, complex 3rd-party orchestration --- ## Demand Signals to Scrape **App Store Low-Rating Reviews** (High-intent feedback) Look at competitor apps with 3.0-4.0 star ratings. Read 1-star and 2-star reviews. - Extract complaint phrases: "I wish it had...", "Missing feature:", "Doesn't work with..." - Tally recurring complaints (if 5+ reviews mention the same gap, that's a real gap) - Example gap: "Post-purchase page builder—everyone mentions lack of email capture" **Reddit r/shopify** (Organic merchant voice) - Search: "How do I [problem]" or "Does Shopify have [feature]" - Frequency signal: If same question appears 20+ times in past year, it's a real pain - Sentiment: Are merchants frustrated? Do they say "I just build custom code"? **Shopify Community Forums** (Official support) - Search community.shopify.com for problem keyword - Flag: If Shopify support says "Use an app" but no good app exists, that's a gap - Count posts: More than 30 posts about a problem = searchable demand **Twitter Merchant Complaints** (Real-time signal) - Search: "Shopify" + problem keyword (e.g., "Shopify returns" or "Shopify bundles") - Filter: Last 3 months only (current pain) - Retweet count: If merchants are retweeting complaints, it's a shared problem **Built for Shopify Gaps** (Official integrations missing) - Check what Shopify has NOT built natively - Example: Shopify has inventory sync but no predictive forecasting - Absence + merchant complaints = clear opportunity --- ## Tier-1 / Tier-2 / Tier-3 Idea Taxonomy **Tier 1: $2-5M Addressable Market** (Fastest path to $1k MRR) - Low
Preview of the first 4,000 characters. Read full instructions →
--- name: app-performance description: "Use when optimizing Shopify embedded app performance — LCP, INP, CLS, TTI, cold-start, App Bridge init, Polaris bundle slimming, large GraphQL costs, Remix defer/streaming/prefetch, image lazy-loading, server cache + CDN, Prisma connection pooling, webhook handler latency, and meeting Built for Shopify performance gates. Triggers: 'app slow', 'embedded app performance', 'LCP shopify app', 'INP shopify', 'app bundle too big', 'polaris bundle slim', 'remix defer', 'prefetch intent', 'shopify app lighthouse', 'shopify performance budget', 'built for shopify performance', 'image lazy load shopify', 'graphql query cost', 'n+1 prisma'." --- # Shopify Embedded App Performance Fix slow Shopify embedded apps before Built for Shopify rejects them, merchants uninstall, and Shopify demotes you in App Store search. The Web Vitals are the gate. Everything below is how you walk through it. --- ## 1. When to use this skill Trigger this skill when: - `shopify app dev` runs but the embedded iframe takes 4+ seconds to render - BFS review comes back "fails performance" with no specifics - Lighthouse on your admin route scores below 70 - Web Vitals API reports LCP > 2.5s, INP > 200ms, or CLS > 0.1 over 28 days - Your bundle is > 500KB gzipped and you don't know why - GraphQL queries are returning `THROTTLED` (as 200 OK, not 429) - Prisma queries take 800ms+ in production but 40ms locally - Webhook handlers are taking > 2 seconds and triggering Shopify retries - A merchant DMs you "your app is the slowest thing in my admin" - You're about to submit for Built for Shopify and want to pass on the first try Don't use this skill for storefront / theme performance — that's a different problem (theme app extensions, web pixels, checkout extensions). This skill is about the admin embedded surface and the server behind it. --- ## 2. Built for Shopify performance thresholds (current) These are the exact numbers. Memorize them. ### Core Web Vitals (admin, measured via App Bridge Web Vitals API) | Metric | Threshold | Measurement window | Min sample size | |--------|-----------|--------------------|-----------------| | **LCP** (Largest Contentful Paint) | ≤ 2.5s (p75) | 28 days | 100 calls | | **INP** (Interaction to Next Paint) | ≤ 200ms (p75) | 28 days | 100 calls | | **CLS** (Cumulative Layout Shift) | ≤ 0.1 (p75) | 28 days | 100 calls | | **TTI** (Time to Interactive) | Aim ≤ 3.8s | Internal target | — | p75 means 75% of measured launches must be at or under the threshold. One slow merchant doesn't sink you — the long tail does. ### Server / API performance | Metric | Threshold | |--------|-----------| | **API p95 latency** | < 500ms | | **API failure rate** | < 0.1% | | **Min requests** (28 days) | 1000 (for checkout-adjacent apps) | | **Webhook ACK** | < 5s before Shopify retries (target < 2s) | ### Storefront-side requirements (if you ship Theme App Extensions) - Your app must not reduce the storefront Lighthouse performance score by more than **10 points** - Per-surface storefront JS budget: **< 50KB gzipped** is the rule of thumb most pass on ### Iframe gotcha Apps rendered in the Shopify admin run inside iframes. Lighthouse run against your raw URL is misleading — it doesn't model the App Bridge bootstrap, the parent admin chrome, or the cross-origin handshake. The only metric that matters for BFS is what the **Web Vitals API inside App Bridge** reports. Wire that up first or you're flying blind. --- ## 3. Where embedded app slowdowns come from In order of how often they're the culprit: ### 3.1 Server cold start (40% of slow first-loads) Your Remix server is on a serverless / scale-to-zero runtime (Fly Machines stopped, Vercel Lambda cold, Render free tier). First request from a merchant pays a 2-5 second cold-boot tax. Every metric is now blown. ### 3.2 App Bridge initialization The App Bridge CDN script must load and the parent admin must complete the postMessage handshake before you
Preview of the first 4,000 characters. Read full instructions →
--- name: app-pricing-strategy description: "Use when designing Shopify app pricing, choosing a pricing model (flat tiered / usage-based / freemium / hybrid), setting trial length (7/14/30 days), structuring 3-4 tier plans, sizing capped usage, raising prices on existing customers, or writing pricing copy for the App Store listing. Triggers: 'shopify app pricing', 'app pricing tiers', 'free trial length', 'usage based pricing', 'recurring vs one-time', 'capped pricing', 'pricing strategy', 'monetization', 'how should I price my shopify app', 'shopify app monetization', 'MUST_USE_BILLING', 'raise app prices'." --- # Shopify App Pricing Strategy ## Frontmatter Triggers - "How much should I charge for my app?" - "What's the best pricing model for my Shopify app?" - "Should I do free, freemium, or paid-only?" - "How do I price a usage-based app?" - "What's the right free trial length?" - "How do competitors price similar apps?" - "When and how should I raise my prices?" - "How do I structure my pricing tiers?" --- ## The Four Proven Pricing Models ### 1. Flat Tiered (Most Common) **When:** 90% of successful Shopify apps use this. Pick it unless you have a reason not to. **How it works:** - 3–4 fixed price points (e.g., Starter $9.99, Growth $29.99, Scale $99.99) - Each tier unlocks fixed feature sets + user/order limits - Revenue is completely predictable - Easy to communicate **Real Shopify examples:** - **Klaviyo Email Marketing:** Free, $20, $50, $150, $500/mo (tier by contact count) - **Gorgias Help Desk:** Free, $50, $150, $400, $1000/mo (tier by conversation volume) - **Printful Print-on-Demand:** Free + rev-share, then flat fees by service tier **Conversion lift by tier:** - Starter tier: 40–60% of free trial users convert - Growth tier: 15–25% of Starter converts to Growth - Scale tier: 5–10% of Growth converts to Scale **Shopify revenue share and fees:** - Eligible standard-rate developers keep 100% of the first $1M in lifetime gross app revenue earned since January 1, 2025. - Above $1M, Shopify's revenue share is 15% and the developer keeps 85% before other fees and taxes. - All billing also has a separate 2.9% processing fee, applicable sales tax, and possible regional fees. - Revenue is aggregated across apps and associated developer accounts. Very large developers have separate eligibility rules. **Pro tip:** Design tiers so the "sweet spot" (Growth/Scale tier) is your profit engine. Starter should feel limited but functional. Scale should feel unreachable to most but desirable. --- ### 2. Usage-Based (For Data/Computation/API Heavy) **When:** Your cost to serve grows with merchant activity (emails sent, API calls, storage, image uploads) **How it works:** - Base fee ($0–$50/mo) + overage charges (e.g., $0.01 per email sent) - Usage counted: emails sent, API calls, MB stored, images processed, orders synced - Revenue scales with merchant success - Harder to forecast for merchants but fair **Real Shopify examples:** - **ReConvert Upsell:** Base $30/mo + $0.10 per order after 1,000/month - **Shopify Email:** Free for Shopify merchants, then usage-based - **Zapier:** Free tier (100 tasks/mo) + $29–$450 based on task volume **Conversion data:** - Usage-based apps see 25–35% free-to-paid conversion (higher because users feel they "only pay for what they use") - But 40% higher churn because cost visibility is higher **When NOT to use:** If your cost structure is fixed (e.g., you pay Shopify $500/mo for a data feed), don't pass overage costs to users—use flat tiers instead. --- ### 3. Freemium with Hard Cap (Most Common for Low-Price Apps) **When:** You want to capture market share and convert via upsell (not friction at signup) **How it works:** - Free tier with strict limits (e.g., 100 emails/month, 1 user, basic features) - Hard stop: users CANNOT use beyond the limit without upgrading - Paid tiers unlock limits + features - Psychology: users see the wall, then upgrade to remove friction **Real Shopify
Preview of the first 4,000 characters. Read full instructions →
--- name: app-validation description: "Validate a Shopify app idea before writing code. Runs a 7-question pre-build framework, facilitates 5-merchant interview protocol, guides landing page + waitlist test, and identifies kill criteria early. Outputs a prioritization matrix and yes/no decision. Triggered on: 'validate app idea', 'should I build this app', 'MVP scope', 'app validation framework', 'problem-solution fit', 'customer interview', 'is my shopify app idea good', 'validate my idea'" --- ## When to Use This Skill Call this when: 1. **You have an app idea** and need confidence before 4 weeks of build time 2. **You want to avoid false starts** with market validation first 3. **You need to prioritize** which app idea to build if you have multiple 4. **You're mid-build** and getting customer feedback signals **Do NOT use this if:** - You've already shipped and have paying customers (use metrics instead) - You're in execution mode and decided to build (stay focused) --- ## The 7-Question Pre-Build Validation Framework Answer all 7 questions with your best estimate. Score each 1-5 (5 = strong yes, 1 = strong no). ### Question 1: Problem Severity (Does it hurt bad enough?) "On a scale of 1-5, how much pain do merchants have right now?" - **5:** Merchants spend 5+ hours/week on this; lose money if unsolved; manual workaround fails 50%+ of the time - **4:** Spend 2-5 hours/week; workaround exists but tedious; minor money loss - **3:** Spend <2 hours/week; annoying but manageable workaround - **2:** Nice-to-have improvement; low time cost - **1:** Merchants don't really complain about this **Validation method:** Ask 5 merchants "How many hours/week does [problem] cost you?" If 4/5 say >2 hours, you're at 4-5. **Red flag:** If score <3, problem is aspirational, not acute. Merchants won't pay. --- ### Question 2: Willingness-to-Pay Signal (Will they actually pay?) "Would a typical merchant in your target market pay $X/month for this?" - **5:** Multiple merchants have said "Yes, I'd pay $50+/month for this" - **4:** 3+ merchants said "Maybe $25-30/month" unprompted - **3:** Merchants said "Maybe I'd try it if free" or "Could work at $10/month" - **2:** "I'd use it if free but wouldn't pay" - **1:** "Not worth paying for" **Validation method:** Ask in interviews: "What's the maximum you'd pay monthly for this? What's minimum to make it worth your time?" If 4/5 say >$15, score 4-5. **Red flag:** If score <3, problem is real but not monetizable. --- ### Question 3: Retention Plausibility (Will they stick around?) "If merchants start using this, will they stay for 6+ months?" - **5:** Solution is sticky by design (required for operations every day) - **4:** Daily/weekly usage; low switching cost to alternatives - **3:** Bi-weekly usage; some switching cost - **2:** Monthly usage; high switching cost (easy to stop) - **1:** One-time use; merchants will abandon after task completes **Validation method:** Ask: "Once you solve this problem, will you need to keep using it weekly?" If yes, score 4-5. If it's a one-time setup, score 1-2. **Red flag:** If score <3, churn will be >30%/month, killing unit economics. --- ### Question 4: Build Complexity vs Founder Skill (Can you actually ship?) "How complex is this to build relative to your experience?" - **5:** You've built 3+ similar apps; <4 weeks for MVP - **4:** Similar to past projects; 4-6 weeks with learning - **3:** Requires 1-2 new technologies; 6-8 weeks - **2:** Requires deep learning in unfamiliar domain; 8-12 weeks - **1:** Requires ML/distributed systems/real-time data processing; >12 weeks **Validation method:** Sketch MVP: "What are the 3 core features?" If all are API-integration or dashboard, score 4-5. If you need to learn new framework, score 3. If it requires ML, score 1-2. **Red flag:** If score <3 and you're solo, you won't finish in 90 days. Adjust scope or team up. --- ### Question 5: Distribution Path (How will they find you?) "Do you have a d
Preview of the first 4,000 characters. Read full instructions →
---
name: b2b-markets
description: "Use when building Shopify B2B catalogs, multi-storefront B2B, company location pricing, wholesale checkout, Shopify Markets (multi-region), multi-currency pricing with @inContext, currency formatting, market-specific catalogs, payment terms (NET 30/60), or anything involving B2B Plus / Markets / international commerce features. Triggers: B2B, wholesale, company, locations, customer accounts B2B, Markets, @inContext, country code, currency code, market, catalog, price list, payment terms, NET 30, draft order B2B, vaulted card, 'shopify b2b', 'shopify markets'."
---
# Shopify B2B + Markets
## When to use this skill
Call this skill when:
- Merchant is setting up wholesale, B2B, or bulk ordering
- Building company catalogs, price lists, or location-based pricing
- Implementing payment terms (NET 30, NET 60, etc.) or vaulted card checkout
- Handling Shopify Markets setup, multi-region, multi-currency, or multi-language storefronts
- Using @inContext directive for currency/language-specific Storefront API queries
- Displaying multi-currency prices in Liquid, handling exchange rates, or market-aware inventory
- Building customer account UI extensions for B2B contacts
- Webhook listeners for B2B events: company.created, companyLocation.created, companyContact.created, draftOrder.created
- Checking which features require B2B Plus plan vs Shopify Markets standard vs core Shopify
## B2B on Shopify: the fundamentals
Shopify B2B Plus enables merchants to:
- Create **companies** (e.g., "Acme Corp") with multiple **company locations** (warehouses, branches)
- Assign **catalogs** (product + pricing rules) to each location
- Set **price lists** with percentage or fixed discounts, currency-specific pricing, date ranges
- Define **payment terms** (NET 30, NET 60, custom) and enable **vaulted card** recurring payments
- Create **draft orders** for company contacts, convert to paid orders with payment terms
- Use **customer account B2B** login (company contact sign-in) with location-switching UI
**B2B Plus-only features:**
- Company object and CompanyLocation hierarchy
- PriceList and Catalog system
- PaymentTerms (NET 30+, custom days)
- DraftOrder for B2B checkout
- Customer Account B2B extensions (login UI, location switching)
**Core Shopify (all plans can do):**
- Multiple currencies (requires Shopify Markets)
- Shopify Markets regions, domains, subfolders
- @inContext for Storefront API (language/country override)
**When to recommend B2B Plus:**
- Merchant has >2 wholesale partners
- Needs tiered pricing by location or customer segment
- Wants self-service company portal (contact management, order history, payment vaults)
- Needs recurring NET-term invoicing (vaulted cards)
---
## Core B2B objects
### Company
A company record represents a wholesale customer (e.g., a distributor, retailer, or reseller).
```graphql
query {
companies(first: 10) {
edges {
node {
id # gid://shopify/Company/12345
name # "Acme Corp"
externalId # Sync ID to your CRM
metafields {
key
value
namespace
}
locations(first: 10) {
edges {
node {
id
name # "Acme - Chicago"
}
}
}
}
}
}
}
```
Mutations:
```graphql
mutation {
companyCreate(input: {
name: "Acme Corp"
externalId: "crm-12345"
}) {
company {
id
name
}
userErrors {
field
message
}
}
}
```
### CompanyLocation
Represents a specific address/warehouse for a company. Each location can have its own catalog + price list assignment.
```graphql
query {
companyLocationConnection(first: 5) {
edges {
node {
id
name
address {
address1
city
province
zip
country
}
contact {
title
Preview of the first 4,000 characters. Read full instructions →
--- name: built-for-shopify-standards description: "Prepare a Shopify app for Built for Shopify status. Covers current quality criteria, performance, accessibility, Shopify admin integration, compliance webhooks, observability, support, application readiness, and ongoing eligibility." --- # Built for Shopify Standards The official quality bar for Shopify App Store apps. Qualifying apps receive the Built for Shopify highlight and badge, additional App Store promotion, eligibility for promotion on other merchant surfaces, and priority review for future app submissions. BFS does not create a separate revenue-share tier. This skill is the full requirement matrix as of May 2026, with rejection patterns, a 50-item self-check, and a decision tree to tell you whether you're ready to apply. --- ## 1. When to use this skill Trigger this skill when: - You're planning to submit an app for the Built for Shopify (BFS) designation - You got a "fails to meet Built for Shopify standards" rejection and want to fix it - You're scoping a v1 app and want to build to BFS from the start (cheaper than retrofitting) - A merchant or partner mentioned your app "isn't Built for Shopify yet" - You're doing a 90-day audit before reapplying after a previous BFS failure - You're deciding whether the promotional benefits justify the implementation and ongoing-compliance work - You want to know exactly what "integration depth" means in BFS-speak (it's specific) - You're comparing your app against a competitor that has the badge and want to close the gap - You're hitting LCP, INP, CLS, or API p95 problems and want to know the actual gate numbers - You're wiring up GDPR webhooks and want to confirm BFS still requires all three Don't use this skill for: - General App Store submission (different bar — that's `app-validation`) - Performance debugging itself (that's `app-performance` — this skill references those thresholds but doesn't reteach them) - Polaris implementation details (that's a separate UI/design skill) - Listing copy or screenshots (that's `app-listing-optimization`) - Pricing strategy (that's `app-pricing-strategy`) This skill is the audit framework. The fix-it skills live elsewhere. --- ## 2. What Built for Shopify actually is ### 2.1 It's a designation, not a category A common misunderstanding: founders think "Built for Shopify" is a category they apply to and join. It isn't. Every BFS app stays in its primary category (Marketing, Fulfillment, etc.) and additionally earns a **badge** that displays on the App Store listing and in search results. The badge says, in effect: "Shopify has tested this app against a defined quality bar and it currently passes." It's not a permanent stamp — Shopify re-evaluates apps continuously and apps **lose BFS status** if they fall below thresholds (e.g., LCP regresses, support response time slips, a customer complaint storm hits, you start failing accessibility checks). ### 2.2 Why merchants notice the badge Shopify documents these benefits: - A Built for Shopify highlight on the app listing - A badge on App Store cards, including search results and category pages - A merchant-facing search filter for Built for Shopify apps - Additional promotion in the Shopify App Store and eligibility for promotion on other key merchant surfaces - Priority review for future app submissions from BFS developers Treat any claim about conversion lift, install velocity, ranking weight, or guaranteed featuring as an experiment to measure for your app, not as an official BFS guarantee. ### 2.3 The revenue share angle (verify the exact terms before relying on it) Shopify's revenue share for App Store developers has shifted multiple times. As of the most recent published policy update: - **First $1M USD in lifetime gross app revenue earned from January 1, 2025**: 0% revenue share (you keep 100%) - **Above $1M lifetime**: 15% revenue share (you keep 85%) Critical clarifications: - Earnings before Jan 1, 2025 don't cou
Preview of the first 4,000 characters. Read full instructions →
--- name: dev-troubleshooting description: "Use when a Shopify dev workflow is failing — `shopify app dev` cryptic errors, Cloudflare tunnel not starting, App Bridge v3→v4 migration 'No AppBridge context provided', GraphQL 200 OK with throttle errors, webhook 401, double-subscribed webhooks, app proxy 404, REST 302 loops, Rust function wasm-validator errors, session token 24h expiry, X-Frame-Options blocking iframe, dev store billing fakeouts, app review SLA blown. Triggers: 'shopify app dev failing', 'tunnel won't start', 'no app bridge context', 'throttle error 200', 'webhook 401', 'wasm validator error', 'session token expired', 'frame ancestors', 'remix template auth broken', 'billing test charge', 'shopify cli error'." --- # Shopify Dev Troubleshooting — Triage First, Fix Fast A symptom-driven triage skill for Shopify app developers. When your dev loop hits a wall, start here. Each pain below is sourced from the most-reported Reddit, Shopify Developer Community (community.shopify.dev), Shopify Community (community.shopify.com), and GitHub Shopify/* issues as of 2026-05-15. Use this skill **first** when: - `shopify app dev` exits with cryptic errors - The browser shows "No AppBridge context provided", 401, 302 loops, or 404 on `/auth/login` - GraphQL "works" but data is missing in production - Webhooks fire twice, never, or your handler keeps timing out - A Function deploys fail with `[wasm-validator error]` - App Review SLA is blown and you don't know what to do - A dev-store billing test charge silently fails If the symptom matches a row in the Diagnostic Table, jump straight to that fix. If not, work through the Decision Tree at the bottom. --- ## 1. When to Use This Skill This is the **entry point** for any "something is broken in my Shopify dev workflow" question. It is not the place to learn how to build new features — that's what the other `shopify-app-builder` skills are for. This skill is the ER, not the gym. Surface this skill when the user says any of: - "shopify app dev failing / not working / errors" - "tunnel won't start", "cloudflared", "max retries reached" - "App Bridge migration", "v3 to v4", "No AppBridge context provided" - "graphql throttled", "200 OK error", "currentlyAvailable" - "webhook 401", "double webhook", "duplicate webhook", "webhook retry" - "remix auth broken", "/auth/login 404", "nested route login" - "wasm-validator error", "wasm-opt failed", "Rust function deploy" - "session token expired", "24 hour", "iframe redirect blocked" - "X-Frame-Options", "frame-ancestors", "DENY" - "billing test charge", "Apps without public distribution" - "app review", "Built for Shopify rejected", "SLA blown" - "shopify cli error", "cannot read properties of null" If multiple symptoms match, run them in order of blast radius: production data corruption > auth break > review block > dev-loop friction. --- ## 2. The Diagnostic Table Find your symptom in column 1. Apply the fix in column 3. | # | Symptom (verbatim or close) | Likely cause | Exact fix | |---|---|---|---| | 1 | `shopify app dev` returns 403 "Cannot find a valid organization associated to this shop" | Stale auth or wrong org logged in | `shopify auth logout && shopify auth login` against the org-owning account; verify with `shopify app config link` | | 2 | "Cannot read properties of null (reading 'X')" on CLI start | Corrupted `.shopify` cache or stale config | Back up the caches with `node <plugin-root>/scripts/reset-shopify-cache.mjs`, then run `shopify app dev --reset` | | 3 | "Could not start Cloudflare tunnel: max retries reached" | Leftover `~/.cloudflared/config.yaml` from another project | `mv ~/.cloudflared/config.yaml ~/.cloudflared/config.yaml.bak`, or `shopify app dev --use-localhost` (CLI 3.80+) | | 4 | Tunnel URL doesn't update in Partner Dashboard | CLI 3.x bug | `shopify app dev --reset --tunnel-url <fresh>` or upgrade CLI to latest | | 5 | "Issues with valid certificates after the recent update" | Self-signed cert rot
Preview of the first 4,000 characters. Read full instructions →
--- name: hydrogen-storefront description: "Use this skill for Hydrogen 2026 Storefront Framework. Triggers include: 'hydrogen storefront', 'hydrogen 2026', 'hydrogen remix', 'shopify hydrogen framework', 'hydrogen setup scaffold', 'hydrogen useCart hook', 'hydrogen createCartHandler', 'hydrogen Customer Account API', 'hydrogen caching strategies', 'hydrogen oxygen deployment', 'hydrogen cli commands', 'hydrogen storefront client', 'hydrogen product page', 'hydrogen collection page', 'hydrogen checkout', 'hydrogen admin api', 'hydrogen queueApi', 'hydrogen analytics', 'hydrogen search implementation', 'hydrogen variants and options', 'hydrogen localization i18n', 'hydrogen performance optimization', 'hydrogen seo structured data', 'hydrogen third party scripts', 'hydrogen css styling tailwind', 'hydrogen testing'." --- # Hydrogen 2026 Storefront Framework Hydrogen is Shopify's Remix-based framework for building fast, custom storefronts. This skill covers Hydrogen 2026 project setup, the Storefront API client, cart management with hooks, Customer Account API, caching strategies, Oxygen deployment, CLI commands, and real-world PDP and collection page patterns. ## When Asked **When asked to scaffold a new Hydrogen storefront:** Provide the npm create @shopify/hydrogen command, explain project structure, and show how to configure .env with Storefront API credentials. **When asked to fetch and display products:** Use the Storefront API via the storefront client (GraphQL query), show how to load product details, variants, and media; explain caching strategies. **When asked to implement a shopping cart:** Use createCartHandler for backend cart mutations, useCart hook for frontend state, and explain line item management, discounts, and checkout flow. **When asked about Customer Account API:** Explain how to enable, authenticate with OAuth, and use for customer login, order history, account details, and profile updates. **When asked to optimize performance and caching:** Discuss Cache-Control headers, Oxygen runtime caching, request coalescing, and streaming SSR; provide cache strategy examples. **When asked to deploy to Oxygen:** Show CLI deployment steps (hydrogen deploy), environment variable setup, monitoring, and rollback procedures. **When asked to implement search or filtering:** Use Hydrogen Search API, faceting, filtering by attribute, and show autocomplete and collection filter patterns. --- ## Hydrogen 2026 Architecture Overview Hydrogen provides: - **Remix Framework**: Server-side rendering (SSR), file-based routing, loader/action functions, Remix utilities - **Storefront API Client**: GraphQL client for fetching product, collection, cart, order, and customer data - **useCart Hook**: Client-side cart state management with add-to-cart, update, remove operations - **createCartHandler**: Server-side cart mutations (create, update, discount, checkout) - **Customer Account API**: OAuth-based customer login, order history, account endpoints - **Caching**: Cache-Control headers, Oxygen response caching, request deduplication - **Oxygen Platform**: Serverless execution environment with global edge cache - **CLI**: `hydrogen dev`, `hydrogen preview`, `hydrogen deploy` commands - **Analytics & Reporting**: Built-in Oxygen analytics, custom event tracking ### Installation & Project Setup ```bash npm create @shopify/hydrogen@latest my-store -- --language TypeScript cd my-store npm install npm run dev ``` This generates: ``` my-store/ ├── app/ │ ├── components/ # Reusable React components │ ├── routes/ # File-based routing (Remix) │ ├── lib/ # Utility functions, API clients │ └── root.tsx # Root layout ├── public/ ├── .env # Storefront API token, store domain ├── hydrogen.config.ts # Hydrogen config ├── remix.config.js # Remix config (SSR, build) ├── package.json └── tsconfig.json ``` ### Environment Setup ```bash # .env PRIVATE_STOREFRONT_A
Preview of the first 4,000 characters. Read full instructions →
--- name: liquid-themes description: "Use this skill for Liquid Theme Development (Online Store 2.0). Triggers include: 'liquid theme development', 'shopify theme online store 2.0', 'liquid section schema', 'liquid blocks', 'liquid filters', 'liquid objects', 'json template shopify', 'theme preset', 'liquid include snippet', 'theme-check linting', 'liquid forloop iteration', 'liquid if conditions', 'liquid assign variable', 'shopify theme app extension', 'liquid capture variable', 'theme metafields', 'liquid date filter', 'liquid money filter', 'liquid array filters', 'liquid string manipulation', 'liquid product page', 'liquid collection page', 'liquid cart page', 'liquid header footer', 'liquid for loop break continue', 'liquid unless statement', 'liquid case when'." --- # Liquid Theme Development (Online Store 2.0) Liquid is Shopify's templating language for building themes and sections on Online Store 2.0. This skill covers Liquid syntax, section schema definition, JSON templates, blocks, filters (20+ common), objects, theme file structure, presets, and real-world section and template patterns. ## When Asked **When asked to build a Liquid section with settings:** Provide a complete section file with schema (settings array, presets, locales), CSS, and JavaScript; explain how settings map to template variables. **Before returning any section, app block, or theme schema:** Run the Shopify schema dedupe check mentally or with `scripts/validate-shopify-schema-ids.mjs <theme-or-file>`. Every `settings[].id` must be unique within its own schema scope, every block's `settings[].id` must be unique inside that block type, and every `blocks[].type` should be unique unless you are intentionally defining different block entries. Do not paste settings from multiple examples until you merge and dedupe IDs. **When asked to implement product filters or sorting:** Use the collection product pagination, filters by attribute, sorting with Liquid forloop and if/case statements; explain faceting. **When asked to add custom fields to products:** Use metafields in Liquid (product.metafields.namespace.key), explain metafield definitions, and show rendering in sections. **When asked to create reusable components:** Use include/render snippets with passed parameters; explain snippet vs. render differences and variable scope. **When asked about Liquid filters and string manipulation:** Provide examples of 20+ filters (split, join, size, capitalize, downcase, strip_html, truncate, money, date, etc.) with use cases. **When asked to optimize theme performance:** Discuss lazy loading, critical CSS, reducing render-blocking resources, and using theme-check for linting. --- ## Liquid & Online Store 2.0 Architecture Liquid provides: - **Section-Based Editing**: Drag-and-drop sections with live customization - **Schema System**: Settings (text, select, checkbox, range, color), preset configurations - **Blocks**: Repeatable content blocks within sections (e.g., carousel slides, testimonials) - **JSON Templates**: Structured page templates with sections array - **Filters**: 50+ filters for formatting (string, date, money, array, math) - **Objects**: Global objects (shop, page, product, collection, cart, customer) - **Include & Render**: Reusable snippets with parameter passing - **Forloop & Control**: for, if, unless, case/when, break, continue statements - **Metafields**: Custom product/collection/order data fields ### Schema Dedupe Guardrail Shopify section schemas use arrays, so JSON itself will not protect you from duplicated visible inputs. A duplicated setting object with the same `id` can make Theme Editor show repeated controls or make generated Liquid read the wrong setting. Hard rules before emitting schema: - Keep section-level `settings[].id` unique. - Keep `blocks[].type` unique within a section or app block. - Keep each block's `settings[].id` unique inside that block. - In `config/settings_schema.json`, keep setting IDs unique a
Preview of the first 4,000 characters. Read full instructions →
--- name: merchant-pain-prevention description: "Use when designing, building, reviewing, or shipping a Shopify app to avoid the patterns that get merchants angry (1-2 star reviews, uninstalls, churn). Covers theme injection / leftover code on uninstall, surprise billing, fake urgency, slow scripts, cancel friction, scope creep, bot-only support, broken on platform updates, locale/checkout breakage. Triggers: 'merchant complaint', 'avoid bad app review', 'shopify app uninstall hygiene', 'leftover code in theme', 'surprise charge', 'shopify app dark pattern', 'billing after uninstall', 'cancel friction', 'shopify app churn', '1 star review', 'billed after trial', 'shopify app cleanup'. MUST trigger on any pre-ship review or quality check." --- # Merchant Pain Prevention Every 1-star review on the Shopify App Store is a merchant who trusted you and felt betrayed. This skill is the inverse of that experience — a hard-coded inventory of the patterns that cause the betrayal, with the structural fixes. The merchant pain ecosystem is small and loud. Stores talk. Subreddits index. Community threads outrank the App Store on Google for the phrase "billed for uninstalled app" — there are at least eight active threads on that exact phrase. If you ship a billable app and get one of those patterns wrong, you will not just lose that merchant; you will repel the next 50 who Google your name. This is not a style guide. It is a survival document. Follow it. --- ## 1. When to use Invoke this skill whenever you are: - **Designing** a new Shopify app or extension — before architecture is locked, before scopes are declared, before billing is wired. - **Reviewing a PR** that touches: theme app extensions, ScriptTag, billing API, webhook handlers, scopes (`shopify.app.toml`), onboarding flow, cancellation flow, email triggers, popups, banners, countdown timers, "social proof" widgets. - **Pre-ship audit** — the 48 hours before you submit to the App Store or release a new version. - **Triaging a merchant complaint** — public 1-star, support ticket, refund request, chargeback, BBB complaint, Trustpilot drop, Reddit post that mentions your app by name. - **Annual reaudit** — quarterly is better. Scopes accrete. Pricing pages drift. Anti-patterns sneak back in when feature flags collide. - **Investigating churn** — a sudden uninstall spike usually maps to one of the cardinal pains. If anyone on your team says "merchants will figure it out" or "this is industry standard" or "everyone does it this way" — that is the trigger to run this skill in full. Industry standard on Shopify is what generates 12 BBB complaints a day. Do not aim for industry standard. --- ## 2. The 7 cardinal merchant pains (ranked by anger) Ranked by how fast they get you a public 1-star review, a chargeback, a Reddit post, and an unrecoverable partner-reputation hit. Each is documented with verbatim merchant quotes. ### Pain 1 — Charged after uninstall The single most-litigated complaint on the App Store. At least eight active Shopify Community threads use this exact phrase as the title. The complaint compounds because Shopify Support since May 3, 2023 no longer mediates refund requests on behalf of merchants — they tell the merchant to email the developer, who often ghosts. > "Why am I still billed for an uninstalled app on Shopify?" — verbatim title repeated across at least five threads. [community.shopify.com/t/why-am-i-still-billed-for-an-uninstalled-app-on-shopify/191216](https://community.shopify.com/t/why-am-i-still-billed-for-an-uninstalled-app-on-shopify/191216) > "Why am I still being charged for POS after uninstalling? I don't use it and uninstalled the app months ago." — the Shopify-owned POS app does it too. [community.shopify.com/t/why-am-i-still-being-charged-for-pos-after-uninstalling/286967](https://community.shopify.com/t/why-am-i-still-being-charged-for-pos-after-uninstalling/286967) > "Why is a merchant that uninstalled our app seeing charges two m
Preview of the first 4,000 characters. Read full instructions →
--- name: metafields-metaobjects description: "Custom data fields and objects specification, namespace/key management, definition creation, querying, and Liquid theme access. Triggers include: 'metafield', 'metaobject', 'custom field', 'custom data', 'namespace key', 'metafield definition', 'metaobject type', 'product metafield', 'variant metafield', 'customer custom field', 'order metafield'." --- # Shopify Metafields and Metaobjects Guide ## Metafields vs Metaobjects: When to Use Each ### Metafields **Purpose:** Store custom key-value data on existing resources (products, orders, customers, etc.) **Use Metafields When:** - Adding custom attributes to existing resources - Simple key-value relationships - Data is tightly coupled to the resource - Needed in themes (Liquid access) - Examples: size chart URL, custom color, warranty period, gift message **Characteristics:** - Attached to existing resource types - Simple string or typed values - Queryable via GraphQL - Accessible in Liquid templates - Max 2,500 metafields per resource - Namespace + key = unique identifier - Supports display in admin UI via definitions ### Metaobjects **Purpose:** Define custom data types/records independent of resources **Use Metaobjects When:** - Creating independent data structures - Multi-field records needed - Reusable data types across shop - Complex relationships - Data referenced by multiple resources - Examples: FAQs, reviews, testimonials, size guides, lookbooks, staff profiles **Characteristics:** - Independent data type (like custom table) - Multiple fields with defined types - Queryable via GraphQL - Can be referenced by products/collections via metafield - Organized in admin UI - Supports indexing and search - Better for data that stands alone **Comparison Table:** | Feature | Metafield | Metaobject | |---------|-----------|-----------| | Attached to resources | Yes | No (standalone) | | Multi-field support | No (single value) | Yes | | Admin UI form | Via definition | Native editor | | Liquid access | Direct | Via reference metafield | | Relationship support | One-way (to resource) | One-way (reference metafield) | | Reusability | Per resource type | Across shop | | Use case | Quick attributes | Structured data | ## Metafield Resource Types The following resources support metafields: 1. **Product** - 2,500 max metafields per product 2. **Product Variant** - 2,500 max metafields 3. **Order** - Custom order data 4. **Customer** - Customer profiles 5. **Collection** - Collection attributes 6. **Draft Order** - Pre-order metadata 7. **Shop** - Store-wide settings 8. **Location** - Warehouse/store details 9. **Company** - B2B company info 10. **Company Location** - B2B location data 11. **Market** - Market-specific metadata 12. **File** - Asset metadata ## Metafield Type System ### Supported Types **Text Types:** - `single_line_text_field` - Max 255 chars (search enabled, sortable) - `multi_line_text_field` - Max 5,000 chars (search enabled) - `rich_text_field` - HTML + Markdown (max 100,000 chars) **Numeric Types:** - `number_integer` - 64-bit signed integer - `number_decimal` - Decimal number (up to 8 decimal places) **Date/Time Types:** - `date_field` - ISO 8601 date (YYYY-MM-DD) - `date_time_field` - ISO 8601 datetime (2026-05-04T14:30:00Z) **Boolean:** - `boolean` - true/false **Reference Types:** - `product_reference` - Reference to Shopify product - `collection_reference` - Reference to collection - `file_reference` - Reference to file in Files API - `metaobject_reference` - Reference to metaobject **Display Types:** - `color` - Color value (hex #RRGGBB) - `weight` - Weight with unit (grams, kilograms, pounds, ounces) - `volume` - Volume with unit - `dimension` - Dimension with unit - `url` - Full URL (max 2,048 chars) **JSON Type:** - `json` - Valid JSON object/array (max 100,000 chars, searchable) **List Type:** - `list.*` - Array of type (e.g., `list.metaobject_reference`) ### Type Examples **Single Lin
Preview of the first 4,000 characters. Read full instructions →
---
name: polaris-ui
description: "Use this skill for Polaris 12.x UI Components. Triggers include: 'polaris components', 'react ui shopify', 'approvider initialization', 'polaris form', 'polaris button', 'polaris card', 'polaris table indexTable', 'polaris modal dialog', 'polaris select dropdown', 'polaris textfield input', 'polaris checkbox radio', 'polaris navigation', 'polaris layout blocklist inlinestack', 'polaris design tokens', 'polaris icons', 'polaris stack grid', 'polaris page frame resource list', 'polaris loading spinner', 'polaris toast notification', 'polaris banner alert', 'shopify ui component library', 'polaris 12', 'polaris css import', 'polaris styled components', 'polaris form validation', 'polaris accessibility a11y', 'polaris icon reference', 'polaris theme provider', 'polaris page actions buttons'."
---
# Polaris 12.x UI Components
Polaris 12.x is Shopify's official React component library for building consistent, accessible admin and embedded app UIs. This skill covers Polaris component patterns, AppProvider initialization, 25+ commonly-used components, design tokens, form validation, and real-world layout patterns for Shopify apps.
## When Asked
**When asked to build a Shopify app UI with forms and inputs:**
Provide a complete React component example using AppProvider, TextField, Select, Checkbox, and Button components with proper state management and form submission handlers.
**When asked about Polaris layout and spacing:**
Explain BlockStack, InlineStack, and InlineGrid with code examples showing proper spacing, padding, and responsive behavior using gap and padding props.
**When asked to create data tables or resource lists:**
Use IndexTable for tabular data with sorting, selection, and bulk actions; ResourceList for browseable item collections with filters and search.
**When asked about Polaris design tokens or theming:**
Provide color, typography, and spacing token values; explain how to access tokens via CSS variables and customize with custom properties.
**When asked to implement forms with validation:**
Build controlled forms with TextField, Select, Checkbox components; add error states, help text, and form submission with validation logic.
**When asked about Polaris icons and iconography:**
Reference available icons (Icon component, 150+ icons from @shopify/polaris-icons), show Icon usage with color and size props.
**When asked to create modals, dialogs, or overlays:**
Use Modal component for full-screen overlays, Popover for inline popups, and ContextualSaveBar for unsaved changes UI patterns.
---
## Polaris 12.x Architecture Overview
Polaris provides:
- **AppProvider**: Required root component that initializes Polaris context (i18n, theme, CSRF token)
- **25+ UI Components**: Button, Card, Layout (BlockStack, InlineStack, InlineGrid), TextField, Select, Modal, IndexTable, ResourceList, etc.
- **Design Tokens**: Color (primary, success, warning, critical), typography (display, heading, body), spacing (0.5rem, 1rem, 1.5rem, 2rem), shadow, border-radius
- **Polaris Icons**: 150+ SVG icons via @shopify/polaris-icons; Icon component wrapper
- **Accessibility**: WCAG 2.1 AA compliant, semantic HTML, ARIA labels, keyboard navigation
- **CSS Imports**: Import from @shopify/polaris (includes Tailwind-like utility classes; use CSS modules or styled-components for scoping)
### Installation & Setup
```bash
npm install @shopify/polaris @shopify/polaris-icons
# or yarn / pnpm
```
### AppProvider Initialization (Required)
```tsx
import React from 'react';
import { AppProvider } from '@shopify/polaris';
import '@shopify/polaris/build/esm/styles.css';
function App() {
return (
<AppProvider i18n={{}}>
<YourComponent />
</AppProvider>
);
}
export default App;
```
**Props:**
- `i18n`: Object with translation strings (optional; defaults to English)
- `features`: Object to enable experimental features
- `colorScheme`: Light (default) or dark mode
- `link`: Function for custoPreview of the first 4,000 characters. Read full instructions →
--- name: shopify-app-store-ads description: "Research, plan, launch, and optimize Shopify App Store ads for a Shopify app. Use when asked to advertise an app in the Shopify App Store, create an App Store Ads campaign, choose keywords or bids, estimate paid acquisition economics, diagnose ad performance, or turn Reddit/community research into a testable campaign. Require explicit approval of the daily and total spend before creating or enabling any paid campaign." --- # Shopify App Store Ads Use App Store ads to test qualified merchant acquisition, not to buy superficial installs. Treat the Shopify Partner Dashboard and current Shopify documentation as the authority for eligibility, available placements, bid behavior, billing, and reporting. ## Ground Rules 1. Verify that the app is publicly published and eligible before proposing launch. An active development version is not evidence of a public App Store listing or advertising eligibility. 2. Research live platform rules before acting. Start with Shopify's [App Store ads documentation](https://help.shopify.com/en/partners/marketing-and-promotions/app-store-ads), then verify the visible Partner Dashboard controls for the specific app. 3. Use community sources (Reddit, reviews, founder posts) to form keyword, pain-point, and creative hypotheses. Label them as anecdotal; do not present them as Shopify policy or benchmark data. 4. Never create, enable, or materially raise a paid campaign without the user's explicit confirmation of the currency, daily cap, total test cap, and stop date. Do not infer approval from a request to "run ads." 5. Never call a campaign live from an API response, draft state, or local configuration alone. Confirm its visible dashboard status, targeting, budget, billing readiness, and landing/listing preview. 6. Do not promise customers or return on ad spend before enough cohort time has passed. Distinguish clicks, installs, trials, activated merchants, and paid customers. ## Readiness Gate Collect these facts before recommending spend: - Public App Store listing URL, app status, category, supported geographies, and current price/trial terms. - Listing conversion evidence: title, tagline, screenshots, review count/rating, pricing clarity, and a merchant-facing promise that matches the target query. - A working install-to-value path: first-run activation event, billing/trial event, and paid-conversion event. Name the exact analytics source and event names; do not invent them. - Unit economics: monthly plan(s), gross margin, expected paid retention, acceptable payback window, and the maximum customer-acquisition cost (CAC). - Partner account access, ad billing readiness, and the person authorized to approve spend. If a required item is unknown, make it a launch blocker or use the smallest reasonable research-only next step. Do not compensate for weak listing conversion or broken onboarding with a larger bid. ## Research and Campaign Brief Build a brief that separates evidence from hypotheses. | Field | Record | | --- | --- | | Merchant segment | Store size, vertical, market, current workflow, and urgent job-to-be-done | | Search intent | The problem phrase merchants use, expected outcome, and disqualifying intent | | Evidence | Shopify listing/report data, review themes, and dated community observations with links | | Offer match | Listing headline, screenshots, trial/pricing, and activation path that answer that intent | | Economics | Target CAC, payback assumption, daily cap, total cap, and stop rule | | Measurement | Shopify report fields plus product events for install, activation, trial, and paid conversion | ### Keyword Research Start from the merchant's problem and workflow, not the app's internal feature names. Group terms into: - **High-intent problem terms:** merchants actively seeking a solution, for example `bundle app` or `back in stock alerts`. - **Workflow and integration terms:** `preorder manager`, `subscription migration`, or `
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
--- name: shopify-cli description: "Use when scaffolding a new Shopify app, running Shopify CLI commands (shopify app dev/deploy/generate), configuring shopify.app.toml, generating app extensions (admin/checkout/theme/function), debugging tunnels or auth issues, or working with the official Remix/Node/PHP/Ruby app templates. Trigger on 'shopify app', 'shopify cli', 'shopify init', 'shopify dev', 'shopify deploy', 'generate extension', 'shopify.app.toml', 'remix template', 'tunnel', 'ngrok', 'cloudflare tunnel', 'ME APP_URL', 'SHOPIFY_API_KEY', or anything involving the Shopify CLI workflow." --- # Shopify CLI Skill Reference ## When to Use This Skill Use this skill for any task involving: - Creating a new Shopify app with `shopify app init` - Running development server with `shopify app dev` - Deploying apps with `shopify app deploy` or `shopify app release` - Generating extensions (admin actions, checkout UI, theme extensions, functions) - Configuring `shopify.app.toml` and understanding all available settings - Working with Remix + React Router v7 app template - Setting up local tunnels (Cloudflare Tunnel or ngrok) - Debugging authentication, webhooks, or environment issues - Managing theme development with `shopify theme` commands - Generating GraphQL types with `@shopify/api-codegen-preset` - Understanding app structure, directory layout, and lifecycle - Error troubleshooting and common failure patterns ## Installation and Setup ### Install Shopify CLI ```bash npm install -g @shopify/cli@latest ``` **Node.js Requirements:** - `>=20.19 <22` OR `>=22.12` - Check version: `node --version` ### Verify Installation ```bash shopify version shopify app --help ``` ## Command Reference | Command | Flags | Purpose | |---------|-------|---------| | `shopify app init` | `--template remix` | Initialize new Shopify app with Remix template | | `shopify app dev` | `--reset`, `--build`, `--no-update` | Start local dev server with hot reload | | `shopify app deploy` | `--force`, `--no-release` | Deploy app to Shopify Partner dashboard | | `shopify app release` | `--version X.Y.Z`, `--force` | Release deployed version to live | | `shopify app generate` | `extension`, `webhook` | Generate boilerplate for extensions/webhooks | | `shopify generate extension` | `--type admin_action`, `--api-version 2026-07` | Create app extension with a currently supported API version | | `shopify app push` | `--force`, `--no-release` | Push config updates without full deploy | | `shopify config show` | | Display loaded config from shopify.app.toml | | `shopify env pull` | | Fetch environment variables from Partner dashboard | | `shopify app open` | | Open app dashboard in browser | | `shopify theme dev` | `--store example.myshopify.com` | Start theme development server | | `shopify theme pull` | `--theme-id 123456789` | Download theme files from store | | `shopify theme push` | `--force`, `--no-delete` | Upload theme files to store | | `shopify auth logout` | | Clear stored authentication | | `shopify auth login` | `--shop example.myshopify.com` | Authenticate with specific store | ## shopify app init Workflow (6-Step Process) ### Step 1: Launch Init Command ```bash shopify app init --template remix ``` ### Step 2: Provide Org and App Name ``` ? App name > my-shopify-app ? Org > Select from: [list of partner orgs] ``` ### Step 3: Select Package Manager ``` ? Package manager > npm / yarn / pnpm ``` ### Step 4: Create Local Tunnel ``` ? Local tunnel authentication > Cloudflare / ngrok / skip ``` ### Step 5: Install Dependencies ```bash cd my-shopify-app npm install ``` ### Step 6: Start Dev Server ```bash npm run dev ``` Output: ``` ✓ Tunnel started at https://RANDOMHASH.lhr.life ✓ App URL: https://RANDOMHASH.lhr.life/api/auth ✓ Admin API access scopes configured ✓ Listening on port 3000 ``` ## Remix Template Deep Dive ### Directory Structure ``` my-shopify-app/ ├── shopify.app.toml # App configuration (CRITICAL) ├── remix.confi
Preview of the first 4,000 characters. Read full instructions →
--- name: shopify-functions description: "Build WebAssembly functions for the Shopify checkout and order pipeline. Rust or JavaScript, 5ms execution window, 256KB binary limit. Targets cart transform, discount, validation, payment customization, delivery customization, order routing, fulfillment constraints, and localization. Triggers include: 'Shopify Function', 'WASM', 'Rust function', 'JavaScript function', 'function-runner', 'cart.transform.run', 'discount.run', 'cart.checkout-validation.run', 'cart.delivery-customization.run', 'cart.payment-customization.run', 'cart.lines.discounts.generate.run', 'order.routing.location.rank.run', 'fulfillment-constraints.run', 'localization.generate.run', 'metafield function', 'shopify function'." --- # Shopify Functions Shopify Functions are WebAssembly (WASM) units of business logic that extend the Shopify checkout, order, and fulfillment pipelines. They execute in a sandboxed runtime on Shopify's servers and have strict constraints: 5ms execution window, 256KB binary limit, no async I/O, no outbound HTTP to unknown hosts, and 30-point GraphQL query complexity ceiling. ## Architecture & Execution Model **Function Lifecycle:** 1. Merchant installs your app; metafield definitions are registered 2. App reads merchant configuration from metafields (Shop, Product, Collection scopes) 3. On checkout/order event, Shopify invokes your function with Input JSON payload 4. Function executes WASM bytecode, applies business logic, returns JSON output 5. Output mutations are applied atomically to the checkout/order state **Execution Constraints (Hard Limits):** - Max execution time: 5ms (timeout failure = no operation) - Max binary size: 256KB gzipped - Max instructions: 11 million - Max memory: 256KB heap - Max output JSON: 256KB - Max GraphQL query complexity: 30 points (estimate 1pt per simple field) - No async I/O, no event loops, no multi-threading - No network access except allowed_hosts (NEW 2025-01) - Deterministic execution only **Why WASM?** Shopify Functions run in Wasmtime, a fast WebAssembly runtime. This provides: - Language flexibility: Compile Rust, JavaScript (via AssemblyScript), or Go to WASM - Isolation: No access to host filesystem, process, or network (except whitelisted hosts) - Performance: Near-native execution speed; optimized just-in-time compilation - Security: Sandboxed; input/output validation by Shopify platform ## Function Targets & Checkout Pipeline The Shopify checkout and order pipeline has **8 invocation points** (targets). Each target receives a specific input schema and must return a specific output schema: | Target | Phase | Purpose | Input | Output | Latency Budget | |--------|-------|---------|-------|--------|-----------------| | `cart.transform.run` | 1. Cart | Transform line items (bundle, rename, change quantity) | Cart items, metafields | Modified items | 5ms | | `cart.checkout-validation.run` | 2. Validation | Validate cart before payment (inventory, rules) | Cart state, attributes | Errors/blocks (optional) | 5ms | | `cart.delivery-customization.run` | 3. Delivery | Customize rates, hide options, rank (shipping, pickup) | Delivery options, cart | Customized rates/ranking | 5ms | | `cart.payment-customization.run` | 4. Payment | Hide payment methods, customize amounts | Payment methods, total | Customized methods/amounts | 5ms | | `discount.run` | 5. Discount | Apply discounts (% off, $ off, free shipping, gift) | Cart items, rules | Discount targets + value | 5ms | | `fulfillment-constraints.run` | 6. Fulfillment | Constrain what locations can fulfill each line | Cart items, locations | Location fulfillment rules | 5ms | | `order.routing.location.rank.run` | 7. Order Routing | Rank locations for fulfillment (priority, cost) | Locations, order lines | Ranked location order | 5ms | | `localization.generate.run` | 8. Localization | Generate translated/localized checkout labels | Buyer locale, shop context | Localized strings | 5ms | | `cart.lines.
Preview of the first 4,000 characters. Read full instructions →
---
name: shopify-mcp
description: "Use this skill for shopify mcp. Triggers include: 'shopify mcp', 'shopify dev mcp', 'storefront mcp', 'merchant-facing mcp', 'well-known mcp', 'shopify mcp configuration', 'custom mcp shopify', 'agentic commerce', 'shopify agent', 'claude code shopify integration', 'mcp.json', 'shopify mcp setup'."
---
# Shopify MCP Integration Guide
Model Context Protocol (MCP) servers connect Claude to Shopify data and operations. There are three deployment patterns: Shopify Dev MCP (developer-centric), Storefront MCP (merchant-centric), and custom MCPs (specialized workflows). This guide covers setup, configuration, implementation patterns, and agentic commerce use cases.
## Shopify Dev MCP: Developer Tools for Claude Code
Shopify Dev MCP is a read-only developer toolkit integrated into Claude Code. It provides access to admin APIs, schema introspection, development store management, and app testing utilities without building a custom MCP.
### Installation and Setup
The Shopify Dev MCP is installed via command-line setup:
```bash
npx -y @shopify/dev-mcp setup
```
This command:
1. Prompts for Shopify organization/store selection
2. Creates a development app or reuses existing one
3. Stores authentication tokens securely in system keychain
4. Registers the MCP server in `~/.claude.json/mcpServers`
5. Restarts Claude Code to load the new MCP
No additional configuration is required post-setup. The MCP automatically handles token refresh and scope validation.
### Claude Code Configuration
After setup, `~/.claude.json/mcpServers` contains:
```json
{
"mcpServers": {
"shopify": {
"command": "npx",
"args": ["-y", "@shopify/dev-mcp", "run"],
"env": {
"SHOPIFY_AUTH_TOKEN": "shpat_...",
"SHOPIFY_STORE": "dev-store-name.myshopify.com",
"SHOPIFY_ORG_ID": "gid://shopify/Organization/12345"
}
}
}
}
```
Manual configuration is unnecessary unless you need environment-specific tokens or custom server paths. For advanced setups (air-gapped networks, custom HTTP proxies), edit the env dict directly.
### Dev MCP Capabilities
The Shopify Dev MCP provides these read-only tools:
**Admin API Query Tool**
- Execute GraphQL queries against the API version configured for the connected development store
- Full schema support (Products, Orders, Customers, Fulfillments, Inventory, etc.)
- Automatic scope validation (app must have required scopes)
- Response size limit: 5MB per query
- Query complexity limit: 100 points (Admin API default)
```graphql
query GetProductMetafields($id: ID!) {
product(id: $id) {
id
title
metafields(first: 10) {
edges {
node {
namespace
key
value
}
}
}
}
}
```
**REST API Endpoint Tool**
- Use legacy Admin REST endpoints only when the connected tool and existing app explicitly support them
- Bearer token authentication handled automatically
- Useful for bulk operations, webhooks, flow triggers
- Rate limit: standard REST bucket holds 40 requests and restores 2 requests/second; read response headers and retry safely
**Store Introspection Tool**
- List installed apps, extensions, functions, webhooks
- Retrieve store metadata (plan, currency, timezone, brand settings)
- Useful for understanding store configuration before building
- No rate limiting
**App Testing Tool**
- Trigger test webhooks (app/installed, app/uninstalled, orders/create)
- List development app credentials
- Rotate API credentials securely
- Simulate store events without live transactions
**Schema Browser Tool**
- Explore GraphQL schema interactively
- Get field descriptions, arguments, return types
- Filter by type (Query, Mutation, Subscription, Object, Enum)
- Search for fields by name or description
### When to Recommend Dev MCP Installation
Recommend Dev MCP when:
- User is building a Shopify app in Claude Code
- User needs to test queries against their dev store without leaving ClauPreview of the first 4,000 characters. Read full instructions →
---
name: storefront-api
description: "Build customer-facing storefront applications with Shopify Storefront API. Access product catalogs, collections, checkout flows, cart management, and customer accounts using public/private tokens. Includes GraphQL queries, Market directives, Customer Account API, and TypeScript examples. Triggers include: 'storefront api', 'customer-facing shopify', 'shopping cart api', 'product catalog query', 'checkout flow', 'customer account api', 'market directive', 'storefront token'."
---
## When to Use Storefront API
Use **Storefront API** for customer-facing applications:
- Building custom storefronts (headless commerce)
- Shopping cart and checkout flows
- Product browsing and search
- Customer account management (orders, addresses)
- Subscription management
- Market-specific pricing and inventory (with Market directives)
- Cart line operations (add, remove, update)
- Customer authentication and profiles
**DO NOT use for:** store management, admin operations, or internal tools (use Admin API instead).
---
## Token Types & Scopes
### Public Access Tokens
**Use for:** Frontend applications, public data access
```javascript
const publicToken = 'Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; // Public token
const shopDomain = 'mystore.myshopify.com';
const endpoint = `https://${shopDomain}/api/2026-01/graphql.json`;
const headers = {
'Content-Type': 'application/json',
'X-Shopify-Storefront-Access-Token': publicToken,
};
```
**Scopes enabled with public token:**
- Read products
- Read product collections
- Read shop information
- Read customer information (requires customer login)
- Create shopping carts
- Manage shopping carts
- Access checkout URLs
### Private Access Tokens (Storefront)
**Use for:** Backend/server-side access with elevated permissions
```javascript
const privateToken = process.env.SHOPIFY_STOREFRONT_PRIVATE_TOKEN;
const headers = {
'Content-Type': 'application/json',
'X-Shopify-Storefront-Access-Token': privateToken,
};
```
**Additional scopes with private token:**
- Full customer account access
- All storefront operations
- No rate limiting (unlike public token: 2 requests/second per IP)
---
## Headers & Configuration
**Standard Storefront Headers:**
```javascript
const headers = {
'Content-Type': 'application/json',
'X-Shopify-Storefront-Access-Token': accessToken,
};
```
**TypeScript Headers Interface:**
```typescript
interface StorefrontHeaders {
'Content-Type': 'application/json';
'X-Shopify-Storefront-Access-Token': string;
'Accept-Language'?: string; // For locale-specific data
}
```
**Add Market/Localization (Market Directive):**
```javascript
const headers = {
'Content-Type': 'application/json',
'X-Shopify-Storefront-Access-Token': accessToken,
'Accept-Language': 'en-US', // for Market resolution
};
```
---
## Product Queries
### Get Product by Handle
```graphql
query GetProduct($handle: String!) {
product(handle: $handle) {
id
title
description
handle
vendor
productType
images(first: 10) {
edges {
node {
url
altText
}
}
}
priceRange {
minVariantPrice {
amount
currencyCode
}
maxVariantPrice {
amount
currencyCode
}
}
variants(first: 100) {
edges {
node {
id
title
sku
price {
amount
currencyCode
}
availableForSale
quantityAvailable
compareAtPrice {
amount
currencyCode
}
selectedOptions {
name
value
}
}
}
}
collections(first: 5) {
edges {
node {
title
handle
}
}
}
}
}
```
**Variables:**
```json
{
"handle": "wireless-headphones"
}
```
### List Products (Paginated)
```graphql
query ListProducts($first: Int!, $after: String, Preview of the first 4,000 characters. Read full instructions →
--- name: top-app-ux-patterns description: "Use when designing or reviewing the UX of a Shopify app and you want to mirror what the top-grossing apps do (Klaviyo, Gorgias, Judge.me, Loox, Vitals, PageFly). Covers IA, first-30s flow, empty states, setup data collection, the aha moment, pricing presentation, listing page conventions, and the 20 reusable UX patterns common across top apps. Triggers: 'what do top shopify apps do', 'best in class shopify ui', 'klaviyo ux', 'gorgias ux', 'modern shopify app pattern', 'shopify app ia', 'app store screenshot pattern', 'polaris convention'. MUST trigger when designing first-run, dashboard, settings, or pricing screens." --- # Top App UX Patterns — What the Best-in-Class Shopify Apps Actually Do A teardown-driven playbook for designing or reviewing Shopify app UX. Built from a live analysis of six top-grossing apps (Klaviyo, Gorgias, Judge.me, Loox, Vitals, PageFly) representing an estimated $70M–$110M of combined Shopify-channel MRR. Use this skill to lift the converged patterns instead of inventing UX from scratch. --- ## 1. When to use Trigger this skill whenever you are: - Designing or reviewing a Shopify App Store **listing page** (hero, gallery, description, pricing cards, "Works with") - Designing the **first-run / install / OAuth → first value** flow - Designing **empty states** for any in-app screen (dashboard, settings, builder, etc.) - Designing the **pricing page** or choosing a pricing structure (flat / tiered / slot-based / usage-based) - Picking the **single addictive metric** for the merchant's dashboard - Reviewing UX for **install→activate→pay** conversion leaks - Comparing a competitor's UX against the converged best-practice set - Auditing copy on the listing or in-app for "outcome vs feature" framing - Choosing how to handle theme integration (theme code edits vs App Blocks / OS 2.0) - Deciding what onboarding data to collect at install vs. defer Do not use this skill for: backend architecture, billing implementation details (use `shopify-app-builder:app-billing`), or scope minimization (use `shopify-app-builder:audit-scopes`). This skill is purely about **what merchants see and feel.** --- ## 2. The six case studies Each case study compresses the teardown into the patterns worth stealing. Numbers are estimates from the source teardown dated 2026-05-15. ### 2.1 Klaviyo — Email Marketing & SMS - **Rating / scale:** 4.6 (2,731 reviews). Est. $35M–$50M MRR from Shopify channel. - **BFS badge:** No (legacy). - **Pricing entry:** Free to install. Email from $20/mo (251–500 contacts). SMS from $15/mo. - **Primary job:** Turn anonymous traffic + one-time buyers into a list to re-monetize across email + SMS + WhatsApp. **Key takeaways:** 1. Lead the tagline with **outcome + AI**, not feature — "AI marketing… to grow faster" beats "Send emails." 2. **Permanent free tier** (250 contacts forever) is the install hook. Reduces friction to near-zero. 3. **Defer credential friction** — DNS records / sender domain asked only at first send, not install. 4. **Bury complexity behind "See all pricing options"** — three clean cards on the listing, full matrix one click away. 5. The aha moment is the **Abandoned Cart attributed revenue** widget within 72 hours of install. ### 2.2 Gorgias — AI Helpdesk & Chat - **Rating / scale:** 4.3 (635 reviews — lowest 5-star share in this set). Est. $14M–$20M MRR. - **BFS badge:** No. - **Pricing entry:** $10/mo Starter (3 agents, 50 tickets) → $900/mo Advanced. Per-ticket overage. - **Primary job:** Replace a tangle of inboxes (email + chat + social + voice + SMS) and auto-resolve the repetitive 60% with AI. **Key takeaways:** 1. **"View demo store"** secondary CTA — uniquely powerful for complex / abstract apps. Lets prospects feel it before installing. 2. **Minimal gallery (2 images)** + bet on the demo + description. 3. **Tiered overage that gets cheaper per unit at higher tiers** is a clean upgrade-pressure mechanic. 4. The aha
Preview of the first 4,000 characters. Read full instructions →
--- name: using-shopify-app-builder description: "Use at the start of any Shopify app engineering, debugging, review, launch, listing, or growth task. Routes the request to the smallest relevant Shopify App Builder skills and enforces credential, verification, deployment, publication, and paid-spend boundaries. Triggers include: 'Shopify app', 'Shopify extension', 'Shopify API', 'App Bridge', 'Polaris', 'Built for Shopify', 'App Store listing', and 'Shopify app ads'." --- # Using Shopify App Builder Treat this skill as the router for the toolkit. Select focused skills before proposing code or operational changes. ## Routing workflow 1. Inspect the repository, framework, Shopify configuration, and the user's stated outcome. 2. Classify the request with the routing table below. 3. Read the selected skill files completely. Use the smallest set that covers the request. 4. Verify time-sensitive platform behavior against current official Shopify documentation. 5. Implement only what the user authorized, then run proportionate checks on the real affected surface. ## Skill routing table | Request | Start with | Add when needed | | --- | --- | --- | | New app, scaffold, extension, or deployment plan | `shopify-cli` | `app-validation`, `app-niche-finder`, `app-auth`, `app-billing` | | Admin data or GraphQL error | `admin-graphql` | `metafields-metaobjects`, `webhooks`, `dev-troubleshooting` | | Legacy REST migration | `admin-rest` | `admin-graphql`, `migrate-rest-to-graphql` command in Claude/Cursor | | OAuth, token exchange, HMAC, or session issue | `app-auth` | `dev-troubleshooting`, `webhooks` | | Billing, plans, trials, or usage charges | `app-billing` | `app-pricing-strategy`, `merchant-pain-prevention` | | Embedded admin UI | `app-bridge` and `polaris-ui` | `ux-polaris-antipatterns`, `app-accessibility`, `app-performance` | | Storefront or theme work | `storefront-api`, `hydrogen-storefront`, or `liquid-themes` | `metafields-metaobjects` | | Checkout or backend customization | `shopify-functions` | `admin-graphql`, `dev-troubleshooting` | | Webhook delivery or signature verification | `webhooks` | `app-auth`, `dev-troubleshooting` | | Pre-ship or App Store review | `built-for-shopify-standards` | `merchant-pain-prevention`, `app-accessibility`, `app-performance`, UX skills | | Listing, name, price, or market validation | `app-listing-optimization`, `app-naming`, `app-pricing-strategy`, or `app-validation` | `app-niche-finder` | | App Store advertising | `shopify-app-store-ads` | `app-listing-optimization`, `app-pricing-strategy` | | Shopify MCP or agentic commerce | `shopify-mcp` | Relevant API and authentication skills | ## Operating guidelines - Inspect first. Do not assume the app template, API version, package version, scopes, or deployment provider. - Use official Shopify documentation as the authority for unstable platform facts. - Keep OAuth scopes minimal and explain every requested write scope. - Treat GraphQL HTTP success separately from GraphQL `errors`, mutation `userErrors`, and throttle metadata. - Verify webhooks with the raw request body and constant-time HMAC comparison. - Never expose, echo, commit, or publish tokens, app secrets, session data, `.env` contents, or personal filesystem paths. - Do not deploy, publish, submit, alter billing, or enable paid advertising unless the user explicitly authorizes that action. - Preserve unrelated work in dirty repositories and avoid destructive cleanup. - Report live evidence for deployments and dashboard changes; source edits or a passing build alone are not proof of live success. ## Harness behavior - Claude Code can use the bundled slash commands and specialist agents in addition to skills. - Codex and OpenCode should invoke focused skills by name or natural-language intent; Claude-specific agents are optional reference material, not native subagents. - Cursor can load the native plugin surfaces or the portable skills collection. - Gemini CLI receives this rout
Preview of the first 4,000 characters. Read full instructions →
---
name: ux-empty-error-states
description: "Use when designing empty states, loading states, error states, and partial-failure states in a Shopify embedded app. Covers Polaris EmptyState, SkeletonPage/SkeletonBodyText, Banner tones (critical/warning/info/success), Toast vs Banner vs Modal decision, optimistic UI in Remix, network-down handling, partial bulk-failure recipes, GraphQL '200 OK with errors' gotcha. Triggers: 'empty state', 'loading state', 'error state', 'polaris banner', 'skeleton', 'toast', 'optimistic ui', 'partial failure', 'network down', 'remix loading ux', 'graphql error handling'."
---
# Empty, Loading & Error State UX for Shopify Polaris Apps
A practical, opinionated reference for the three states that make or break a Shopify embedded app: when there's nothing yet, when something is on its way, and when something went sideways. Pulled from Polaris docs, Remix pending UI docs, and real-world patterns.
---
## 1. EmptyState — when, how, and what to put inside
### What it is
`EmptyState` is Polaris' purpose-built component for "this page/section is empty." It composes a centered illustration, a heading, optional body text, and a primary action (and optional secondary action). It is intended for whole-page-empty experiences, not tiny empty slots inside a card sidebar.
### When to use it
Use `EmptyState` when:
- A list/table/chart has zero rows for first-time merchants (no products, no orders, no campaigns).
- A filtered/searched view returns zero matches (different copy, same component).
- A feature requires setup before it can be used (no connected account, no plan selected).
- A merchant landed on a page that needs onboarding context before they can act.
Do **not** use `EmptyState` for:
- Small empty slots inside a `Card` where a simple "No notes yet" sentence is enough.
- Form fields that aren't filled in — that's just normal state.
- Loading. Use `SkeletonPage` instead.
- Errors. Use a `Banner` (or a full-page error view) instead.
### Anatomy
```tsx
import { EmptyState, Page } from "@shopify/polaris";
<Page>
<EmptyState
heading="Manage your inventory transfers"
action={{ content: "Add transfer", onAction: () => navigate("/transfers/new") }}
secondaryAction={{
content: "Learn more",
url: "https://help.shopify.com/manual/inventory/transfers",
external: true,
}}
image="https://cdn.shopify.com/s/files/.../empty-state.svg"
>
<p>Track and receive your incoming inventory from suppliers.</p>
</EmptyState>
</Page>
```
### Content rules
- **Heading** — a friendly sentence fragment, not a label. "Manage your inventory transfers," not "Transfers."
- **Body** — one or two sentences. Explain the value, not the mechanism.
- **Primary action** — verb-first, the single most important thing they can do. "Add transfer," "Import products," "Connect Stripe."
- **Secondary action** — almost always a "Learn more" link to Shopify docs or your own help article. Use `external: true` and the new-window icon will render.
- **Image** — a Polaris illustration or your own brand-consistent SVG. ~400×250px works well. Polaris recommends ~40px of white space above when nested inside a `Card` or `Modal`.
### Two flavors you must handle
1. **First-run empty** (no data has ever existed). Copy is teaching-oriented. CTA is "Create your first X."
2. **Filtered empty** (data exists, the filter killed it). Copy is "No results match your filters." CTA is "Clear filters" or "Reset search." Do NOT show the onboarding CTA here — it confuses returning users.
Distinguish them in code:
```tsx
const showFilteredEmpty = products.length === 0 && hasActiveFilters;
const showFirstRunEmpty = products.length === 0 && !hasActiveFilters;
```
---
## 2. SkeletonPage / SkeletonBodyText — loading patterns
Polaris ships four skeleton components: `SkeletonPage`, `SkeletonBodyText`, `SkeletonDisplayText`, `SkeletonTabs`, and `SkeletonThumbnail`. The point is **perceived performance**: merchants tolePreview of the first 4,000 characters. Read full instructions →
--- name: ux-modern-app-feel description: "Use when you want a Shopify embedded app to feel modern, fast, and opinionated like Linear, Notion, Vercel, or Cron — speed-first, keyboard-first, calm UI, opinionated defaults, no-config success path. Covers keyboard shortcuts inside App Bridge, command palette patterns, micro-interactions Polaris allows, density vs spacious tradeoffs, brand expression within Polaris tokens, and 15 concrete patterns to copy from modern SaaS into Polaris-compliant Shopify apps. Triggers: 'modern shopify app', 'fast app', 'linear-style ux', 'notion-style ux', 'keyboard shortcuts shopify app', 'command palette', 'calm ui', 'minimalist polaris', 'opinionated defaults', 'fewer settings', 'speed first'." --- # Modern App Feel for Shopify Embedded Apps Most Shopify apps feel like 2015 — wall-of-settings, slow page loads, mouse-only, no keyboard, no taste. The modern reference is Linear, Notion, Vercel, Cron, Raycast, Superhuman, Arc — apps that feel calm, instant, opinionated, and keyboard-first. This skill is how to bring that feel inside Polaris and App Bridge 4.x without breaking the Built for Shopify (BFS) badge or merchant expectations. The premise: Polaris is the floor, not the ceiling. You can absolutely build a Linear-tier embedded app within Polaris — you just have to be deliberate about the seven things that actually make an app feel modern, and ruthless about everything else. --- ## When to Use This Skill Use when: - Building a new Shopify embedded app and you want it to feel categorically better than the competitor apps in the same category - Refactoring an existing app that feels slow, cluttered, or "Shopify-default" with no taste - Asked "how do I make this feel more like Linear / Notion / Vercel inside a Shopify app" - Adding keyboard shortcuts, a command palette, optimistic UI, or other speed-feel patterns to an embedded app - Deciding between dense vs spacious layouts for a merchant-facing dashboard - Asked about brand expression — when can you override Polaris colors, and when shouldn't you - About to ship an "infinite settings" page and want the heuristic for whether each setting earns its place - Considering a custom design system on top of Polaris (almost always wrong — this skill explains why) Do NOT use when: - Building a checkout extension or storefront block — those have their own constraints (Checkout UI Extensions, theme app extensions) - Building a non-embedded surface (POS, mobile app shell) - The merchant has explicitly asked for a Shopify-default-looking app for trust reasons (rare, but real for some legal/finance apps) --- ## The Six Modern SaaS UX Principles (And How Each Lands Inside Polaris) Every modern SaaS app worth copying — Linear, Notion, Vercel, Cron, Raycast, Superhuman, Arc — converges on these six principles. The trick is translating each into something Polaris-compliant. ### 1. Speed Above Everything Linear's mantra is "fast is a feature." Anything under 100ms feels instant, anything over 300ms feels slow, anything over 1s loses the user. Modern apps engineer the perceived performance budget aggressively — optimistic UI updates, prefetching, route-level caching, skeleton screens that match real layout. **Inside Polaris:** Polaris doesn't fight you here. It ships fast-rendering primitives. The bottlenecks are usually (a) your Remix loaders waiting on Shopify GraphQL, (b) re-renders from unmemoized state, (c) no optimistic updates on mutations. Polaris does NOT ship a built-in optimistic UI helper — you wire it yourself with Remix `useFetcher` or TanStack Query. ### 2. Density (When the Merchant Is Power) Linear, Notion, Airtable use **information-dense** layouts. More rows, smaller padding, tighter typography. The merchant who lives in your app 4 hours a day wants more data per pixel, not more whitespace. **Inside Polaris:** Polaris spacing tokens default to spacious (gap `400` = 24px). For power-user surfaces, drop to `200` or `300`. `IndexTable`
Preview of the first 4,000 characters. Read full instructions →
---
name: ux-onboarding
description: "Use when designing the first-run/onboarding experience of a Shopify embedded app. Covers the first-30-second rule, required-vs-optional setup, checklist vs wizard vs deferred-config vs sample-data, time-to-value targets, the 'aha moment' pattern, personalization using shop's currency/language/niche, activation events to instrument, and 15 onboarding pattern recipes built on Polaris components. Triggers: 'shopify app onboarding', 'first run', 'first time experience', 'app activation', 'onboarding checklist', 'wizard', 'empty state first install', 'time to value', 'aha moment', 'shopify app welcome screen', 'guide merchant'."
---
# Shopify Embedded App: First-Run Onboarding UX
Onboarding is the single highest-leverage screen in your app. A merchant who never reaches "aha" within their first session uninstalls inside 7 days at rates of 40-60% across the App Store. The goal of this skill is to get every merchant to one observable, on-store value moment in under 5 minutes, with zero theme code edits and zero credit-card friction.
This skill is opinionated. It is built on (1) the Shopify Built for Shopify requirements, (2) the Polaris onboarding guidance, (3) a teardown of 6 top-grossing apps (Klaviyo, Gorgias, Judge.me, Loox, Vitals, PageFly).
---
## 1. When to use
Pull this skill in when you are:
- Designing the welcome screen / first-run flow of a brand new Shopify embedded app
- Reworking an existing app's activation funnel because installs are not converting to paid
- Adding a "setup guide" or "getting started checklist" to an existing dashboard
- Deciding whether to gate the app behind a wizard or drop merchants into a tile-grid
- Pursuing the Built for Shopify badge (which has explicit onboarding requirements)
- Writing the empty state for the merchant's first visit before any data exists
- Auditing your own app and asking "why is our 7-day retention so bad"
Skip this skill if you are working on a public storefront (Hydrogen/Liquid) - that is a different audience and a different onboarding model.
---
## 2. The "first 30 seconds" rule
When a merchant clicks Install on the App Store and approves your scopes, your app loads inside an iframe in the Shopify admin. The first thing they see is yours to design. Built for Shopify reviewers grade this screen. Real merchants decide whether to keep your app based on what they see in roughly 30 seconds.
**What must be visible in the first 30 seconds:**
1. **A clear app title** - use the App Bridge `<ui-title-bar>` web component or Polaris `<Page title>`. The merchant should see your app name and nothing else competing for it.
2. **A one-sentence promise** - the same outcome verb you led with on the App Store listing ("Convert more shoppers", "Replace 10 apps", "Send your first review request in 60 seconds"). Use Polaris `<Text variant="bodyLg" tone="subdued">`.
3. **One primary CTA** - a single Polaris `<Button variant="primary">` that starts the activation path. Never two competing primary actions on the welcome screen.
4. **Proof the app is connected** - a small `<Badge tone="success">Connected to {shop}</Badge>` confirms OAuth worked. Removes the merchant's "did it install correctly" anxiety.
5. **A skip / dismiss option** - per Built for Shopify guidance, onboarding must be dismissible. A "Skip for now" Polaris `<Button variant="plain">` in the top-right.
**What must NOT be in the first 30 seconds:**
- A video that auto-plays
- A modal popup ("Welcome!" interrupting the welcome screen is hostile)
- A form with more than 3 fields
- Any request for credit card, billing, or upgrade
- A request for OAuth scopes you didn't ask for at install
- An external link that opens a new tab (the iframe context dies)
**Iframe-aware loading:**
The embedded app loads inside `https://admin.shopify.com/store/{shop}/apps/{your-app}`. The iframe has constraints: third-party cookies are not guaranteed, the URL has the `shop`, `host`, and `embedded` querPreview of the first 4,000 characters. Read full instructions →
--- name: ux-polaris-antipatterns description: "Use when reviewing or writing Polaris UI for common design mistakes — using deprecated Stack instead of BlockStack/InlineStack, modal overuse, blocking validation, wrong tone (success/critical/warning/info), custom CSS overrides instead of tokens, off-brand colors, mis-sized cards, missing helpText, no FormLayout, mobile responsive failures, accessibility failures inside Polaris components, drifting between Polaris versions. Triggers: 'polaris mistake', 'polaris anti-pattern', 'polaris stack deprecated', 'polaris design review', 'shopify ui code review', 'polaris best practice', 'polaris vs custom', 'polaris tokens'." --- # Polaris UI Anti-Patterns (v12+) A field guide to the 20 most common ways Shopify app teams break the Polaris contract — and the exact fix for each. Use this when reviewing a PR, writing a new screen, or auditing an app pre-submission for Built for Shopify. The principle behind every rule: **Shopify admin is a shared design surface.** Merchants have already learned its patterns. The closer your app feels to the rest of admin, the higher your install-to-activation rate. The further you drift, the more your app feels like a third-party graft — and the more support tickets you get from confused merchants. --- ## 1. When to use Pull this skill in when you are: - Reviewing a pull request that touches `@shopify/polaris` components - Writing a new screen and unsure whether a custom component is warranted - Migrating from Polaris 10 or 11 to 12+ - Preparing an app for App Store submission or Built for Shopify certification - Debugging "why does our app look off-brand?" complaints - Diagnosing accessibility audit failures - Deciding between `<Modal>`, `<Banner>`, `<Toast>`, or inline error - Choosing between custom CSS and design tokens If the user mentions Polaris, Stack, BlockStack, design tokens, `--p-color-*`, `className` on Polaris components, Modal overuse, or "this feels off-brand" — trigger this skill. --- ## 2. The 20 anti-patterns, ranked by severity Ranked by how badly each one degrades the merchant experience (1 = catastrophic, 20 = nit). Fixes are in the "do this instead" column. | # | Anti-pattern | Severity | Do this instead | |---|---|---|---| | 1 | Using `<Stack>` / `<LegacyStack>` / `<VerticalStack>` / `<HorizontalStack>` | Build-breaking on v12+ | `<BlockStack>` (vertical) or `<InlineStack>` (horizontal). Run `npx @shopify/polaris-migrator` | | 2 | Wrapping Polaris components in custom `className` for styling | High — most Polaris components do not accept `className` | Use the component's built-in props (`tone`, `variant`, `padding`, `gap`). For exceptions, use `<Box>` with token props | | 3 | Hex codes (`color: #008060`) instead of design tokens | High — instantly off-brand on theme changes | `var(--p-color-bg-fill-success)` or a `tone` prop | | 4 | Modal for non-blocking errors or confirmations | High — blocks the merchant; high abandonment | `<Banner>` for in-context info, `<Toast>` for transient confirmations, inline error for forms | | 5 | Toast for errors that need explanation | High — disappears in 3s, easily missed | `<Banner tone="critical">` with title + body + recovery action | | 6 | Using `tone="success"` for neutral or informational | Medium — semantic noise | `tone="info"` for info, no tone for neutral | | 7 | Using `tone="critical"` for warnings | Medium — desensitizes the merchant to real errors | `tone="warning"` for cautionary, `tone="critical"` only for destructive/error | | 8 | Missing `<FormLayout>` around form fields | Medium — inconsistent spacing | Always wrap related fields in `<FormLayout>` inside `<Form>` | | 9 | Blocking validation on every keystroke | Medium — feels hostile, breaks flow | Validate on blur or on submit; clear errors on next change | | 10 | Missing `helpText` on non-obvious fields | Medium — drives support tickets | `helpText` describing format, examples, or constraints | | 11 | Forgetting to imp
Preview of the first 4,000 characters. Read full instructions →
---
name: webhooks
description: "Webhook delivery methods, verification, retry behavior, payload handling, and implementation patterns for Shopify events. Triggers include: 'set up webhook', 'verify webhook signature', 'webhook delivery', 'HMAC verification', 'webhook retry', 'event subscription', 'webhook payload', 'AWS EventBridge Shopify', 'Google Pub/Sub webhook', 'webhook manifest'."
---
# Shopify Webhooks Implementation Guide
## When to Use This Skill
Use webhooks when you need to:
- Receive real-time event notifications from Shopify (orders, products, customers, fulfillments, etc.)
- Sync external systems with Shopify data changes
- Trigger automated workflows based on shop events
- Monitor GDPR compliance actions (customer data erasure, shop deletion)
- Process bulk operations completion
- Update inventory or pricing in third-party systems
## Webhook Delivery Methods
### 1. HTTPS (Traditional)
Most common delivery method. Webhooks sent as POST requests to your publicly accessible HTTPS endpoint.
**Characteristics:**
- Requires public HTTPS endpoint (443, TLS 1.2+)
- Real-time delivery (within seconds)
- Max 5 retries over 48 hours (exponential backoff: 10s, 30s, 1m, 2m, 8h)
- Request timeout: 30 seconds
- Payload size: max 2MB
- Rate limiting: respect Shopify API rate limits
**Configuration Example:**
```json
{
"deliveryMethod": {
"https": {
"address": "https://myapp.example.com/webhooks/shopify"
}
},
"query": "subscription { event { id occurredAt } }",
"filter": "orders/created"
}
```
### 2. AWS EventBridge
Asynchronous delivery via AWS EventBridge. Events queued in partner event bus.
**Characteristics:**
- No public endpoint needed
- Queued delivery (managed by EventBridge)
- Scalable, event-sourcing ready
- Requires AWS EventBridge partner event bus setup
- Lower operational overhead
- Better for high-volume events
**Setup Steps:**
```bash
# 1. Shopify creates AWS partner event bus in your account
# 2. Your app subscribes to webhooks via EventBridge configuration
# 3. Events appear in partner event bus: aws.partner/shopify.com/[app-id]/[account-id]
# 3. Create rule to route to your targets (SQS, Lambda, etc.)
aws events put-rule \
--name shopify-webhook-router \
--event-bus-name aws.partner/shopify.com/12345/default \
--state ENABLED
```
**Example Event:**
```json
{
"detail-type": "orders/created",
"detail": {
"id": "gid://shopify/Order/123456",
"displayOrderNumber": "#1001",
"email": "customer@example.com",
"createdAt": "2026-05-04T14:30:00Z",
"totalPriceSet": {
"shopMoney": {
"amount": "299.99",
"currencyCode": "USD"
}
}
},
"source": "aws.partner/shopify.com/12345/default"
}
```
### 3. Google Cloud Pub/Sub
Event streaming via Google Pub/Sub. Decoupled, scalable webhook delivery.
**Characteristics:**
- No public endpoint needed
- Managed queue with exactly-once semantics
- Scalable message processing
- Requires Google Cloud project setup
- Integration with Cloud Functions, Dataflow, etc.
- Best for data pipeline workflows
**Configuration:**
```bash
# 1. Create Pub/Sub topic in Google Cloud
gcloud pubsub topics create shopify-webhooks
# 2. Subscribe your app to receive messages
gcloud pubsub subscriptions create shopify-webhook-sub \
--topic=shopify-webhooks \
--push-endpoint=https://your-service.com/pubsub-handler
# 3. Create service account for Shopify to publish
gcloud iam service-accounts create shopify-publisher
gcloud pubsub topics add-iam-policy-binding shopify-webhooks \
--member=serviceAccount:shopify-publisher@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/pubsub.publisher
```
## HMAC Verification (HTTPS Only)
All HTTPS webhooks are signed with HMAC-SHA256. Always verify signatures.
**Headers:**
- `X-Shopify-Hmac-SHA256`: Base64-encoded HMAC-SHA256 signature
- `X-Shopify-Shop-Api-Access-Token`: OAuth token used (for debugging)
- `X-Shopify-Webhook-Id`: Unique webhook instance ID
- `X-ShPreview of the first 4,000 characters. Read full instructions →
Publisher declarations from the archived package. These are separate from our research and the live service's terms.
Package observed Nov 19, 2026.
plugins_6a701c7b1f9481919cf7c7448ddc1bd4
Download plugin data (JSON)Plugin details: served from cache. Prepared . Refreshed when plugin data changes or after 6 hours. Your account and Follow status are live.