Shopify Builder

This skill provides automated workflows for building and decorating a Shopify store. It leverages the Shopify Admin API (REST and GraphQL) to handle product management, theme assets, and global settings.

Store Registration & Setup

Before any API work, ensure the merchant has a live store and valid API credentials.

Access Token (shpat_*) — source of truth: The only supported procedure for obtaining an Access Token (Dev Dashboard, install, client-credentials exchange) is documented in references/oauth-client-credentials.md. Do not infer token steps from memory or from fragments elsewhere in this file; read that reference whenever you need to acquire or refresh a token.

1. Go to shopify.com → click Start free trial.
2. Enter email, set a password, choose a store name and region.
3. Open Admin at https://[your-store].myshopify.com/admin.
4. Configure Settings → Payments, Shipping, and Domains as needed.

Getting API Credentials — Client Credentials OAuth

Mandatory — read the reference, not a summary: To obtain an Access Token (shpat_*), you must read references/oauth-client-credentials.md from start to finish. This SKILL file intentionally omits the step-by-step token flow; all concrete steps (app creation, version release, install, credential retrieval, curl token exchange, validation, troubleshooting) live only in that reference. If you do not already hold a valid shpat_*, do not create apps, exchange credentials, or call the Admin API until you have read it. Skipping it causes predictable failures (e.g. shop_not_permitted, wrong Content-Type on token exchange).

Canonical procedure: references/oauth-client-credentials.md.

Credential Detection Logic

When the user provides credentials, determine how to proceed:

User provides	Action
Store domain + Client ID + Client Secret (shpss_*)	Immediately run token exchange — Windows: Invoke-RestMethod with client_credentials grant (see Step 5 of oauth-client-credentials.md)；macOS/Linux: curl with client_credentials grant. Do NOT ask the user to run this themselves. Do NOT open a browser first — try CLI exchange first, only investigate app installation if it fails with 400.
A single shpat_* token	Use directly (already an Access Token)
Nothing / partial	Ask for the following three values only — do NOT mention shpat_* to the user, do NOT ask them to run curl: store domain (xxx.myshopify.com), Client ID, Client Secret (shpss_*). Walk them through Dev Dashboard Steps 1–4 to obtain these, then exchange the token yourself.

Gate: Do NOT attempt any API operation until a valid Access Token (shpat_*) is confirmed. If the token is missing or uncertain, stop and follow references/oauth-client-credentials.md to obtain it — do not substitute ad-hoc OAuth steps.

API Execution Rules

Tool hierarchy (strictly follow this order):

1. Shopify GraphQL Admin API (primary) — use for all reads and writes via Invoke-RestMethod (Windows) or curl (macOS/Linux) with the Access Token.
2. Manual click-path instructions — only for destructive or human-confirmation actions (e.g. deleting billing info).
3. Browser tool (fallback) — only if the API returns consistent errors, the action is not exposed via API, or platform restrictions block automation.

Prefer GraphQL over REST for all new development. REST endpoints are legacy; use them only when a GraphQL equivalent is unavailable.

API call pattern — all requests use the exchanged/provided token:

Windows（PowerShell）：

# GraphQL
$headers = @{ "X-Shopify-Access-Token" = "{ACCESS_TOKEN}"; "Content-Type" = "application/json" }
$body = '{"query": "...", "variables": {...}}'
Invoke-RestMethod -Uri "https://{STORE_NAME}.myshopify.com/admin/api/2026-01/graphql.json" -Method Post -Headers $headers -Body $body

# REST（legacy, use only when GraphQL unavailable）
$headers = @{ "X-Shopify-Access-Token" = "{ACCESS_TOKEN}" }
Invoke-RestMethod -Uri "https://{STORE_NAME}.myshopify.com/admin/api/2026-01/{resource}.json" -Headers $headers

macOS/Linux（bash）：

# GraphQL
curl -s -X POST "https://{STORE_NAME}.myshopify.com/admin/api/2026-01/graphql.json" \
  -H "X-Shopify-Access-Token: {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "...", "variables": {...}}'

# REST（legacy, use only when GraphQL unavailable）
curl -s "https://{STORE_NAME}.myshopify.com/admin/api/2026-01/{resource}.json" \
  -H "X-Shopify-Access-Token: {ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

Instructions

1. Supplier contact sourcing (CRITICAL — read first)

Do not attempt to find supplier email addresses on Alibaba product or detail URLs. Those pages do not expose usable supplier email.

Primary method — Google search (run in this session; do not spawn a subagent): For each supplier, search Google with the supplier or company name plus email, e.g. {supplier_or_company_name} email (quote the name if it helps disambiguate). Open several results across the first page(s)—alibaba.com listings often still lack a public email, so deliberately check non-Alibaba hits (official site, LinkedIn, trade directories, PDF/catalog pages, contact pages). Extract only publicly visible addresses from those pages; do not invent or guess addresses.

Expectation: It is not required to discover an email for every supplier or SKU. Partial coverage is acceptable—proceed with whatever verified contact you can find; do not block the workflow on 100% email coverage.

2. Shopify API Validation Protocol (Critical)

For every modification:

1. Inspect Response: Check for errors or userErrors in the API response — a 200 OK does NOT mean the write succeeded.
2. Publication State: Ensure products are status: active and explicitly published to the "Online Store" channel.
3. Media Success: Verify images are correctly assigned after upload.
4. Read-Back: Execute a GET request after any write to verify storefront-facing values.
5. API Documentation Fallback: When a GraphQL schema, field, or endpoint behaviour is uncertain, consult shopify-dev-mcp for live documentation lookup before retrying blindly.

3. Product Listing Workflow

1. Product Data: Products must come from a prior sourcing stage. If no products have been selected yet, read and follow the market-insight-product-selection skill to run sourcing first — do NOT proceed with listing until at least one product with a confirmed supplier URL is available.
2. Optimize: Rewrite descriptions into a structured format (Headline -> 3-5 Benefit Bullets -> Specs -> Care instructions).
3. Pricing: Set retail price (3-5x markup of Landed Cost) and compare_at_price (1.5x of retail).
4. API Upload (REST):
   • Endpoint: POST /admin/api/2026-01/products.json
   • Payload:

     {
       "product": {
         "title": "SEO Optimized Title",
         "body_html": "<h3>Headline</h3><ul><li>Feature</li></ul>",
         "vendor": "Brand Name",
         "product_type": "Category",
         "status": "active",
         "images": [{ "src": "https://..." }],
         "options": [{ "name": "Size", "values": ["S", "M"] }],
         "variants": [{ "option1": "S", "price": "39.99", "compare_at_price": "59.99" }]
       }
     }
     

4. Homepage Hero Banner Deployment

1. Generate Asset: Use image_generate (16:9).
2. Upload to Shopify Media (GraphQL):
   • Mutation: fileCreate
   • Query:

     mutation fileCreate($files: [FileCreateInput!]!) {
       fileCreate(files: $files) {
         files { id alt ... on MediaImage { image { url } } }
       }
     }
     

3. Resolve Path: Extract filename from the returned URL to use the shopify://shop_images/{filename} format.
4. Update Template: Use PUT /admin/api/2026-01/themes/{theme_id}/assets.json to update templates/index.json.

5. Seasonal Branding (Easter, BFCM, etc.)

1. Global Color Schemes: Patch config/settings_data.json using a Python/JQ script to update hex codes in color_schemes (e.g., scheme-1, scheme-6).
2. Announcement Bar: Update sections/header-group.json with the seasonal promo text.
   • Constraint: Maintain block IDs; only modify text and link.

6. Marquee (Scrolling Text) Injection

1. Section Injection: Add a block with type: marquee to sections in templates/index.json.
2. Update Order: Add the marquee ID to the order array.
3. HTML Constraint: Wrap marquee text blocks in valid HTML tags (e.g., <p>EASTER SALE IS LIVE!</p>).

Store Preview (Password-Protected Stores)

New Shopify stores are locked by default. To preview:

1. Admin → Online Store → Preferences → Storefront password — copy the password shown.
2. Open the store URL, click "Enter using password", enter the password.

Always check password_enabled in GET /admin/api/2026-01/shop.json before screenshotting.

GraphQL Admin API

Use GraphQL (not REST) for all new development. REST remains available but receives fewer updates.

Endpoint:

POST https://{store}.myshopify.com/admin/api/2026-01/graphql.json

Headers:

{
  "X-Shopify-Access-Token": "shpat_...",
  "Content-Type": "application/json"
}

Key mutations for store building:

Create product:

mutation CreateProduct($input: ProductInput!) {
  productCreate(input: $input) {
    product { id title handle }
    userErrors { field message }
  }
}

Upload media (banner images, product images):

mutation fileCreate($files: [FileCreateInput!]!) {
  fileCreate(files: $files) {
    files { id alt ... on MediaImage { image { url } } }
  }
}

Register webhook:

mutation CreateWebhook($input: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(input: $input) {
    webhookSubscription { id topic }
    userErrors { field message }
  }
}

Rate limiting: 50 cost points/second. Check X-Shopify-GraphQL-Admin-Api-Call-Limit header; use exponential backoff on HTTP 429.

Always check userErrors in every mutation response — a 200 OK does not mean the write succeeded.

Full reference: references/api-admin.md

---

Storefront API

Public GraphQL API for headless storefronts and theme-side data fetching.

Endpoint:

POST https://{store}.myshopify.com/api/2026-01/graphql.json

Authentication: X-Shopify-Storefront-Access-Token: {public_token} (safe for client-side; cannot access admin or customer PII).

Key operations:

Query products (public):

query GetProducts($first: Int!) {
  products(first: $first) {
    edges {
      node {
        id title handle description
        priceRange { minVariantPrice { amount currencyCode } }
        images(first: 3) { edges { node { url altText } } }
        variants(first: 10) { edges { node { id title price { amount } availableForSale } } }
      }
    }
  }
}

Cart create + add-to-cart mutations are supported via cartCreate / cartLinesAdd. The Ajax API (/cart/add.js, /cart/change.js) is the simpler alternative for standard Liquid themes.

Full reference: references/api-storefront.md