List all Shopify stores configured for this agent.

Returns a JSON array of {alias, domain, name, currency, auth_mode}. The name field is the merchant's own shop name from Shopify (fetched once per process, cached). Use this list to match user intent - e.g., a user saying "check the outlet" maps to the store whose name or domain contains "outlet".

If only one store is configured, shop can be omitted on tool calls.

Args: refresh: If True, bypass the shop-name cache and re-fetch from Shopify. Use after a merchant renames a shop in the Shopify admin.

Execute a read-only GraphQL query against a Shopify store's Admin API.

Universal entry point for reading any data the token's scopes permit: products, variants, orders, customers, inventory, fulfillments, discounts, locations, markets, metafields, metaobjects, segments, shop settings, etc.

Full GraphQL reference: https://shopify.dev/docs/api/admin-graphql

Write mutations are rejected by design. The query string is parsed and validated as read-only before transmission.

Idiomatic patterns:

• Pagination: first: <=250, after: <cursor>, read pageInfo { hasNextPage endCursor }.

• Search: pass a Shopify search string to the query: arg on connections, e.g. orders(first: 100, query: "created_at:>=2026-04-01 financial_status:paid").

• Money: totalPriceSet { shopMoney { amount currencyCode } }.

• For datasets >10k records, use shopify_bulk_query instead.

Args: query: GraphQL document. Must be a query or a fragment. Subscription and mutation operations are rejected - with one narrow exception, bulkOperationCancel. For bulk exports, use shopify_bulk_query. variables: Optional variables dict passed as GraphQL variables. shop: Store alias (from shopify_list_stores) or domain. Required when multiple stores are configured; optional (auto-selected) when there's only one store. api_version: Override API version (default "2026-04"). Format "YYYY-MM".

Introspect a Shopify store's Admin GraphQL schema.

Pass type_name to fetch a single type's fields (cheap, ~50 cost points). Omit it for the full schema type catalog (expensive, ~800 cost points - use sparingly).

Args: type_name: GraphQL type name (e.g. "Order", "Product", "Customer"). Must match [A-Za-z_][A-Za-z0-9_]*. Omit for full schema. shop: Store alias or domain (see shopify_list_stores). Required when multiple stores are configured. api_version: Override API version (default "2026-04").

Launch an async bulk export of a read-only GraphQL query.

Use for exporting datasets too large for paginated queries (>10k records, or anything you'd otherwise paginate hundreds of times). Shopify runs the query in the background and produces a JSONL file with all results.

Restrictions (enforced by Shopify):

• Exactly one top-level connection per query.

• Max 5 total connections, max depth 2.

• Every nested connection node must select id without an alias.

• API ≤ 2025-10: one bulk op at a time per shop. API ≥ 2026-01: up to 5.

Returns the BulkOperation ID - poll with shopify_bulk_poll.

Args: query: Read-only GraphQL document with a single root connection. shop: Store alias or domain. Required when multiple stores are configured. api_version: Override API version (default "2026-04").

Poll a bulk operation's status by ID.

Statuses: CREATED, RUNNING, COMPLETED, CANCELED, EXPIRED, FAILED. On COMPLETED, the url field is a pre-signed JSONL download (valid 7 days). On FAILED, partialDataUrl may hold partial results; errorCode explains why.

Args: operation_id: Global ID of the bulk operation (format: gid://shopify/BulkOperation/<numeric-id>). shop: Store alias or domain the bulk op was launched on. Required when multiple stores are configured. api_version: Override API version (default "2026-04").

Run a ShopifyQL analytics query against a Shopify store.

ShopifyQL is Shopify's SQL-like reporting language. Requires read_reports scope. Consumes the same cost bucket as GraphQL.

Syntax: FROM SHOW [, ...] [BY ] [GROUP BY ] [WHERE ] [SINCE -Nd UNTIL today] [ORDER BY [ASC|DESC]] [LIMIT N]

Datasets: sales, orders, products, customers, inventory, sessions. Time tokens: -Nd / -Nw / -Nm / -Nq / -Ny, or named (today, yesterday, this_week, last_week, this_month, last_month, last_year).

Examples:

• FROM sales SHOW total_sales GROUP BY day SINCE -7d UNTIL today ORDER BY day ASC

• FROM sales SHOW total_sales BY product_title ORDER BY total_sales DESC LIMIT 10 SINCE -30d

• FROM sales SHOW returning_customer_rate GROUP BY month SINCE -6m

• FROM sales SHOW net_sales SINCE -1q UNTIL today

• FROM sessions SHOW sessions, conversion_rate GROUP BY referrer_source SINCE -14d

Returns tableData.columns, tableData.rows, and parseErrors. When parsing fails, tableData is null and parseErrors contains a list of human-readable error strings (e.g. "Column 'total_sale' not found").

Args: query: ShopifyQL query string. shop: Store alias or domain. Required when multiple stores are configured. api_version: Override API version (default "2026-04").