{"count":28,"docs":[{"slug":"blog/dry-run-preview","title":"Dry-run: preview every agent action before it happens","tags":["blog","feature","safety"],"body":"\n# Dry-run: preview every agent action before it happens\n\nEvery write tool in Shopigent accepts `dry_run: true`. When set, the tool validates the input, resolves all references (products, variants, customers), and returns **the exact mutation it would execute** — without executing it.\n\n## Why it matters\n\nAgents are great at intent, imperfect at details. Dry-run catches the gap:\n\n```json\n{\n  \"tool\": \"discounts_create\",\n  \"dry_run\": true,\n  \"input\": { \"title\": \"WEEKEND20\", \"value\": \"20%\", \"applies_to\": \"collection:hoodies\" }\n}\n```\n\nThe response shows the resolved discount — which collection ID matched, start/end dates, usage limits — so the agent (or you) can verify before committing.\n\n## Dry-run + confirmation gate\n\nThe two features stack:\n\n1. Agent calls the tool with `dry_run: true` → sees the preview.\n2. Agent calls it for real → Shopigent pauses at the **confirmation gate**.\n3. You approve in the dashboard → the mutation runs and lands in the **audit log**.\n\nThree checkpoints between \"the agent had an idea\" and \"your store changed\". That's how it should be.\n"},{"slug":"blog/feature-read-tools-content","title":"Manage collections, blogs, articles, and pages — now with read tools","tags":["blog","feature","content","collections"],"body":"\n# Manage collections, blogs, articles, and pages — now with read tools\n\nShopigent has always supported **write tools** for collections, blogs, articles, and pages (create, update, delete). What was missing was the ability to *explore* them first — to list what exists, inspect a specific item, and decide what to act on.\n\nNow every content category has both **read and write** tools.\n\n## New read tools\n\n### Collections (5 tools)\n\nCollections organize your products. The new read tools let you browse and inspect them:\n\n```\nList all my collections and show me which ones have\nthe most products.\n```\n\n```\nGet the \"Winter Sale\" collection — I need to see\nits current products and description.\n```\n\n| Tool | What it does |\n|------|-------------|\n| `list_collections` | Lists all collections (manual + automated) with id, title, handle, sort order |\n| `get_collection_by_id` | Fetches a single collection by GID, including description, image, product count |\n\n### Blogs (5 tools)\n\nBlogs hold your articles. Read tools let you discover them:\n\n```\nList all my blogs and show me which ones have the\nmost recent articles.\n```\n\n| Tool | What it does |\n|------|-------------|\n| `list_blogs` | Lists all blogs with id, title, handle, comment policy |\n| `get_blog_by_id` | Fetches a single blog by GID, including its articles and metadata |\n\n### Articles (5 tools)\n\nArticles are individual blog posts. Now you can read them:\n\n```\nList all articles in the \"News\" blog, ordered by date.\n```\n\n```\nGet the article about the summer sale — I need to\ncheck its publish date.\n```\n\n| Tool | What it does |\n|------|-------------|\n| `list_articles` | Lists all blog articles for a blog, with optional filters |\n| `get_article_by_id` | Fetches a single article by GID, including body, summary, tags, author |\n\n### Pages (5 tools)\n\nPages are static content (About, Contact, etc.):\n\n```\nList all my pages and tell me which ones are unpublished.\n```\n\n```\nGet the \"About Us\" page and show me its current content.\n```\n\n| Tool | What it does |\n|------|-------------|\n| `list_pages` | Lists all pages with id, title, handle, and status |\n| `get_page_by_id` | Fetches a single page by GID, including body and SEO metadata |\n\n## Why this matters\n\nBefore these read tools, an agent could only *write* content — but couldn't discover what exists. The workflow was:\n\n**Before:** \"Delete the About page\" → \"I don't know which page that is.\"\n**After:** \"List my pages. Find 'About'. Delete it.\"\n\nIt's a small change that makes the agent dramatically more useful — especially for repetitive tasks like auditing content, cleaning up old blogs, or restructuring collections.\n\n## Full category breakdown\n\nThe tools are now organized into **10 categories**:\n\n| Category | Tools |\n|----------|-------|\n| Products | 28 |\n| Content | 16 |\n| Metaobjects & Custom Data | 15 |\n| Themes | 9 |\n| GitHub Theme | 4 |\n| Orders | 6 |\n| Customers | 5 |\n| Discounts | 4 |\n| Fulfillments | 4 |\n| Inventory | 1 |\n\n**Total: 92 tools** — every category has both read and write capabilities."},{"slug":"blog/feature-search-products","title":"Find any product instantly with full-text search","tags":["blog","feature","products"],"body":"\n# Find any product instantly with full-text search\n\nShopigent's `search_products` tool gives your AI agent the ability to search across your entire product catalog by keyword — just like the Shopify admin search, but accessible from any MCP client.\n\n## What it is\n\n`search_products` is a new read tool that performs full-text search across product titles, descriptions, and tags. It returns matching products with relevance scores, so the most relevant results appear first.\n\n```\nSearch my store for \"wool beanie\" — show me the top 5 matches.\n```\n\n## Why it's different from list_products\n\n`list_products` returns products with optional filters (status, collection, etc.). `search_products` is built for *discovery* — when you don't know exactly what you're looking for but have a keyword in mind.\n\n| Tool | Best for |\n|------|----------|\n| `list_products` | Browsing a category, paginated listing, status filters |\n| `search_products` | Keyword search, finding a specific product by name or description |\n\n## Example prompts\n\n### Find products by material\n\n```\nSearch for products containing \"organic cotton\" in their description.\nList the top 3 with their prices and inventory.\n```\n\n### Find products by tag or keyword\n\n```\nSearch for \"clearance\" across all product names and tags.\nShow me how many are still in stock.\n```\n\n### Product research\n\n```\nSearch for \"running\" in my store and tell me which products\nneed better meta descriptions based on their search ranking.\n```\n\n### Compare with list_products\n\n```\nSearch for \"winter\" products. Then for each result, check\nif the inventory is below 10 and add it to a restock list.\n```\n\n## How it works with the tool grid\n\n`search_products` is part of the **Products** category (15 tools). Enable it in Curated Tools alongside `list_products`, `get_product_by_id`, and the product write tools.\n\nAvailable on all plans (Free, Growth, Pro)."},{"slug":"blog/shopigent-vs-raw-api-key","title":"Shopigent vs a raw Admin API key: why curated tools win","tags":["blog","comparison","security"],"body":"\n# Shopigent vs a raw Admin API key\n\nTechnically, you don't need Shopigent to connect an LLM to Shopify. You can create a custom app, grab an Admin API token, and hand it to your agent. Merchants ask us why they shouldn't. Fair question — here's the honest comparison.\n\n## What a raw token gives you\n\n- **Everything, forever.** Whatever scopes the token has, the agent has — 24/7, no questions asked.\n- **No record.** Shopify logs API calls internally, but *you* have no readable trail of what your agent did or why.\n- **No brakes.** A hallucinated ID in a `productDelete` mutation executes just as happily as a correct one.\n- **Raw GraphQL complexity.** The agent burns tokens (and makes mistakes) constructing mutations, cursors, and error handling from scratch.\n\n## What curated tools change\n\n| | Raw Admin token | Shopigent |\n|---|---|---|\n| Access control | All-or-nothing scopes | Per-category toggles, per-key |\n| Destructive actions | Execute immediately | Pause at the confirmation gate |\n| Visibility | None | Full audit log (input, result, latency) |\n| Agent ergonomics | Raw GraphQL | 51 validated, documented tools |\n| Failure mode | Silent damage | Rejected input or pending approval |\n| Revocation | Rotate token, redeploy | Revoke key in one click |\n\n## The deeper point\n\nAgents don't fail like humans. They fail *confidently*, at machine speed, in bulk. The right response isn't \"never connect an agent\" — it's **structure the access so mistakes are cheap**. Validated inputs catch most errors; the confirmation gate catches the rest; the audit log tells you what happened either way.\n\nThat's the entire product, honestly. Fewer capabilities exposed, more safely, with receipts.\n\n*Try it free — read-only access needs zero trust.*\n"},{"slug":"blog/use-case-bulk-edit","title":"Use case: bulk editing products from a spreadsheet","tags":["blog","use-case","products"],"body":"\n# Use case: bulk editing products from a spreadsheet\n\nShopify's bulk editor is powerful but limited to what it shows in the grid. With Shopigent + an MCP agent, you can update any field on any product — based on a spreadsheet you already have.\n\n## The workflow\n\n**Step 1:** Export a CSV from Shopify (or prepare one in Google Sheets).\n\n**Step 2:** Feed it to your agent with clear instructions.\n\n**Step 3:** The agent reads each row, matches the product in Shopify, and applies the change — always with dry-run first.\n\n## Example: price update from a CSV\n\n```\nI have a file called prices.csv with columns: SKU, new_price.\n\nFor each row, find the matching product in Shopify by SKU. \nDry-run updating the price to new_price. Report back any SKUs \nthat don't match before you execute.\n```\n\n## Example: bulk tag addition\n\n```\nAdd the tag \"winter-2026\" to every product in the \"Winter Collection\" \ncollection. Show me how many products will be affected, then dry-run\nbefore executing.\n```\n\n## Example: SEO meta update\n\n```\nRead meta-descriptions.csv (columns: title, new_meta). For each row, \nfind the product by title and update its seo.description to new_meta. \nSkip any products that already have the same meta.\n```\n\n## Example: multi-lingual translation\n\n```\nExport all products. For products where the Spanish description \nis missing, translate the English description using the product's \ntags as context. Dry-run the first 5 translations for review.\n```\n\n## Tips for spreadsheet operations\n\n### Always use SKU or GID\nProduct titles change. Use the **SKU** or the Shopify **GID** (`gid://shopify/Product/123`) to match rows reliably.\n\n### Dry-run first\nAdd `dryRun: true` to every bulk update. The agent will preview every mutation without touching your store.\n\n### Batch by category\nSplit large spreadsheets into batches (e.g. 20 products at a time) to review before committing.\n\n```\nProcess the first 20 rows and stop for review. If the output \nlooks right, I'll tell you to continue with the next 20.\n```\n\n### Use filters to narrow scope\n\n```\nList products in \"Electronics\" with inventory > 10. Export their \nSKUs and current prices, then reduce each price by 15%.\n```\n\nThis avoids updating products that shouldn't change.\n\n## Why this works\n\nShopigent's `update_product` tool supports every field: title, description, price, compareAtPrice, tags, status, SEO, metafields, and more. Combined with `dryRun`, you get the power of a full API client without writing a single GraphQL query."},{"slug":"blog/use-case-bulk-seo","title":"Use case: bulk-editing product SEO with an agent","tags":["blog","use-case","products"],"body":"\n# Use case: bulk-editing product SEO with an agent\n\nProduct SEO is the most common \"should do, never does\" task. There are hundreds of products and writing unique descriptions by hand is brutal. An agent changes the math.\n\n## The prompt\n\n```\nFor products missing a meta description, write a 150-character meta description\nand a compelling product description using the title and vendor. Don't change\nprices or anything else. Show me a preview first.\n```\n\n## How it stays safe\n\n- The agent uses `products_list` (read) to find gaps — no writes yet.\n- For each product it drafts text, then calls `products_update` with `dry_run: true` so you see the before/after.\n- Only when you approve does the change go live. And you can scope it: \"only the apparel collection\" so nothing else moves.\n\n## Why not a bulk editor app?\n\nBulk editors are fast but dumb — they apply a template. An agent *understands* the product and writes per-item copy. Combined with the confirmation gate, you get bespoke quality with the safety of a bulk tool.\n\n> Tip: start read-only on the Free plan. Use the audit log to see exactly what the agent proposed, then upgrade to Growth and approve in one pass.\n"},{"slug":"blog/use-case-customer-support","title":"Use case: answering customer emails with an agent","tags":["blog","use-case","customers"],"body":"\n# Use case: answering customer emails with an agent\n\nSupport emails pile up fast — \"Where's my order?\", \"Can I change my address?\", \"Do you have this in a different size?\" — and every answer means digging through the Shopify admin.\n\nWith Shopigent, your AI agent reads the store data and drafts replies in seconds.\n\n## The workflow\n\n**Step 1:** A customer emails you.\n\n**Step 2:** Your agent searches for the customer and their orders in Shopify — without you leaving your email client or chat.\n\n```\nFind customer by email \"maria@example.com\" and show their \nlast 3 orders with status and fulfillment info.\n```\n\n**Step 3:** The agent drafts a reply based on live data.\n\n**Step 4:** If the reply involves a store change (refund, address update), the agent prepares it for your approval via the confirmation gate.\n\n## Example prompts\n\n### Check an order status\n\n```\nA customer named \"Elena\" emailed asking about order #1234. \nFind the order status, tracking number, and estimated delivery.\n```\n\n### Update a shipping address\n\n```\nCustomer \"Carlos\" needs his shipping address changed on order #5678 — \nhe moved to 42 New Street, Berlin. Dry-run the update first.\n```\n\n### Process a simple refund\n\n```\nOrder #9012 was returned. Refund the full amount to the original \npayment method. Use dryRun first to preview the refund mutation.\n```\n\n### Draft a support reply\n\n```\nLook up customer \"Sofia\" — her email is sofia@example.com. She has 14 \norders and her last one (#3456) shows \"delivered\" but she says it hasn't \narrived. What's the tracking status? Draft a reply offering options.\n```\n\n## Why this works\n\nShopigent's tools cover everything support needs:\n- **`get_customer`** → fetch contact details, tags, notes\n- **`list_orders`** → find recent orders by customer\n- **`get_order`** → check status, fulfillment, tracking\n- **`update_customer`** → change address, add tags\n- **`refund_order`** → process returns (with confirmation gate)\n\nAnd the audit log means every action is recorded — useful for tracking which tickets were handled through the agent."},{"slug":"blog/use-case-inventory-sync","title":"Use case: inventory sync after a stocktake","tags":["blog","use-case","inventory"],"body":"\n# Use case: inventory sync after a stocktake\n\nAfter a physical count, you often need to reconcile Shopify stock with what's on the shelves. Doing it by hand in the admin is slow and error-prone. Here's the agent-assisted version.\n\n## The prompt\n\n```\nFrom the attached stock count (SKU → quantity), adjust each variant's available\ninventory to match. Use inventory_adjust with dry_run first and report what will change.\n```\n\n## What happens\n\n1. The agent matches each SKU to a variant via `inventory_levels_list` (read) — catching typos before anything changes.\n2. For each mismatch it calls `inventory_adjust` with `dry_run: true`, returning a clear summary: \"SKU AB-123: 14 → 9\".\n3. You review the summary in the confirmation card and approve. No mismatched number slips through because the preview shows every delta.\n\n## The audit trail\n\nEvery adjustment — input, result, timestamp — lands in the audit log. So if a number looks wrong next month, you can see exactly when it was set and by which agent session.\n\n> Particularly useful for stores with multiple locations: the agent can target a specific location per SKU without you hunting through dropdown menus.\n"},{"slug":"blog/use-case-weekend-sale","title":"Use case: set up a weekend sale in two minutes","tags":["blog","use-case","discounts"],"body":"\n# Use case: set up a weekend sale in two minutes\n\nThe workflow merchants automate first is almost always discounts. It's fiddly in the admin (collection, value, dates, limits, code) and it's exactly the kind of structured task agents nail. Here's the full flow with Shopigent.\n\n## The prompt\n\nIn Claude, Cursor, or Hermes:\n\n```\nCreate a 20% discount code WEEKEND20 for the Hoodies collection,\nvalid Friday 00:00 to Sunday 23:59, one use per customer.\n```\n\n## What the agent does\n\n1. `products_list` / collections lookup — resolves \"Hoodies\" to the real collection ID.\n2. `discounts_create` with `dry_run: true` — previews the exact discount object.\n3. `discounts_create` for real — and here it **stops**.\n\n## What you do\n\nYour Shopigent dashboard shows a confirmation card:\n\n> **discounts_create** — WEEKEND20 · 20% off · collection: Hoodies (14 products) · Fri 00:00 → Sun 23:59 · 1/customer\n\nOne tap to approve. The discount goes live, the action lands in the audit log, and the agent confirms back in chat.\n\n## Variations that work just as well\n\n- \"Extend WEEKEND20 until Monday night\" → `discounts_update`\n- \"How did WEEKEND20 perform?\" → `orders_list` filtered by discount code\n- \"Kill the sale now\" → `discounts_delete` (confirmation again — deletes are always gated)\n\n## Why this beats doing it by hand\n\nNot because clicking is hard — because **the agent gets the details right** (IDs, dates, limits) and the gate means you review *one summary card* instead of five admin screens. Two minutes, fully audited.\n"},{"slug":"blog/why-ai-agents-for-shopify","title":"Why your Shopify store needs an AI agent (and how to stay in control)","tags":["blog","ai-agents","mcp"],"body":"\n# Why your Shopify store needs an AI agent (and how to stay in control)\n\nAI agents are past the demo phase. They can genuinely run store operations: updating product copy, building discounts, answering \"what were my top sellers last month\", adjusting inventory after a stocktake. The blocker was never intelligence — it was **safe access**.\n\n## The problem with raw API access\n\nGive an agent your Admin API key and you've given it everything, forever, with no record. One hallucinated `DELETE` and your catalog is gone. That's why most merchants (rightly) never connect an LLM to their store.\n\n## Scoped tools + human gate\n\nShopigent takes a different route:\n\n1. **You pick the categories** an agent can touch — Products yes, Orders no, for example.\n2. **Reads are free, writes are gated.** Any create/edit/delete/refund pauses and asks *you* to approve it in the dashboard.\n3. **Everything is logged.** Every call, its input, its result, its latency.\n\n> The agent proposes; you approve. That's the entire trust model, and it works.\n\n## What merchants actually automate first\n\nFrom what we see, the first wins are boring and valuable:\n\n- Bulk product copy cleanup and SEO descriptions\n- Seasonal discount setup (\"20% off everything in Collection X this weekend\")\n- Answering ops questions without opening five admin tabs\n- Tagging and segmenting customers after imports\n\nStart read-only on the Free plan, watch the audit log for a week, then enable writes for the categories you trust. Control first, speed second — and you end up with both.\n"},{"slug":"changelog","title":"Changelog","tags":["changelog"],"body":"\n# Changelog\n\n## 2026-09-03\n- **New: GitHub Theme category (4 tools)** — connect your store's theme to a GitHub repo and work Git-first. `github_theme_connection`, `github_list_theme_branches`, `github_theme_file` (read), and `github_create_theme_pr` (opens a PR; deploy handled by GitHub Actions, no auto-publish). Enabled from the GitHub Theme page in the dashboard.\n\n## 2026-09-03 (earlier)\n- **fix(object-arg payloads)** — object-payload tools (`create/update_metafield_definition`, `create/update_metaobject_definition`, `create/update_metaobject`) now send the full payload to Shopify (previously sent `{}` due to Zod STRIP-mode). (PR #5)\n- **fix(scopes)** — the **Metaobjects & Custom Data** category now shows \"Granted\" after reauthorize (added to scope-granted sync). (PR #6)\n- **fix(MCP metafield-read + HTTP)**:\n  - `list_product_metafield_definitions` & `get_metafield_definition` — correct nested `type { name }` selections (previously GraphQL error).\n  - `get_metafield_definition` accepts only `id` (no longer sends ownerType).\n  - HTTP JSON body limit raised **100KB → 50MB** — media uploads (`upload_product_media`) with large base64 now work (previously HTTP 413). Plus structured JSON errors instead of HTML. (PR #7)\n- **UI polish** — uniform scopes badges + aligned; dashboard quick-stats in one row; responsive mobile pages; tool cards with clear Enable/confirmation.\n\n## 2026-09-03 (earlier)\n- **88 curated tools across 9 categories** — up from 69. New **Metaobjects & Custom Data** category (15 tools).\n- **Product media (SH-002, SH-007)** — new `upload_product_media` (staged-upload), `get_product_media`, and `get_product_publications`.\n- **Custom Data (SH-003)** — 15 metaobject & metafield-definition tools. Requires a dedicated **Custom Data** scope category; many are destructive and require confirmation.\n- **Template suffix (SH-004)** — `update_product` now supports `templateSuffix` / `clearTemplateSuffix`.\n- **Customers** — `create_customer` added (Customers now 5 tools).\n- **API version 2026-07**, new `read_publications` scope + `metaobjects` scopes.\n\n## 2026-09-02\n- **69 curated tools** — up from 68. Added `upload_theme_asset` for uploading arbitrary files (images, Liquid, CSS, JS) to themes.\n- **Theme asset upload** — `upload_theme_asset` (Pro) uploads any file to a theme. Supports PNG, JPG, SVG, Liquid, JSON, CSS, JS via BASE64 or text payload.\n\n## 2026-09-01\n- **60 tools across 9 categories** — up from 51/8. Added read tools for collections, blogs, articles, and pages. New dedicated Collections and Translations categories. Inventory merged into Products.\n- **`search_products`** — new full-text search tool that finds products by keyword across titles, descriptions, and tags with relevance scoring.\n- **Content read tools** — `list_pages`, `get_page_by_id`, `list_blogs`, `get_blog_by_id`, `list_articles`, `get_article_by_id` make every content category fully readable.\n- **Collection read tools** — `list_collections`, `get_collection_by_id` let you browse collections before writing.\n- **Hero terminal slider** — homepage demo now cycles through 5 interactive prompt examples with prev/next controls and clickable dots.\n\n## 2026-07-20\n- **Connect guides** — added setup guides for Claude, Cursor, and Hermes agents.\n- **Plans & Billing doc** — clarified plan limits and upgrade flow.\n\n## 2026-07-12\n- **Security & Trust doc** — published our access model, key handling, and data practices.\n- **Scopes reference** — mapped every tool category to its Shopify OAuth scopes.\n\n## 2026-06-30\n- **Confirmation gate** ships to all paid plans — every destructive action requires an in-dashboard approval.\n- **Audit log** — records tool name, input, result, and latency for every call.\n\n## 2026-06-15\n- **Dry-run preview** — every write tool supports `dry_run: true` to preview the exact mutation before executing.\n\n## 2026-05-01\n- **Public launch** — Shopigent on the Shopify App Store with 51 curated tools across 8 categories and scope-based access control.\n"},{"slug":"guides/connect-chatgpt","title":"Connect ChatGPT to your store","tags":["guide","chatgpt","mcp","openai"],"body":"\n# Connect ChatGPT to your store\n\nChatGPT (GPT-4o and newer) supports MCP servers natively through **ChatGPT MCP** — giving you a conversational interface to your store data.\n\n> **Prerequisite:** You've installed Shopigent and issued an MCP API key. See [Getting Started](/guides/getting-started).\n\n## 1. Configure the MCP server\n\nOpen **ChatGPT Settings → MCP Servers → Add** and paste:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopigent\": {\n      \"url\": \"https://mcp.shopigent.greeknous.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nYou can also configure it via `~/.chatgpt/mcp.json` if you use ChatGPT Desktop.\n\n## 2. Ask your first query\n\n```\nShow me my top 10 products by revenue this month.\n```\n\nChatGPT uses `orders_list` and `products_list` through MCP and answers with live numbers.\n\n## 3. Go further with prompts\n\n```\nI want to create a discount for customers who spent over €200 last year.\nFirst find those customers, then suggest a discount structure.\n```\n\n```\nMy \"Trail Beanie\" has inventory 34 units. Check the last 90 days of sales \nfor that product and tell me if 34 units is enough or if I should reorder.\n```\n\n## 4. Combine with ChatGPT plugins\n\nPair Shopigent with ChatGPT's data analysis (code interpreter) to export store data and build reports — all from the same chat.\n\n## Troubleshooting\n\n- **MCP not showing** — ensure ChatGPT Desktop is updated to a version that supports MCP (GPT-4o, 2025+ releases).\n- **Key rejected** — the key is one-time. Generate a fresh one from the Shopigent dashboard.\n- **Scope denied** — the category you're querying isn't enabled in Curated Tools."},{"slug":"guides/connect-claude","title":"Connect Claude to your store","tags":["guide","claude","mcp"],"body":"\n# Connect Claude to your store\n\nThis guide shows how to connect Claude (Desktop or Code) to Shopigent's MCP endpoint.\n\n> **Prerequisite:** You've installed Shopigent and issued an MCP API key from the dashboard. See [Getting Started](/guides/getting-started).\n\n## 1. Add the MCP server\n\nAdd Shopigent to your Claude MCP configuration (`claude_desktop_config.json` or `~/.claude/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"shopigent\": {\n      \"url\": \"https://mcp.shopigent.greeknous.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n## 2. Verify the connection\n\nAsk Claude something read-only first:\n\n```\nList my 5 most recent orders with customer name and total.\n```\n\nClaude should call `orders_list` and return real data from your store.\n\n## 3. Example prompts for Claude\n\n### Explore your store\n\n```\nDescribe my store: how many products, customers, orders, and active discounts? \nUse the appropriate tools one at a time.\n```\n\n```\nShow me a dashboard: my top 3 products by revenue this month, my 3 lowest-stock \nitems, and how many pending orders I have — all in one response.\n```\n\n### Merchandising\n\n```\nFind 5 products with no meta description. For each one, draft a compelling \nmeta description based on its title and tags. Show me the drafts, then \nupdate them if I approve.\n```\n\n```\nWhich products in my store are tagged \"clearance\" but still at full price? \nList them with options to mark them down.\n```\n\n### Customer insights\n\n```\nWho are my top 5 customers by total spend? Show name, email, order count, \nand total spent. Don't change anything — just report.\n```\n\n```\nI want to send a birthday promo. List customers with birthdays this month, \ntheir email, and their favourite product category based on purchase history.\n```\n\n## 4. Try a write action (Growth/Pro)\n\n```\nCreate a 10% discount code SUMMER10 valid until end of month for all products.\n```\n\nShopigent will show a **confirmation prompt** in the app before the discount is created. Approve it, and check the audit log.\n\n### Bulk operations (always dry-run first)\n\n```\nDry-run: set the price of all products tagged \"sale\" to 20% off their current \nprice. Show me the before/after for 3 examples before executing.\n```\n\n## Troubleshooting\n\n- **401 Unauthorized** — the API key is wrong or was revoked. Issue a new one from the dashboard.\n- **Tool not available** — the category (e.g. Discounts) is disabled in your Curated Tools settings, or your plan doesn't include write access.\n- **Action blocked** — a pending confirmation is waiting in the Shopigent app."},{"slug":"guides/connect-claude-code","title":"Connect Claude Code to your store","tags":["guide","claude-code","claude","mcp"],"body":"\n# Connect Claude Code to your store\n\n[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) is Anthropic's terminal-based agent. Combined with Shopigent, you can execute store operations — reads, writes, bulk edits — from the same terminal where you code.\n\n> **Prerequisite:** You've installed Shopigent and issued an MCP API key. See [Getting Started](/guides/getting-started).\n\n## 1. Start Claude Code with the MCP config\n\nCreate `~/.claude/shopigent.json`:\n\n```json\n{\n  \"shopigent\": {\n    \"url\": \"https://mcp.shopigent.greeknous.com/mcp\",\n    \"headers\": {\n      \"Authorization\": \"Bearer YOUR_API_KEY\"\n    }\n  }\n}\n```\n\nThen start Claude Code:\n\n```bash\nclaude --mcp ~/.claude/shopigent.json\n```\n\nOr add Shopigent to your project's `.claude/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopigent\": {\n      \"url\": \"https://mcp.shopigent.greeknous.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n## 2. Terminal-native prompts\n\nClaude Code shines at batch operations. Try these:\n\n```\nRead store-data/products.json, then for every product in that file that \nis out of stock, update its status to DRAFT using shopigent.\n```\n\n```\nList all discounts that expire this week. For each one, calculate the \ntotal revenue it generated and create a report.\n```\n\n## 3. Developer workflows\n\n```\nI'm building a new landing page. Fetch my current theme settings and \nlist the snippets I'd need to modify.\n```\n\n```\nPull the last 50 orders and check if any need fulfillment \n(fulfillment status = null). Return them as a JSON array.\n```\n\n## 4. Script it\n\nBecause Claude Code runs in the terminal, you can pipe results into scripts:\n\n```bash\nclaude --mcp shopigent \"List all products with inventory < 5\" | \\\n  jq '.products[].title' | xargs -I{} echo \"Reorder: {}\"\n```\n\n## Troubleshooting\n\n- **CLI not found** — install Claude Code: `npm install -g @anthropic-ai/claude-code`\n- **Connection error** — verify the MCP URL and key. Keys from the dashboard work for 24 hours.\n- **Batch too large** — use `dryRun: true` to preview mutations before running them in bulk."},{"slug":"guides/connect-codex","title":"Connect Codex CLI to your store","tags":["guide","codex","mcp","openai"],"body":"\n# Connect Codex CLI to your store\n\n[OpenAI Codex CLI](https://codex.openai.com) is an agentic terminal that combines Claude/ChatGPT-like reasoning with a live shell. Add Shopigent's MCP tools and your store becomes accessible from any terminal session.\n\n> **Prerequisite:** You've installed Shopigent and issued an MCP API key. See [Getting Started](/guides/getting-started).\n\n## 1. Configure Codex CLI\n\nCodex reads MCP servers from `~/.codex/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopigent\": {\n      \"url\": \"https://mcp.shopigent.greeknous.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nStart Codex:\n\n```bash\ncodex\n```\n\n## 2. Prompts for Codex\n\nCodex is built for engineering workflows. Try:\n\n```\nUse shopigent to export all my product titles, prices, and inventory \ncounts to a CSV file called inventory-export.csv.\n```\n\n```\nFind every product whose description mentions \"cotton\" and replace \nit with \"organic cotton\". Preview with dryRun first.\n```\n\n## 3. Bulk operations\n\n```\nRun a dry-run discount: create a 15% off code called FALL15 for all \nproducts in the \"Fall Collection\" collection. If it looks right, \nconfirm it.\n```\n\n```\nList products where compareAtPrice < price (sale is inverted). \nFix each one.\n```\n\n## Troubleshooting\n\n- **Config not found** — ensure `~/.codex/mcp.json` has valid JSON.\n- **Tool calls return 401** — the key expired. Generate a new one.\n- **Rate-limited** — Free plan: 25 calls/day. Upgrade to Growth or Pro for higher limits."},{"slug":"guides/connect-continue","title":"Connect Continue.dev to your store","tags":["guide","continue","mcp","vscode"],"body":"\n# Connect Continue.dev to your store\n\n[Continue.dev](https://continue.dev) is an open-source AI code assistant that runs in VS Code and JetBrains. It supports MCP servers, so you can add Shopigent and manage your store without leaving the editor.\n\n> **Prerequisite:** You've installed Shopigent and issued an MCP API key. See [Getting Started](/guides/getting-started).\n\n## 1. Add Shopigent to Continue\n\nEdit `~/.continue/config.json`:\n\n```json\n{\n  \"experimental\": {\n    \"mcpServers\": {\n      \"shopigent\": {\n        \"url\": \"https://mcp.shopigent.greeknous.com/mcp\",\n        \"headers\": {\n          \"Authorization\": \"Bearer YOUR_API_KEY\"\n        }\n      }\n    }\n  }\n}\n```\n\nRestart VS Code (or reload the Continue extension).\n\n## 2. Ask from your editor\n\nOpen Continue's chat panel (Ctrl+Shift+R / Cmd+Shift+R) and try:\n\n```\nUsing shopigent, what are my 3 best-selling products this month?\n```\n\n```\nCheck the inventory of product \"Approach Under Glove\" and tell me \nif I need to reorder.\n```\n\n## 3. Code + store data\n\nContinue's strength is combining code context with external data:\n\n```\nI'm building a product card component. Fetch 3 real products from \nmy store with shopigent, and show me the shape of the data I need.\n```\n\n```\nI need to add a \"Low Stock\" badge. Query my inventory and tell me \nwhich products have fewer than 10 units — I'll handle the front-end.\n```\n\n## Troubleshooting\n\n- **Tools not available** — ensure Continue version supports MCP (≥ v0.9.0).\n- **Key invalid** — regenerate from the Shopigent dashboard.\n- **Read-only** — Free plan limits to read-only tools. Upgrade for writes."},{"slug":"guides/connect-cursor","title":"Connect Cursor to your store","tags":["guide","cursor","mcp"],"body":"\n# Connect Cursor to your store\n\nCursor supports MCP servers natively, which means your editor's AI can read and manage your Shopify store through Shopigent while you code.\n\n> **Prerequisite:** You've installed Shopigent and issued an MCP API key from the dashboard. See [Getting Started](/guides/getting-started).\n\n## 1. Add the MCP server\n\nOpen **Cursor Settings → MCP → Add new MCP server**, or edit `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopigent\": {\n      \"url\": \"https://mcp.shopigent.greeknous.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor. The Shopigent tools appear in the MCP tools list.\n\n## 2. Verify\n\nIn a Cursor chat, ask:\n\n```\nUsing shopigent, list my products that are out of stock.\n```\n\n## 3. Prompts for Cursor developers\n\n### Development + store data\n\n```\nI'm building a product grid component. Use shopigent to fetch 6 real products \nfrom my store so I can preview how the grid renders with actual data.\n```\n\n```\nI need to test the checkout flow. Use shopigent to create a 1€ test product \nfor me, then delete it after I've finished testing.\n```\n\n### Bulk edits from code\n\n```\nRead the file ./products-to-update.json. For each SKU in the file, find \nthe matching product in Shopify and update its price to the new_price \nfrom the JSON. Use dryRun first.\n```\n\n### Theme development\n\n```\nFetch my current theme assets. I need to find where the header logo \nis rendered so I can change its size.\n```\n\n```\nI just updated my Liquid template. Use shopigent to create a draft of \nthe changed theme, then publish it if it renders correctly.\n```\n\n## Ideas for developer workflows\n\n- Generate SEO descriptions in your editor and push them straight to products.\n- Pull real product data while building a storefront, instead of mocking it.\n- Update theme content (Pro plan) while iterating on Liquid locally.\n- Use Cursor's `Cmd+K` to ask: \"Add a 10% student discount using shopigent\" — it calls the tools inline.\n\n## Troubleshooting\n\n- **Tools don't appear** — check the JSON syntax and restart Cursor completely.\n- **401 Unauthorized** — regenerate the API key in the Shopigent dashboard.\n- **Writes rejected** — your plan is read-only (Free) or the category is disabled."},{"slug":"guides/connect-hermes","title":"Connect Hermes Agent to your store","tags":["guide","hermes","mcp"],"body":"\n# Connect Hermes Agent to your store\n\nHermes Agent can operate your store conversationally — from Discord, Telegram, or the desktop app — through Shopigent's MCP endpoint.\n\n> **Prerequisite:** You've installed Shopigent and issued an MCP API key. See [Getting Started](/guides/getting-started).\n\n## 1. Add the MCP server to Hermes\n\n```bash\nhermes mcp add shopigent https://mcp.shopigent.greeknous.com/mcp \\\n  --header \"Authorization: Bearer ***\"\n```\n\nOr add it to your Hermes `config.yaml`:\n\n```yaml\nmcp:\n  servers:\n    shopigent:\n      url: https://mcp.shopigent.greeknous.com/mcp\n      headers:\n        Authorization: \"Bearer YOUR_API_KEY\"\n```\n\n## 2. Talk to your store\n\nFrom any connected chat:\n\n```\nΠόσες παραγγελίες είχαμε σήμερα; Ποια προϊόντα πούλησαν περισσότερο;\n```\n\nHermes calls `orders_list` / `products_list` and answers with live data — in any language.\n\n## 3. Prompts for any language\n\n### Greek\n\n```\nΒρες τα προϊόντα που έχουν απόθεμα κάτω από 5 τεμάχια και φτιάξε \nμια λίστα για παραγγελία.\n```\n\n```\nΠόσα προϊόντα πωλήθηκαν αυτή την εβδομάδα; Σύγκρινε με την προηγούμενη.\n```\n\n### English\n\n```\nShow me all orders from last week grouped by day. Which day had the most revenue?\n```\n\n```\nCreate a discount called SPRING25 for 25% off on all products in the \n\"Spring Collection\" collection, valid for 7 days. Dry-run first.\n```\n\n## 4. Autonomous routines\n\nBecause Hermes supports scheduled jobs, you can combine it with Shopigent for recurring ops:\n\n- Daily sales summary delivered to Discord every morning\n- Low-stock alerts checked hourly\n- Weekly draft of a promo discount, waiting for your approval via the confirmation gate\n\nThe confirmation gate is key: an autonomous agent can *prepare* destructive actions around the clock, but nothing executes until you approve.\n\n## Troubleshooting\n\n- **Connection fails** — verify the URL and that the key hasn't been revoked.\n- **Tool missing** — the category is toggled off in Curated Tools, or your plan doesn't include it.\n- **Scheduled job fails** — check Hermes' cron logs; the API key may have expired."},{"slug":"guides/getting-started","title":"Getting Started with Shopigent","tags":["guide","getting-started"],"body":"\n# Getting Started with Shopigent\n\nThis guide walks you through connecting an AI agent to your Shopify store with Shopigent.\n\n## 1. Install\nInstall Shopigent from the [Shopify App Store](https://apps.shopify.com/shopigent) and grant the scopes your store needs.\n\n## 2. Enable tool categories\nOpen the **Curated Tools** dashboard in the app. Each category (Products, Orders, Customers, etc.) has a toggle — enable only what you want your agent to access.\n\n## 3. Issue an MCP API key\nFrom the dashboard, generate an MCP API key. The plaintext key is shown once — store it securely. Shopigent stores only a hash.\n\n## 4. Connect your AI agent\n\nNow that you have an API key, choose your tool and follow the dedicated guide:\n\n- **[Claude Desktop](/guides/connect-claude)** — Anthropic's standalone app\n- **[Claude Code](/guides/connect-claude-code)** — Claude in your terminal\n- **[Cursor](/guides/connect-cursor)** — AI-native code editor\n- **[Hermes Agent](/guides/connect-hermes)** — Autonomous agent (Discord, Telegram)\n- **[ChatGPT](/guides/connect-chatgpt)** — OpenAI's MCP-capable chat\n- **[Codex CLI](/guides/connect-codex)** — OpenAI's terminal agent\n- **[Continue.dev](/guides/connect-continue)** — VS Code extension\n\nOr read the **[Prompts & Best Practices](/guides/prompts-best-practices)** guide for tips and examples.\n\n## 5. Confirmation gate\n\nAny destructive action (create, edit, delete, refund) triggers a confirmation prompt. Approve it to proceed. Every action is recorded in the audit log.\n\n## Next steps\n\n- Browse all [curated tools](/reference/tools) with descriptions\n- See [scopes & permissions](/reference/scopes-and-permissions) to enable only what your agent needs\n- Compare [plans and pricing](/guides/plans-and-billing)\n- Read the [Prompts & Best Practices](/guides/prompts-best-practices) guide\n"},{"slug":"guides/plans-and-billing","title":"Plans & Billing","tags":["guide","plans","billing"],"body":"\n# Plans & Billing\n\nShopigent bills through the [Shopify App Store](https://apps.shopify.com/shopigent), so charges appear on your regular Shopify invoice. No separate card, no separate account.\n\n## Plans at a glance\n\n| | Free | Growth | Pro |\n|---|---|---|---|\n| Price | $0 | $9.99/mo | $29/mo |\n| Read tools | ✅ All | ✅ All | ✅ All |\n| Write tools | — | ✅ Core resources | ✅ Core resources |\n| Translations | — | — | ✅ |\n| Theme content & Liquid | — | — | ✅ |\n| Tool calls / day | 25 | 500 | Unlimited |\n| Trial | — | 7-day trial | 7-day trial |\n\n**Core resources** = Products, Orders, Customers, Discounts, Content, Inventory, Fulfillments.\n\n> **Agency plan — coming soon.** A multi-store plan for agencies is on our roadmap. It is not yet available; join the waitlist at [hello@greeknous.com](mailto:hello@greeknous.com).\n\n## What you get per plan\n\n### Free — $0\n- Read-only access to your whole store\n- 92 curated tools across all Shopify surfaces\n- Up to 25 tool calls per day\n- Full audit log of every agent action\n- Dry-run preview before any action\n- Connect any MCP client (Claude, Cursor, Hermes)\n- Email support\n- No credit card required\n\n### Growth — $9.99/mo (7-day trial)\n- Everything in Free, plus write tools\n- Create, edit, update, delete products & orders\n- Manage customers, discounts, collections\n- Up to 500 tool calls per day\n- Mandatory confirmation on destructive actions\n- Blog, page & content management\n- Inventory & fulfillment tools\n\n### Pro — $29/mo (7-day trial)\n- Everything in Growth, plus premium scopes\n- Translations (set/get/delete) for any resource\n- Theme content & Liquid editing\n- Duplicate, publish & manage themes\n- Unlimited tool calls\n- Priority execution\n- Custom tools builder\n\n## How limits work\n\n- A **tool call** is one MCP tool invocation — one `list_products` call, one `refund_order`, etc.\n- Limits reset at midnight UTC.\n- Calls that hit the confirmation gate count once (not again on approval).\n- `dry_run` calls count as normal calls.\n\n## Upgrading & downgrading\n\n1. Open the Shopigent dashboard in your Shopify admin.\n2. Go to **Plan** and pick the new tier.\n3. Shopify shows its standard approval screen; charges are prorated by Shopify automatically.\n\nDowngrades apply at the end of the current billing cycle. Your settings, keys, and audit log are kept — write tools simply stop being available if the new plan doesn't include them.\n\n## FAQ\n\n**Do unused calls roll over?** No, the daily allowance resets every day.\n\n**What happens if I hit my limit?** Tools return a clear `rate_limited` error with the reset time. Reads on the Free plan are throttled, never silently dropped.\n\n**Is there a trial for paid plans?** Growth and Pro include a 7-day free trial via Shopify's standard trial mechanism.\n"},{"slug":"guides/prompts-best-practices","title":"Prompts & Best Practices","tags":["guide","prompts","best-practices"],"body":"\n# Prompts & Best Practices\n\nGet the most out of Shopigent by using the right prompts, safety patterns, and workflows.\n\n## Key principles\n\n### 1. Dry-run before write\n\nEvery write tool supports `dryRun: true`. Always preview the mutation before it touches your live store:\n\n```\nDry-run: update the price of \"Approach Under Glove\" to €39.99.\n```\n\nThe agent returns the exact GraphQL mutation it *would* execute. Only when you approve does it run live.\n\n### 2. Use categories explicitly\n\nShopigent has **10 tool categories** (Products, Content, Metaobjects & Custom Data, Themes, GitHub Theme, Orders, Customers, Discounts, Fulfillments, Inventory). Mention the category for faster tool routing:\n\n```\nUse products tools: find all products with no description in Italian.\n```\nvs.\n```\nWhat products need Italian descriptions?\n```\n\n### 3. Chain operations, don't guess\n\nInstead of asking for everything at once, chain:\n\n```\n1. List my products tagged \"clearance\".\n2. For each, update the price to 40% off current.\n3. Show me the total discount value.\n```\n\nThe agent resolves each step separately, triggering confirmation only when a write tool is used.\n\n### 4. Confirmation gate pattern\n\nDestructive writes (delete, refund, publish theme) require **confirmed: true**. Use this pattern:\n\n```\nDelete product with ID gid://shopify/Product/12345.\n```\n\n→ Returns `confirmation_pending` with a token.\n\n```\nConfirm: yes, with the same token.\n```\n\n→ Executes the delete and logs it.\n\nAn agent can *propose* destructive actions autonomously — nothing executes until you approve.\n\n## Prompts by role\n\n### Store owner\n\n```\nI'm going on holiday. Check my inventory: what needs reordering, \nare there any stuck fulfillments, and do I have active discounts \nthat expire while I'm away?\n```\n\n```\nList all products with 0 inventory and no reorder point set.\n```\n\n### Developer\n\n```\nI need to rename \"Trail Beanie\" to \"Trail Beanie 2.0\" across all \nlanguages. Dry-run a translation update for each language the product \nhas, then execute.\n```\n\n```\nExport my theme's schema.json and check if there are Liquid errors \nin the templates.\n```\n\n### Marketing\n\n```\nDraft a 15% discount code for email subscribers. The code should \nbe single-use per customer, valid for 48 hours, and exclude sale items.\n```\n\n```\nFind products with less than 2 inventory — these are running out \nand need promotion before they're gone.\n```\n\n## Tool priorities by task\n\n| If you want to… | Use… |\n|---|---|\n| Discover what's in stock | `list_products` with inventory filters |\n| Edit a product | `update_product` (dry-run first) |\n| Check revenue | `list_orders` (date range filter) |\n| Run a promotion | `create_discount` |\n| Fix customer details | `get_customer` → `update_customer` |\n| Manage content | `create_blog_post`, `update_page` |\n| Edit the design | `update_theme_content` (Pro) |\n| Translate the store | `set_translations` (Pro) |\n\n## Rate limits by plan\n\n| Plan | Tool calls / day | Best for |\n|---|---|---|\n| Free | 25 | Exploring, read-only queries |\n| Growth | 500 | Daily operations with writes |\n| Pro | Unlimited | Power use + custom tools + translations |\n\nUse **dry-run preview** to avoid wasting call allowance on failed writes.\n\n## Pro tips\n\n1. **Name your operations** — agents follow steps better when you say \"Step 1… Step 2…\"\n2. **Use filters** — `list_products` with `query: \"status:ACTIVE\"` returns useful subsets\n3. **Check the audit log** — every call is recorded. Review what your agent did.\n4. **Least privilege scopes** — enable only the categories your agent needs\n5. **Trial the Pro plan** — unlock theme editing, translations, and unlimited calls"},{"slug":"guides/security-and-trust","title":"Security & Trust","tags":["guide","security","trust"],"body":"\n# Security & Trust\n\nGiving an AI agent access to your store is a trust decision. Here is exactly how Shopigent limits, records, and controls that access.\n\n## The access model\n\n1. **You choose the categories.** Each of the 8 tool categories (Products, Orders, …) has an on/off toggle. Disabled categories are invisible to agents — the tools aren't listed, let alone callable.\n2. **Reads and writes are separated by plan.** Free is read-only by design; write tools only exist on paid plans.\n3. **Destructive actions stop at the confirmation gate.** Create, edit, delete, refund — the call pauses and a confirmation card appears in your dashboard. Nothing executes until a human approves it.\n4. **Everything is written to the audit log.** Tool name, full input, result, latency, timestamp. The log is append-only.\n\n## API keys\n\n- Keys are shown **once** at creation; Shopigent stores only a salted hash.\n- Keys can be revoked instantly from the dashboard.\n- Each key is scoped to one store.\n\n## Data handling\n\n- Shopigent processes your store data to execute tool calls; it does not sell it or use it for advertising.\n- Store data is **not used to train AI models**.\n- Audit log entries are retained so you can review agent activity; you can request deletion of your data at any time.\n- Uninstalling the app triggers Shopify's standard data-removal webhooks and Shopigent deletes stored shop data accordingly (see [Privacy Policy](/privacy-policy)).\n\n## Shopify-side protections\n\n- Shopigent requests only the Shopify scopes needed for the categories you use.\n- All traffic runs over TLS.\n- Billing is handled entirely by Shopify — Shopigent never sees your payment details.\n\n## Reporting a vulnerability\n\nFound something? Email **shopigent@greeknous.com**. We respond fast and appreciate responsible disclosure.\n"},{"slug":"guides/troubleshooting-faq","title":"Troubleshooting & FAQ","tags":["guide","faq","troubleshooting"],"body":"\n# Troubleshooting & FAQ\n\n## Connection issues\n\n**401 Unauthorized**\nThe API key is invalid or revoked. Generate a new key in the dashboard and update your MCP client config. Remember: keys are shown only once.\n\n**MCP client can't find the server**\nCheck the endpoint URL and that your client actually reloaded its config (Cursor and Claude Desktop need a full restart).\n\n## Missing or failing tools\n\n**A tool doesn't appear in the tools list**\nThe category is toggled off in **Curated Tools**, or your plan doesn't include it (e.g. theme tools require Pro).\n\n**`plan_upgrade_required` error**\nThe tool exists but your plan is read-only for it. See [Plans & Billing](/guides/plans-and-billing).\n\n**`rate_limited` error**\nYou hit the daily call allowance (Free 25/day, Growth 500/day). The error includes the reset time (midnight UTC).\n\n## Confirmation gate\n\n**\"Action pending confirmation\" — nothing happens**\nThe action is waiting for approval in the Shopigent dashboard. Open the app in Shopify admin and approve or reject it.\n\n**Can I turn off confirmations?**\nNo — that's deliberate. Every destructive action requires human approval. Use `dry_run` for previews instead.\n\n## General\n\n**Does Shopigent work with any MCP client?**\nYes — anything that speaks Model Context Protocol: Claude, Cursor, Hermes, custom agents.\n\n**Can agents see data in disabled categories?**\nNo. Disabled categories aren't listed to the agent at all.\n\n**Where do I see what my agent did?**\nThe **Audit Log** in the dashboard — every call with input, result, and latency.\n\n**How do I completely revoke an agent's access?**\nRevoke its API key. Effect is immediate.\n\nStill stuck? Email **shopigent@greeknous.com**.\n"},{"slug":"index","title":"Shopigent — Operate your Shopify store with AI agents","tags":["home","overview"],"body":""},{"slug":"privacy-policy","title":"Privacy Policy","tags":["legal","privacy"],"body":"\n# Shopigent — Privacy Policy\n\n**Last updated:** 2026-07-24 | **Controller:** Greek Nous | **Contact:** shopigent@greeknous.com\n\n## 1. What Shopigent is\nShopigent is a Shopify app that lets merchants operate their store through AI agents (any MCP-compatible client, e.g. Hermes, Claude, Cursor). It exposes a curated set of read and write operations (\"tools\") over the Shopify Admin API, gated by the merchant's chosen plan and the scopes they grant at install time.\n\n## 2. Data we access\nAt install, the merchant authorizes Shopify OAuth scopes. Shopigent only accesses data required by the tools the merchant enables. Possible scope categories: products, orders, customers, discounts, inventory, fulfillments, online store content, and themes. We access store data **only** to fulfill a tool call the merchant (or their agent, on their behalf) explicitly triggers.\n\nWe do **not** access: payment instrument numbers, passwords, or any data outside the authorized Shopify scopes.\n\n## 3. Data we store\n- **Shop connection metadata** (store domain, granted scopes, current plan).\n- **API key hashes** — we store only a salted SHA-256 hash of the MCP API key. The plaintext key is shown once at creation and never stored.\n- **Tool-call audit logs** — for every tool call we record: shop, tool key, operation type, input arguments, result status, and latency.\n- **Plan / billing events** — subscription status and Shopify charge IDs (received via Shopify webhooks), not card numbers.\n\n## 4. Data we share\nWe do not sell or share merchant data with third parties except:\n- with **Shopify**, necessarily, to perform the requested operations;\n- with the merchant's chosen AI client, only the data needed to answer the specific request they made.\n\n## 5. Data retention\nAudit logs and connection metadata are retained while the app is installed. Uninstalling the app triggers deletion of store-specific records.\n\n## 6. Security\nMCP API keys are hashed (never stored in plaintext). All Admin API calls use the store's OAuth access token, transmitted only to Shopify over TLS. Destructive tools require an explicit confirmation step before they run.\n\n## 7. Your rights\nMerchants may request deletion of their data at any time via shopigent@greeknous.com or by uninstalling the app from their Shopify admin.\n\n## 8. Changes\nMaterial changes to this policy will be communicated via the support email.\n"},{"slug":"reference/scopes-and-permissions","title":"Scopes & Permissions Reference","tags":["reference","scopes","permissions"],"body":"\n# Scopes & Permissions Reference\n\nTwo layers of scoping protect your store: **Shopify OAuth scopes** (what the app itself may access) and **Shopigent category toggles** (what your agents may access). An agent can never exceed either layer.\n\n## Category → Shopify scope map\n\n| Shopigent category | Read scope | Write scope |\n|---|---|---|\n| Products | `read_products` | `write_products` |\n| Orders | `read_orders` | `write_orders` |\n| Customers | `read_customers` | `write_customers` |\n| Discounts | `read_discounts` | `write_discounts` |\n| Content (pages/blogs) | `read_content` | `write_content` |\n| Metaobjects & Custom Data | `read_metaobjects` | `write_metaobjects` |\n| Themes | `read_themes` | `write_themes` |\n| GitHub Theme | app-internal (no OAuth scope) | app-internal (no OAuth scope) |\n| Inventory | `read_inventory` | `write_inventory` |\n| Fulfillments | `read_fulfillments` | `write_fulfillments` |\n| Translations *(Pro)* | `read_translations` | `write_translations` |\n| Publications *(get_product_publications)* | `read_publications` | — |\n\n## How the layers interact\n\n```\nAgent calls tool\n   │\n   ├─ 1. Is the category enabled in Curated Tools?   ── no → tool not even listed\n   ├─ 2. Does the plan allow this tool type?          ── no → plan_upgrade_required\n   ├─ 3. Does the app hold the Shopify scope?         ── no → scope_missing\n   ├─ 4. Is it destructive?                           ── yes → confirmation gate\n   └─ 5. Execute → record in audit log\n```\n\n## Principle of least privilege\n\n- Start with only the categories you need — you can enable more later without reinstalling.\n- Prefer separate API keys per agent/client, so revoking one doesn't break the others.\n- Review the audit log after enabling a new category to see how your agent uses it.\n"},{"slug":"reference/tools","title":"Tools Reference","tags":["reference","tools"],"body":"\n# Tools Reference\n\nShopigent exposes **92 curated tools** across 10 categories. Each category can be toggled on/off per store, and write tools always pass through the confirmation gate.\n\n> Tools are *curated operations*, not raw API passthrough — inputs are validated, outputs are trimmed to what agents actually need, and destructive calls require human approval.\n\n## Plans at a glance\n\n| Plan | Daily calls | Access |\n|------|-------------|--------|\n| Free | 25/day | Read-only (queries) |\n| Growth | 500/day | All writes except premium tools |\n| Pro | Unlimited | Everything, including translations + theme editing |\n\n**Premium (Pro-only) tools:** `set_translations`, `get_translations`, `delete_translations`, `update_theme_content`, `update_theme_file`, `update_theme_translations`, `duplicate_theme`, `publish_theme`.\n\n---\n\n## Products (28)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_products` | Read | Free | Paginated list of products, optionally filtered by a search query. |\n| `search_products` | Read | Free | Full-text search across product titles, descriptions, and tags with relevance scoring. |\n| `get_product_by_id` | Read | Free | Fetch a single product by its Shopify GID. |\n| `create_product` | Write | Growth | Creates a new product with optional description, status, vendor, type, price, SKU, barcode, weight, and tags. |\n| `update_product` | Write | Growth | Updates a product's fields including title, description, status, vendor, type, tags, SEO, handle, and template (templateSuffix / clearTemplateSuffix). |\n| `delete_product` | Write | Growth | Permanently deletes a product. Irreversible. |\n| `create_product_variant` | Write | Growth | Adds a variant (SKU, price, weight, barcode) to an existing product. |\n| `update_product_variant` | Write | Growth | Sets SKU, price, weight, and barcode on an existing product variant. |\n| `update_product_variant_price` | Write | Growth | Sets the price of a single product variant by its GID. |\n| `bulk_update_prices` | Write | Growth | Updates prices for multiple variants at once. |\n| `update_product_images` | Write | Growth | Manages product images (add, update alt text, delete) via the Shopify Media API. |\n| `upload_product_media` | Write | Growth | Uploads media to a product using Shopify's staged-upload flow. |\n| `get_product_media` | Read | Free | Lists media attached to a product. |\n| `get_product_publications` | Read | Free | Lists where a product is published (channels, online store, etc.). |\n| `get_product_metafields` | Read | Free | Reads metafields attached to a product. |\n| `set_product_metafields` | Write | Growth | Writes or updates one or more product metafields. |\n| `get_store_info` | Read | Free | Returns store-level information: name, email, currency, timezone, and plan. |\n| `list_collections` | Read | Free | Lists all collections (manual + automated) with id, title, handle, and sort order. |\n| `get_collection_by_id` | Read | Free | Fetches a single collection by its GID, including description, image, product count. |\n| `create_collection` | Write | Growth | Creates a new manual or automated collection. |\n| `update_collection` | Write | Growth | Updates a collection's title, description, handle, sort order, and/or SEO. |\n| `delete_collection` | Write | Growth | Deletes a collection by its GID. |\n| `add_products_to_collection` | Write | Growth | Adds one or more products to a collection. |\n| `remove_products_from_collection` | Write | Growth | Removes one or more products from a collection. |\n| `update_collection_image` | Write | Growth | Adds, updates, or deletes a collection's image. |\n| `get_translations` | Read | Pro | Reads all translatable content for a resource (product, collection, page, etc.) in a locale. |\n| `set_translations` | Write | Pro | Writes or updates translation values for a resource in a locale. |\n| `delete_translations` | Write | Pro | Removes translation overrides for given keys in a locale. |\n\n## Content (16)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_pages` | Read | Free | Lists all pages with id, title, handle, and status. |\n| `get_page_by_id` | Read | Free | Fetches a single page by its GID, including body and SEO metadata. |\n| `create_page` | Write | Growth | Creates a new online store page. |\n| `update_page` | Write | Growth | Updates a page's title, body, and/or handle. |\n| `delete_page` | Write | Growth | Deletes a page by its GID. |\n| `list_blogs` | Read | Free | Lists all blogs with id, title, handle, and comment policy. |\n| `get_blog_by_id` | Read | Free | Fetches a single blog by its GID, including its articles and metadata. |\n| `create_blog` | Write | Growth | Creates a new blog. |\n| `update_blog` | Write | Growth | Updates a blog's title and/or handle. |\n| `delete_blog` | Write | Growth | Deletes a blog by its GID. |\n| `list_articles` | Read | Free | Lists all blog articles for a blog, with optional filters. |\n| `get_article_by_id` | Read | Free | Fetches a single blog article by its GID, including body, summary, tags, author. |\n| `create_article` | Write | Growth | Creates a new blog post (article) under a blog. |\n| `update_article` | Write | Growth | Updates a blog post's title, body, summary, handle, tags, author. |\n| `delete_article` | Write | Growth | Deletes a blog post by its GID. |\n| `update_article_image` | Write | Growth | Adds, updates, or deletes a blog article's featured image. |\n\n## Metaobjects / Custom Data (15)\n\nAccess to **Custom Data** (metaobjects & metafield definitions) requires a dedicated scope category in **Scopes & Permissions**.\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_metaobjects` | Read | Free | Lists metaobjects of a given type. |\n| `list_metaobject_definitions` | Read | Free | Lists metaobject definitions. |\n| `get_metaobject` | Read | Free | Fetches a single metaobject by its GID. |\n| `create_metaobject` | Write | Growth | Creates a new metaobject. |\n| `update_metaobject` | Write | Growth | Updates an existing metaobject. |\n| `delete_metaobject` | Write | Growth | Deletes a metaobject. Destructive. |\n| `get_metaobject_definition` | Read | Free | Fetches a single metaobject definition. |\n| `create_metaobject_definition` | Write | Growth | Creates a metaobject definition. |\n| `update_metaobject_definition` | Write | Growth | Updates a metaobject definition. |\n| `delete_metaobject_definition` | Write | Growth | Deletes a metaobject definition. Destructive. |\n| `list_product_metafield_definitions` | Read | Free | Lists metafield definitions scoped to products. |\n| `get_metafield_definition` | Read | Free | Fetches a single metafield definition. |\n| `create_metafield_definition` | Write | Growth | Creates a metafield definition. |\n| `update_metafield_definition` | Write | Growth | Updates a metafield definition. |\n| `delete_metafield_definition` | Write | Growth | Deletes a metafield definition. Destructive. |\n\n## Themes (9)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_themes` | Read | Free | Lists all online store themes (main, unpublished, etc.). |\n| `get_theme_file` | Read | Free | Reads a single theme file (e.g. config/settings_data.json, templates/index.liquid). |\n| `upload_theme_asset` | Write | Pro | Uploads any file to a theme (images as BASE64, text as TEXT). Supports PNG, JPG, SVG, Liquid, JSON, CSS, JS. |\n| `duplicate_theme` | Write | Pro | Creates a copy of an existing theme for safe editing. |\n| `update_theme_content` | Write | Pro | Edits the Customizer content of a theme via config/settings_data.json. |\n| `update_theme_file` | Write | Pro | Writes/overwrites ANY theme file (Liquid template, section, snippet, JSON). |\n| `publish_theme` | Write | Pro | Makes a theme the live (published) theme. |\n| `get_theme_translations` | Read | Free | Reads all theme content translations for a given locale. |\n| `update_theme_translations` | Write | Pro | Writes/updates theme content translations for one or more keys. |\n\n## Orders (6)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_orders` | Read | Free | Paginated list of orders, filterable by status/date/tags. |\n| `search_orders` | Read | Free | Full-text search across orders by number, customer name, or email. |\n| `get_order` | Read | Free | Fetches a single order by its GID (line items, addresses, tags, status). |\n| `create_order` | Write | Growth | Creates a draft order with line items and customer info. |\n| `update_order` | Write | Growth | Updates editable order fields: tags, note, and/or email. |\n| `refund_order` | Write | Growth | Issues a refund on an order. Irreversible financial action. |\n\n## Customers (5)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_customers` | Read | Free | Lists store customers with optional filters. |\n| `search_customers` | Read | Free | Full-text search across customers by name, email, or phone. |\n| `get_customer` | Read | Free | Fetches a single customer by GID (name, email, phone, tags, note). |\n| `create_customer` | Write | Growth | Creates a new customer. |\n| `update_customer` | Write | Growth | Updates a customer's tags or note. |\n\n## Discounts (4)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_discounts` | Read | Free | Lists store discounts (discount nodes). |\n| `get_discount` | Read | Free | Fetches a single discount by its GID node id. |\n| `create_discount` | Write | Growth | Creates a new discount code or automatic discount. |\n| `delete_discount` | Write | Growth | Deletes a discount by its GID. |\n\n## Fulfillments (4)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `list_fulfillment_orders` | Read | Free | Lists store fulfillment orders. |\n| `get_fulfillment_order` | Read | Free | Fetches a single fulfillment order by its GID. |\n| `close_fulfillment_order` | Write | Growth | Closes a fulfillment order (marks it fulfilled/complete). |\n| `open_fulfillment_order` | Write | Growth | Re-opens a closed fulfillment order. |\n\n## Inventory (1)\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `update_inventory_quantity` | Write | Growth | Sets the available inventory quantity for an item at a location. |\n\n## GitHub Theme (4)\n\nThe **GitHub Theme** category connects your store to a GitHub repo that serves as the source of truth for your theme. Theme changes are made as pull requests to that repo and deployed via GitHub Actions — a Git-first workflow that never auto-publishes to your live store. Access is enabled per store from the **GitHub Theme** page in the Shopigent dashboard (app-internal scope category, not an OAuth scope).\n\n| Tool | Type | Plan | What it does |\n|------|------|------|--------------|\n| `github_theme_connection` | Read | Free | Returns whether the store has a GitHub theme repo connected (owner/repo/defaultBranch). Does NOT expose tokens. Read-only. |\n| `github_list_theme_branches` | Read | Free | Lists branches on the connected store's theme GitHub repo. Requires a GitHub theme connection. Read-only. |\n| `github_theme_file` | Read | Free | Reads a single file from the theme GitHub repo at a ref (default: default branch). Returns path, branch, sha, and content. Read-only. |\n| `github_create_theme_pr` | Write | Growth | Commits one or more theme file changes to a new branch and opens a PR on the theme repo. Deploy is handled by GitHub Actions (staging, no auto-publish). Confirmation required; dry-run available. |\n\n## Cross-cutting features\n\n- **Dry-run** — every write tool accepts `dryRun: true` to preview the exact mutation without executing.\n- **Confirmation gate** — destructive calls pause until approved in the Shopigent dashboard.\n- **Audit log** — every call is recorded with input, result, and latency.\n- **Scope-based** — each category maps to its own OAuth scope category; enable only what your agent needs (least privilege)."},{"slug":"terms-of-service","title":"Terms of Service","tags":["legal","terms"],"body":"\n# Shopigent — Terms of Service\n\n**Last updated:** 2026-07-24 | **Provider:** Greek Nous | **Contact:** shopigent@greeknous.com\n\n## 1. Acceptance\nBy installing or using Shopigent (\"the App\") you agree to these Terms. The App is provided as-is, without warranty, for use with your Shopify store.\n\n## 2. Plans and billing\nThe App offers Free, Growth, and Pro plans. Plan limits (e.g. daily tool-call allowances, available tools) are enforced as described in the App. Paid plans are billed through Shopify's billing API; cancelling reverts the store to the Free plan. We do not store card details. An Agency (multi-store) plan is planned but not yet available.\n\n## 3. Use of tools\nThe App exposes operations over your Shopify store. You are responsible for the actions your agents perform. Destructive operations (create/delete/refund/etc.) require an explicit confirmation step before execution. You should review audit logs regularly.\n\n## 4. Scope authorization\nThe App only performs operations your store has authorized via Shopify OAuth scopes. Enabling a tool does not grant new Shopify scopes; it only makes an already-authorized operation available to your agents.\n\n## 5. Acceptable use\nYou agree not to use the App to violate Shopify's Acceptable Use Policy, applicable law, or the rights of others. We may suspend access for abuse.\n\n## 6. Limitation of liability\nThe App is provided \"as is.\" To the maximum extent permitted by law, Greek Nous is not liable for indirect or consequential damages arising from use of the App, including merchant actions performed via AI agents.\n\n## 7. Termination\nEither party may terminate use by uninstalling the App. Upon uninstall, store data handling follows our Privacy Policy.\n\n## 8. Contact\nQuestions: shopigent@greeknous.com\n"}]}