Gentic Shopify — Documentation

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Shopify, you need an API key to authenticate your requests.

1. Go to gentic.co/shopify and create an account.
2. Create an organization from your dashboard. API keys and billing are scoped to the organization.
3. Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/shopify. For Claude Code:

claude mcp add gentic-shopify \
  --transport http \
  https://mcp.gentic.co/shopify \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Shopify agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/shopify/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/shopify/gentic-shopify.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. When to Apply

• User wants to inspect or analyze Shopify orders, products, or customers in plain English.
• User wants to compute ROAS, attributed revenue, or CAC by joining Shopify orders against ad spend from Meta or Google Ads.
• User wants a CSV export of orders filtered by date, financial status, or channel (source_name).
• User wants the top customers by lifetime value, or to investigate a specific customer's order history.
• User wants to look up a single order, product, or customer by ID, GID, or product handle.
• User wants to run an arbitrary Admin GraphQL query against the Shopify store (read-only).
• User wants to know which Shopify store is connected, or check the store's currency, timezone, or plan.

5. Workflow

1. 1. Check connection with `shopify_connection_status`

   Free call — returns whether the org has connected a Shopify store, plus the `shop_domain` and `updated_at` timestamp when connected. If not connected, direct the user to the Gentic dashboard → Integrations → Shopify to paste a shop subdomain and Admin API access token. At least one of `read_orders` / `read_products` / `read_customers` must be granted on the token; individual tools that need a specific scope will surface their own error at call time if it's missing.

2. 2. Grab store basics with `get_shop_info`

   Free call — returns name, email, primary domain, currency, IANA timezone, weight unit, and plan. Worth calling once per session: the currency drives how you format revenue numbers, and the timezone matters for any date-bucketed analysis (`processed_at` comes back in store-local time).

3. 3. List orders with `list_orders` (5¢/call)

   Cursor-paginated. Sort defaults to `processed_at` descending — the right key for revenue attribution, since `processed_at` is when the order was actually placed (`created_at` can include draft-order timestamps that lag). Filter by date range (`processed_at_min`/`max` for ROAS, `created_at_min`/`max` for funnel analysis), `financial_status`, `fulfillment_status`, and `source_name` (the channel — workhorse for ROAS attribution). Watch for `line_items_truncated: true` on orders with >50 line items — follow up with `get_order` for the full breakdown.

4. 4. Drill into a single record (free)

   `get_order`, `get_product`, and `get_customer` are all free. `get_order` returns full line items (up to 250), refunds, fulfillments + tracking, addresses, and customer summary. `get_product` accepts either `id` or `handle` and returns up to 20 images + 100 variants with prices, SKUs, and inventory quantities — set `include_html: true` to also pull `descriptionHtml`. `get_customer` returns the customer profile plus the 10 most recent orders inline (handy for LTV / churn / cohort analysis without a second roundtrip).

5. 5. List products with `list_products` (5¢/call)

   Most recently updated first. Filter by `status` (ACTIVE / ARCHIVED / DRAFT), `vendor`, `product_type`, and `title` (substring match). Returns summary fields including price range and total inventory. For variants, SKUs, and full descriptions, follow up with `get_product`. Use `extra_query` for any Shopify search syntax the typed filters don't cover.

6. 6. List customers with `list_customers` (5¢/call)

   Sorts by `total_spent` descending by default — top customers first, the right order for LTV analysis. Filter by `email` (exact), `tag` (exact), `total_spent_min`/`max`, `orders_count_min`, `created_at_min`/`max`. `extra_query` is the escape hatch for free-form Shopify search. Paginate via `next_cursor` — `resultCount` reflects the page only, not the total.

7. 7. Export revenue for joins with `export_orders_report` ($1/call)

   The ROAS workhorse. Returns a CSV download URL that expires in **1 hour** AND persists the rows to MotherDuck `shopify_orders` with a schema that matches the row layout exactly. Pre-computes `net_revenue` (= `current_total_price` − `total_refunded`) and `processed_date` (DATE part of `processed_at`) so the join against `meta_ad_insights` is a single equality predicate, not a CASE-laden CTE. Filter by `processed_at_min`/`max` (preferred for ROAS attribution), `created_at_min`/`max`, `financial_status`, `source_name`, or `extra_query`. Caps at 10,000 orders per call — narrow the date window if you hit it. Tell the user the 1-hour expiry up front.

8. 8. Use `shopify_graphql_query` as an escape hatch (10¢/call)

   When the typed tools don't cover a specific field, drop into raw Admin GraphQL (API version `2026-04`). Mutations and subscriptions are rejected server-side — Gentic's Shopify surface is analytics-only and won't modify the store. Returns the raw GraphQL response plus rate-limit cost info. Prefer the typed tools when they exist: they paginate, normalize money fields, and surface consistent error messages.

9. 9. Present results clearly

   For orders: lead with the headline (period revenue, order count, AOV), show a ranked table by the metric the user cares about, and call out outliers (huge orders, refunds, unusual channels). For customers: surface lifetime value, order count, and the most recent order date prominently. For exports: show the download URL **and the 1-hour expiry** clearly so the user doesn't lose access to the file. For ROAS workflows: after running `export_orders_report`, hand the analysis to the Data MCP server to join `shopify_orders.processed_date` against `meta_ad_insights.date` and compute ROAS = `net_revenue / spend`.

6. Tool Reference

10 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

7. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

8. Notes

• **Read-only by design.** Every tool in v1 is read-only; `shopify_graphql_query` rejects mutations and subscriptions server-side.
• **Scopes are not all-or-nothing.** Connection succeeds as long as at least one of `read_orders` / `read_products` / `read_customers` is granted. A ROAS-focused user can connect with `read_orders` alone; tools that need a different scope error at call time with a clear message naming the scope to add.
• **`processed_at` vs `created_at`:** `processed_at` is when the order was actually placed and is the right key for revenue attribution. `created_at` can include draft-order timestamps that lag. Default sort and the export's pre-computed `processed_date` both use `processed_at`.
• `shop_domain` is the subdomain only (e.g. `my-shop` for `my-shop.myshopify.com`) and is stored as plaintext — it's a tenant identifier, not a secret. The Admin API access token is encrypted at rest.
• `list_*` tools cap each page at 50 records and paginate via `next_cursor`. `resultCount` is the page size, not the total — there's no cheap total count on Shopify, by design.
• `get_order` returns up to 250 line items; if an order has more (rare), use `shopify_graphql_query` for the rest.
• `get_product` accepts either `id` (numeric or full GID) or `handle` (the url-safe slug) — exactly one, not both.
• **`export_orders_report` CSV links expire in 1 hour.** The MotherDuck `shopify_orders` table persists, so you don't lose the data — re-export only if you need a fresh CSV file.
• `export_orders_report` caps at 10,000 orders per call. Narrow the date window if you hit it; the warehouse table is appended/upserted in chunks so multiple calls compose cleanly.
• Shopify Admin API version pinned to `2026-04`. Bumps are coordinated with the gentic-web validator's `SHOPIFY_API_VERSION` constant.
• All tools are organization-scoped — users only see their own Shopify store.