Shopify Development Skill
Use this skill when the user asks about:
- Building Shopify apps or extensions
- Creating checkout/admin/POS UI customizations
- Developing themes with Liquid templating
- Integrating with Shopify GraphQL or REST APIs
- Implementing webhooks or billing
- Working with metafields or Shopify Functions
ROUTING: What to Build
IF user wants to integrate external services OR build merchant tools OR charge for features:
→ Build an App (see references/app-development.md)
IF user wants to customize checkout OR add admin UI OR create POS actions OR implement discount rules:
→ Build an Extension (see references/extensions.md)
IF user wants to customize storefront design OR modify product/collection pages:
→ Build a Theme (see references/themes.md)
IF user needs both backend logic AND storefront UI:
→ Build App + Theme Extension combination
Shopify CLI Commands
Install CLI:
bash
1npm install -g @shopify/cli@latest
Create and run app:
bash
1shopify app init # Create new app
2shopify app dev # Start dev server with tunnel
3shopify app deploy # Build and upload to Shopify
Generate extension:
bash
1shopify app generate extension --type checkout_ui_extension
2shopify app generate extension --type admin_action
3shopify app generate extension --type admin_block
4shopify app generate extension --type pos_ui_extension
5shopify app generate extension --type function
Theme development:
bash
1shopify theme init # Create new theme
2shopify theme dev # Start local preview at localhost:9292
3shopify theme pull --live # Pull live theme
4shopify theme push --development # Push to dev theme
Access Scopes
Configure in shopify.app.toml:
toml
1[access_scopes]
2scopes = "read_products,write_products,read_orders,write_orders,read_customers"
Common scopes:
read_products, write_products - Product catalog accessread_orders, write_orders - Order managementread_customers, write_customers - Customer dataread_inventory, write_inventory - Stock levelsread_fulfillments, write_fulfillments - Order fulfillment
GraphQL Patterns (Validated against API 2026-01)
Query Products
graphql
1query GetProducts($first: Int!, $query: String) {
2 products(first: $first, query: $query) {
3 edges {
4 node {
5 id
6 title
7 handle
8 status
9 variants(first: 5) {
10 edges {
11 node {
12 id
13 price
14 inventoryQuantity
15 }
16 }
17 }
18 }
19 }
20 pageInfo {
21 hasNextPage
22 endCursor
23 }
24 }
25}
Query Orders
graphql
1query GetOrders($first: Int!) {
2 orders(first: $first) {
3 edges {
4 node {
5 id
6 name
7 createdAt
8 displayFinancialStatus
9 totalPriceSet {
10 shopMoney {
11 amount
12 currencyCode
13 }
14 }
15 }
16 }
17 }
18}
graphql
1mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
2 metafieldsSet(metafields: $metafields) {
3 metafields {
4 id
5 namespace
6 key
7 value
8 }
9 userErrors {
10 field
11 message
12 }
13 }
14}
Variables example:
json
1{
2 "metafields": [
3 {
4 "ownerId": "gid://shopify/Product/123",
5 "namespace": "custom",
6 "key": "care_instructions",
7 "value": "Handle with care",
8 "type": "single_line_text_field"
9 }
10 ]
11}
Checkout Extension Example
tsx
1import {
2 reactExtension,
3 BlockStack,
4 TextField,
5 Checkbox,
6 useApplyAttributeChange,
7} from "@shopify/ui-extensions-react/checkout";
8
9export default reactExtension("purchase.checkout.block.render", () => (
10 <GiftMessage />
11));
12
13function GiftMessage() {
14 const [isGift, setIsGift] = useState(false);
15 const [message, setMessage] = useState("");
16 const applyAttributeChange = useApplyAttributeChange();
17
18 useEffect(() => {
19 if (isGift && message) {
20 applyAttributeChange({
21 type: "updateAttribute",
22 key: "gift_message",
23 value: message,
24 });
25 }
26 }, [isGift, message]);
27
28 return (
29 <BlockStack spacing="loose">
30 <Checkbox checked={isGift} onChange={setIsGift}>
31 This is a gift
32 </Checkbox>
33 {isGift && (
34 <TextField
35 label="Gift Message"
36 value={message}
37 onChange={setMessage}
38 multiline={3}
39 />
40 )}
41 </BlockStack>
42 );
43}
Liquid Template Example
liquid
1{% comment %} Product Card Snippet {% endcomment %}
2<div class="product-card">
3 <a href="{{ product.url }}">
4 {% if product.featured_image %}
5 <img
6 src="{{ product.featured_image | img_url: 'medium' }}"
7 alt="{{ product.title | escape }}"
8 loading="lazy"
9 >
10 {% endif %}
11 <h3>{{ product.title }}</h3>
12 <p class="price">{{ product.price | money }}</p>
13 {% if product.compare_at_price > product.price %}
14 <p class="sale-badge">Sale</p>
15 {% endif %}
16 </a>
17</div>
Webhook Configuration
In shopify.app.toml:
toml
1[webhooks]
2api_version = "2026-01"
3
4[[webhooks.subscriptions]]
5topics = ["orders/create", "orders/updated"]
6uri = "/webhooks/orders"
7
8[[webhooks.subscriptions]]
9topics = ["products/update"]
10uri = "/webhooks/products"
11
12# GDPR mandatory webhooks (required for app approval)
13[webhooks.privacy_compliance]
14customer_data_request_url = "/webhooks/gdpr/data-request"
15customer_deletion_url = "/webhooks/gdpr/customer-deletion"
16shop_deletion_url = "/webhooks/gdpr/shop-deletion"
Best Practices
API Usage
- Use GraphQL over REST for new development
- Request only fields you need (reduces query cost)
- Implement cursor-based pagination with
pageInfo.endCursor
- Use bulk operations for processing more than 250 items
- Handle rate limits with exponential backoff
Security
- Store API credentials in environment variables
- Always verify webhook HMAC signatures before processing
- Validate OAuth state parameter to prevent CSRF
- Request minimal access scopes
- Use session tokens for embedded apps
- Cache API responses when data doesn't change frequently
- Use lazy loading in extensions
- Optimize images in themes using
img_url filter
- Monitor GraphQL query costs via response headers
Troubleshooting
IF you see rate limit errors:
→ Implement exponential backoff retry logic
→ Switch to bulk operations for large datasets
→ Monitor X-Shopify-Shop-Api-Call-Limit header
IF authentication fails:
→ Verify the access token is still valid
→ Check that all required scopes were granted
→ Ensure OAuth flow completed successfully
IF extension is not appearing:
→ Verify the extension target is correct
→ Check that extension is published via shopify app deploy
→ Confirm the app is installed on the test store
IF webhook is not receiving events:
→ Verify the webhook URL is publicly accessible
→ Check HMAC signature validation logic
→ Review webhook logs in Partner Dashboard
IF GraphQL query fails:
→ Validate query against schema (use GraphiQL explorer)
→ Check for deprecated fields in error message
→ Verify you have required access scopes
Reference Files
For detailed implementation guides, read these files:
references/app-development.md - OAuth authentication flow, GraphQL mutations for products/orders/billing, webhook handlers, billing API integrationreferences/extensions.md - Checkout UI components, Admin UI extensions, POS extensions, Shopify Functions for discounts/payment/deliveryreferences/themes.md - Liquid syntax reference, theme directory structure, sections and snippets, common patterns
Scripts
scripts/shopify_init.py - Interactive project scaffolding. Run: python scripts/shopify_init.pyscripts/shopify_graphql.py - GraphQL utilities with query templates, pagination, rate limiting. Import: from shopify_graphql import ShopifyGraphQL
Official Documentation Links
API Version: 2026-01 (quarterly releases, 12-month deprecation window)
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
