Skip to content
ShopMCP
All topicsRead as Markdown

Shopify Admin API operations

ShopMCP exposes the pinned, non-deprecated Shopify Admin GraphQL API through named operations. Discover the compact operation catalogue with search_shopify_operations(query, kind, offset, limit); inspect operation inputs and output fields with get_shopify_operation(operation). Explore nested input and output types with get_shopify_type(typeName, offset, limit). These metadata tools explain the schema and are available even when execution is denied. They do not prove that a shop has the required Shopify scopes, protected customer-data approval, plan entitlement, or staff access. Shopify checks those against the connected token.

Every operation must also be explicitly granted in that connection's API operations selector. These per-operation grants are additional to the existing simple resource tools; existing resource grants are never expanded into API-operation grants. The operation's read, write, or delete class is used for consent, audit, and plan checks. Platform scopes and entitlements remain separate requirements.

The Check Shopify access control reads the installed app's granted, required, and optional scopes only after a merchant clicks it. To request more app access, add eligible handles to Shopify's optional_scopes app configuration and deploy that configuration first. Then select only the optional, ungranted scopes needed and click Request selected scopes. Shopify reports whether the selected request was granted or declined; a decline leaves the choices available for review. This flow does not revoke scopes and never requests hidden or unselected values. Shopify scopes are app-wide and do not add any operation to a connection's explicit grant list. write_themes is an ordinary Shopify access scope. Individual theme file operations such as themeFilesUpsert also require Shopify's Theme App Extension exemption. ShopMCP has not confirmed that exemption; theme mutations remain unavailable until it is confirmed, even when an operation and write_themes are granted. Shopify scopes API

Execute one named operation with shopify_query(operation, arguments, selection?) or shopify_mutation(operation, arguments, selection?, idempotencyKey?). Inputs are schema-typed variables. Output selections are validated against the pinned schema. Unknown, deprecated, injected, over-deep, over-sized, or policy-unsafe operations are rejected. Mutations must request and return Shopify userErrors; inspect them before proceeding. Use the operation and type inspection tools to learn all required and optional fields, nested input types, enums, nullability, and selectable output fields before constructing arguments.

For lists, request bounded pages and carry the returned cursor in the next call. Pro connections can use shopify_batch(operation, rows:[arguments...], selection?, offset?, limit?, continueOnError?) for independent mutation rows. Batches run at most 25 rows per request, and the caller-held row list and offsets remain subject to the connection's batch policy limit. The response gives per-row results and failures plus continuation details; resume from those details. Mutations are never automatically retried. A failed or timed-out write may have reached Shopify, so inspect current state before deciding whether to submit it again and use an idempotency key where supported.

Coverage recipes

  • Product content and SEO: Inspect productUpdate, its nested product input, SEO fields, and user errors; query the product afterward to verify saved values. Price fields still require the separate price policy.
  • Categories and catalog data: Inspect product/category operations and input enums, then query the resulting product and category associations. Shopify market/catalog eligibility remains platform-controlled.
  • Customers and addresses: Use customerCreate and relevant customerAddress* operations. Explicit customer-data policy, operation grants, protected-data approval, token scopes, and staff access all apply. Request only the personal fields you need.
  • Discounts: Use the discount queries and mutations to inspect, create, update, activate, or deactivate supported discount types. Follow the returned union/type shape and check user errors. One offer stays one discount: never create several discounts with the same value to get different codes; use discountRedeemCodeBulkAdd (convenience: add_discount_codes) to add redeem codes to an existing discount instead, and discountRedeemCodeBulkCreation (convenience: get_discount_code_creation) to poll the result.
  • Draft orders: draftOrderCreate and draftOrderUpdate are refused before any Shopify request when their input carries an order-level or line-item appliedDiscount, independent of connection grants and the price policy (Built for Shopify 5.5.2). Use an existing code discount via discountCodes, or create_discount. draftOrderDuplicate and draftOrderCreateFromOrder run a read-only preflight on the source draft order or order first and are refused, fail closed, if that source carries a custom discount or cannot be fully verified.
  • Order editing: Query the order, call orderEditBegin, apply the relevant line-item or shipping mutations to the edit, inspect calculated changes and errors, then call orderEditCommit. Do not treat a successful intermediate edit as a committed order. orderEditAddLineItemDiscount is not a draft order and stays under the existing price policy only.
  • Returns and fulfillment: Inspect return, reverse-fulfillment, fulfillment-order, and fulfillment operations and their nested inputs. Shopify's order state, fulfillment service, location, scopes, and staff rights determine availability.
  • Inventory: Use inventoryAdjustQuantities for adjustments and inventory-transfer operations for transfers. Set allowed locations in connection policy; operations that cannot be bounded to those locations are denied.
  • Publications and menus: Inspect publication and menu query/mutation fields, then verify the resulting publication or menu state. Publishing still depends on Shopify scopes and resource availability.
  • Metafields and metadata: Use the operation's namespace and owner inputs and the configured metafield namespace allowlist. Operations whose namespace cannot be safely constrained are denied when an allowlist is configured.
  • B2B: Inspect company, location, contact, and catalog operations and nested inputs. Store plan, scopes, customer-data policy, and Shopify staff access still apply.
  • Analytics: Discover ShopifyQL and analytics operations, inspect their query inputs and result types, and page through bounded results. Data availability and access depend on the shop and Shopify entitlements.

Batch processing is for bounded, resumable work and reports each row independently. Large reads should use schema-supported pagination and caller-held cursors. Shopify-native bulk operations remain restricted because ShopMCP cannot yet enforce ownership and output controls over their delegated results. Theme writes require a new explicit operation grant and Shopify's write_themes scope. Theme file writes such as themeFilesUpsert additionally require Shopify's Theme App Extension exemption, which ShopMCP has not confirmed; the app-level gate keeps theme mutations unavailable until then. Existing theme backup/restore behavior does not authorize writes.

Existing OAuth clients

If the shop owner grants additional operations, existing OAuth connections remain limited to the scope of their original consent. Reconnect the AI client and approve the expanded scope so the new operations can be used. An existing API-key connection uses its current connection grants. Shopify scopes must also actually be granted.

Errors or missing features

get_support_reporting_instructions describes the optional reporting workflow. The client shows the complete technical report to the user first and sends it only after explicit approval with submit_support_report. See [Report an issue](/docs/support?locale=en) for details.