Shopify Development

1---
2name: shopify-development
3description: |
4  Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.
5  TRIGGER: "shopify", "shopify app", "checkout extension", "admin extension", "POS extension",
6  "shopify theme", "liquid template", "polaris", "shopify graphql", "shopify webhook",
7  "shopify billing", "app subscription", "metafields", "shopify functions"
8---
9 
10# Shopify Development Skill
11 
12Use this skill when the user asks about:
13 
14- Building Shopify apps or extensions
15- Creating checkout/admin/POS UI customizations
16- Developing themes with Liquid templating
17- Integrating with Shopify GraphQL or REST APIs
18- Implementing webhooks or billing
19- Working with metafields or Shopify Functions
20 
21---
22 
23## ROUTING: What to Build
24 
25**IF user wants to integrate external services OR build merchant tools OR charge for features:**
26→ Build an **App** (see `references/app-development.md`)
27 
28**IF user wants to customize checkout OR add admin UI OR create POS actions OR implement discount rules:**
29→ Build an **Extension** (see `references/extensions.md`)
30 
31**IF user wants to customize storefront design OR modify product/collection pages:**
32→ Build a **Theme** (see `references/themes.md`)
33 
34**IF user needs both backend logic AND storefront UI:**
35→ Build **App + Theme Extension** combination
36 
37---
38 
39## Shopify CLI Commands
40 
41Install CLI:
42 
43```bash
44npm install -g @shopify/cli@latest
45```
46 
47Create and run app:
48 
49```bash
50shopify app init          # Create new app
51shopify app dev           # Start dev server with tunnel
52shopify app deploy        # Build and upload to Shopify
53```
54 
55Generate extension:
56 
57```bash
58shopify app generate extension --type checkout_ui_extension
59shopify app generate extension --type admin_action
60shopify app generate extension --type admin_block
61shopify app generate extension --type pos_ui_extension
62shopify app generate extension --type function
63```
64 
65Theme development:
66 
67```bash
68shopify theme init        # Create new theme
69shopify theme dev         # Start local preview at localhost:9292
70shopify theme pull --live # Pull live theme
71shopify theme push --development  # Push to dev theme
72```
73 
74---
75 
76## Access Scopes
77 
78Configure in `shopify.app.toml`:
79 
80```toml
81[access_scopes]
82scopes = "read_products,write_products,read_orders,write_orders,read_customers"
83```
84 
85Common scopes:
86 
87- `read_products`, `write_products` - Product catalog access
88- `read_orders`, `write_orders` - Order management
89- `read_customers`, `write_customers` - Customer data
90- `read_inventory`, `write_inventory` - Stock levels
91- `read_fulfillments`, `write_fulfillments` - Order fulfillment
92 
93---
94 
95## GraphQL Patterns (Validated against API 2026-01)
96 
97### Query Products
98 
99```graphql
100query GetProducts($first: Int!, $query: String) {
101  products(first: $first, query: $query) {
102    edges {
103      node {
104        id
105        title
106        handle
107        status
108        variants(first: 5) {
109          edges {
110            node {
111              id
112              price
113              inventoryQuantity
114            }
115          }
116        }
117      }
118    }
119    pageInfo {
120      hasNextPage
121      endCursor
122    }
123  }
124}
125```
126 
127### Query Orders
128 
129```graphql
130query GetOrders($first: Int!) {
131  orders(first: $first) {
132    edges {
133      node {
134        id
135        name
136        createdAt
137        displayFinancialStatus
138        totalPriceSet {
139          shopMoney {
140            amount
141            currencyCode
142          }
143        }
144      }
145    }
146  }
147}
148```
149 
150### Set Metafields
151 
152```graphql
153mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
154  metafieldsSet(metafields: $metafields) {
155    metafields {
156      id
157      namespace
158      key
159      value
160    }
161    userErrors {
162      field
163      message
164    }
165  }
166}
167```
168 
169Variables example:
170 
171```json
172{
173  "metafields": [
174    {
175      "ownerId": "gid://shopify/Product/123",
176      "namespace": "custom",
177      "key": "care_instructions",
178      "value": "Handle with care",
179      "type": "single_line_text_field"
180    }
181  ]
182}
183```
184 
185---
186 
187## Checkout Extension Example
188 
189```tsx
190import {
191  reactExtension,
192  BlockStack,
193  TextField,
194  Checkbox,
195  useApplyAttributeChange,
196} from "@shopify/ui-extensions-react/checkout";
197 
198export default reactExtension("purchase.checkout.block.render", () => (
199  <GiftMessage />
200));
201 
202function GiftMessage() {
203  const [isGift, setIsGift] = useState(false);
204  const [message, setMessage] = useState("");
205  const applyAttributeChange = useApplyAttributeChange();
206 
207  useEffect(() => {
208    if (isGift && message) {
209      applyAttributeChange({
210        type: "updateAttribute",
211        key: "gift_message",
212        value: message,
213      });
214    }
215  }, [isGift, message]);
216 
217  return (
218    <BlockStack spacing="loose">
219      <Checkbox checked={isGift} onChange={setIsGift}>
220        This is a gift
221      </Checkbox>
222      {isGift && (
223        <TextField
224          label="Gift Message"
225          value={message}
226          onChange={setMessage}
227          multiline={3}
228        />
229      )}
230    </BlockStack>
231  );
232}
233```
234 
235---
236 
237## Liquid Template Example
238 
239```liquid
240{% comment %} Product Card Snippet {% endcomment %}
241<div class="product-card">
242  <a href="{{ product.url }}">
243    {% if product.featured_image %}
244      <img
245        src="{{ product.featured_image | img_url: 'medium' }}"
246        alt="{{ product.title | escape }}"
247        loading="lazy"
248      >
249    {% endif %}
250    <h3>{{ product.title }}</h3>
251    <p class="price">{{ product.price | money }}</p>
252    {% if product.compare_at_price > product.price %}
253      <p class="sale-badge">Sale</p>
254    {% endif %}
255  </a>
256</div>
257```
258 
259---
260 
261## Webhook Configuration
262 
263In `shopify.app.toml`:
264 
265```toml
266[webhooks]
267api_version = "2026-01"
268 
269[[webhooks.subscriptions]]
270topics = ["orders/create", "orders/updated"]
271uri = "/webhooks/orders"
272 
273[[webhooks.subscriptions]]
274topics = ["products/update"]
275uri = "/webhooks/products"
276 
277# GDPR mandatory webhooks (required for app approval)
278[webhooks.privacy_compliance]
279customer_data_request_url = "/webhooks/gdpr/data-request"
280customer_deletion_url = "/webhooks/gdpr/customer-deletion"
281shop_deletion_url = "/webhooks/gdpr/shop-deletion"
282```
283 
284---
285 
286## Best Practices
287 
288### API Usage
289 
290- Use GraphQL over REST for new development
291- Request only fields you need (reduces query cost)
292- Implement cursor-based pagination with `pageInfo.endCursor`
293- Use bulk operations for processing more than 250 items
294- Handle rate limits with exponential backoff
295 
296### Security
297 
298- Store API credentials in environment variables
299- Always verify webhook HMAC signatures before processing
300- Validate OAuth state parameter to prevent CSRF
301- Request minimal access scopes
302- Use session tokens for embedded apps
303 
304### Performance
305 
306- Cache API responses when data doesn't change frequently
307- Use lazy loading in extensions
308- Optimize images in themes using `img_url` filter
309- Monitor GraphQL query costs via response headers
310 
311---
312 
313## Troubleshooting
314 
315**IF you see rate limit errors:**
316→ Implement exponential backoff retry logic
317→ Switch to bulk operations for large datasets
318→ Monitor `X-Shopify-Shop-Api-Call-Limit` header
319 
320**IF authentication fails:**
321→ Verify the access token is still valid
322→ Check that all required scopes were granted
323→ Ensure OAuth flow completed successfully
324 
325**IF extension is not appearing:**
326→ Verify the extension target is correct
327→ Check that extension is published via `shopify app deploy`
328→ Confirm the app is installed on the test store
329 
330**IF webhook is not receiving events:**
331→ Verify the webhook URL is publicly accessible
332→ Check HMAC signature validation logic
333→ Review webhook logs in Partner Dashboard
334 
335**IF GraphQL query fails:**
336→ Validate query against schema (use GraphiQL explorer)
337→ Check for deprecated fields in error message
338→ Verify you have required access scopes
339 
340---
341 
342## Reference Files
343 
344For detailed implementation guides, read these files:
345 
346- `references/app-development.md` - OAuth authentication flow, GraphQL mutations for products/orders/billing, webhook handlers, billing API integration
347- `references/extensions.md` - Checkout UI components, Admin UI extensions, POS extensions, Shopify Functions for discounts/payment/delivery
348- `references/themes.md` - Liquid syntax reference, theme directory structure, sections and snippets, common patterns
349 
350---
351 
352## Scripts
353 
354- `scripts/shopify_init.py` - Interactive project scaffolding. Run: `python scripts/shopify_init.py`
355- `scripts/shopify_graphql.py` - GraphQL utilities with query templates, pagination, rate limiting. Import: `from shopify_graphql import ShopifyGraphQL`
356 
357---
358 
359## Official Documentation Links
360 
361- Shopify Developer Docs: https://shopify.dev/docs
362- GraphQL Admin API Reference: https://shopify.dev/docs/api/admin-graphql
363- Shopify CLI Reference: https://shopify.dev/docs/api/shopify-cli
364- Polaris Design System: https://polaris.shopify.com
365 
366API Version: 2026-01 (quarterly releases, 12-month deprecation window)
367