Skip to main content
Glama

shopify_manage

Destructive

Perform guided Shopify writes on one selected store by operation, previewing changes by default and reading state before applying updates, deletes, inventory, discounts, orders, or refunds.

Instructions

Guided writes for one store, chosen by operation. Every operation reads the current state first, defaults to dryRun:true (a preview that changes nothing), never notifies customers unless asked, and reads the result back after a write. Put the operation's fields in input. Operations:

  • webhook: Create, update or delete one of this app's webhook subscriptions (webhookSubscriptionCreate / Update / Delete). Deliver to an HTTPS URL, Google Pub/Sub (pubsub://project:topic) or Amazon EventBridge. A subscription keeps sending store data to its uri until it is deleted, whoever made it, so create, and an update that changes uri, need confirm:"webhook"; delete needs confirm:"delete". create refuses a duplicate topic and uri. The name records who made the change. Shopify shows an app only the webhook subscriptions it created; other apps' subscriptions are not listed. input: {action: create|update|delete, id?, topic?, uri?, format?: JSON|XML, filter?, includeFields?: [...], metafieldNamespaces?: [...], name?}

  • page: Create, update or delete an Online Store page (pageCreate / pageUpdate / pageDelete). body is HTML. update and delete read the page first; update previews current and changes. A handle change on update can leave the old URL redirecting (redirectNewHandle). delete cannot be undone and needs confirm:"delete". seo is not available: Shopify's page input has no SEO fields. input: {action: create|update|delete, id?, title?, body?, handle?, isPublished?, publishDate?, templateSuffix?, redirectNewHandle?}

  • article: Create, update or delete a blog article (articleCreate / articleUpdate / articleDelete). create needs blogId, title and author (a name). body and summary are HTML; imageUrl is a public https URL with imageAlt. update and delete read the article first; blogId on update moves it to another blog. delete cannot be undone and needs confirm:"delete". input: {action: create|update|delete, id?, blogId?, title?, body?, summary?, author?, tags?: [...], imageUrl?, imageAlt?, isPublished?, publishDate?, handle?, templateSuffix?, redirectNewHandle?}

  • blog: Update a blog's title, handle, commentPolicy (AUTO_PUBLISHED, MODERATED or CLOSED) or templateSuffix (blogUpdate). Update only: blogs are not created or deleted here. Reads the blog first; dryRun:true (the default) previews. redirectNewHandle and redirectArticles keep old URLs working after a handle change. input: {id, title?, handle?, commentPolicy?: AUTO_PUBLISHED|MODERATED|CLOSED, templateSuffix?, redirectNewHandle?, redirectArticles?}

  • metaobject: Create, update, upsert or delete one metaobject entry (metaobjectCreate / Update / Upsert / Delete). Reads the definition first and rejects unknown field keys before any write. create: type, optional handle, fields [{key, value}], optional status DRAFT or ACTIVE (publishable types). update: id plus fields and/or status. upsert: type plus handle plus fields. delete: id, needs confirm "delete". input: {action: create|update|upsert|delete, id?, type?, handle?, fields?: [{key, value}], status?: DRAFT|ACTIVE}

  • metafield_definition: Create one metafield definition (metafieldDefinitionCreate); create only. Refuses when ownerType, namespace and key already have a definition. The access scope depends on the owner type (for example write_products for PRODUCT, write_customers for CUSTOMER), so none is checked up front and Shopify rejects a missing one. type is a metafield type name such as single_line_text_field or list.single_line_text_field; validations are {name, value} pairs; pin puts it at the top of the admin page. input: {action: create, ownerType, namespace, key, name, type, description?, validations?: [{name, value}], pin?}

  • draft_order: Edit or delete an existing draft order. update (draftOrderUpdate): any of lineItems (replaces the whole list), customerId, email, note, tags (replaces), shippingAddress, billingAddress, appliedDiscount, shippingLine and reserveInventoryUntil; the preview runs draftOrderCalculate when lineItems change. delete (draftOrderDelete) cannot be undone and needs confirm:"delete". Completed draft orders are refused. No invoice is sent. Create and complete are separate operations. input: {action: update|delete, id, lineItems?: [{variantId?, title?, price?, quantity, sku?, taxable?, requiresShipping?}], customerId?, email?, note?, tags?: [...], shippingAddress?: {firstName?, lastName?, company?, address1?, address2?, city?, provinceCode?, countryCode?, zip?, phone?}, billingAddress?: {firstName?, lastName?, company?, address1?, address2?, city?, provinceCode?, countryCode?, zip?, phone?}, appliedDiscount?: {value, valueType: FIXED_AMOUNT|PERCENTAGE, title?, description?}, shippingLine?: {title, price}, currencyCode?, reserveInventoryUntil?}

  • file: Create, rename or delete files in Content > Files, any content type. create (fileCreate) copies a public HTTPS originalSource URL into Shopify as FILE, IMAGE, VIDEO, EXTERNAL_VIDEO or MODEL_3D, with alt and filename. update (fileUpdate) changes alt and filename. delete (fileDelete, up to 50 ids) cannot be undone and needs confirm:"delete"; it lists the files first. Shopify processes files asynchronously: fileStatus starts as UPLOADED or PROCESSING and becomes READY. Check with shopify_search files or shopify_get uploaded_image. input: {action: create|update|delete, originalSource?, contentType?: FILE|IMAGE|VIDEO|EXTERNAL_VIDEO|MODEL_3D, alt?, filename?, id?, ids?: [...]}

  • fulfillment: Change tracking on a fulfillment (update_tracking, fulfillmentTrackingInfoUpdate) or cancel it (cancel, fulfillmentCancel). Cancel reverses the fulfillment and reopens its items on new fulfillment orders; it needs confirm:"cancel". notifyCustomer defaults to false. Reads the fulfillment first. Needs a fulfillment-order write scope; write_merchant_managed_fulfillment_orders covers fulfillments of merchant-managed locations. input: {action: update_tracking|cancel, id, company?, number?, url?, notifyCustomer?}

  • inventory: Inventory changes beyond shopify_set_inventory. adjust: up to 100 relative changes {inventoryItemId or sku, locationId, delta} (inventoryAdjustQuantities), each checked against the current quantity. move: items {inventoryItemId or sku, quantity} from fromLocationId to toLocationId, taken from available stock, done as one atomic adjust (inventoryMoveQuantities cannot cross locations). move_state: move quantity between states at one location, such as available to damaged (inventoryMoveQuantities; needs referenceDocumentUri). update_item: tracked, cost, countryCodeOfOrigin, harmonizedSystemCode, provinceCodeOfOrigin, requiresShipping (inventoryItemUpdate). activate: stock an item at a location (inventoryActivate). deactivate: remove an item from a location and its stock tracking there (inventoryDeactivate; needs confirm:"deactivate"). A SKU must match exactly one inventory item or the call is refused. Reads current quantities first; dryRun shows each row's before and after. input: {action: adjust|move|move_state|update_item|activate|deactivate, changes?: [{inventoryItemId?, sku?, locationId, delta}], items?: [{inventoryItemId?, sku?, quantity}], quantityName?: available, reason?: correction|cycle_count_available|damaged|movement_created|movement_updated|movement_received|movement_canceled|other|promotion|quality_control|received|reservation_created|reservation_deleted|reservation_updated|restock|safety_stock|shrinkage, referenceDocumentUri?, fromLocationId?, toLocationId?, locationId?, fromState?: available|damaged|quality_control|reserved|safety_stock, toState?: available|damaged|quality_control|reserved|safety_stock, inventoryItemId?, sku?, tracked?, cost?, countryCodeOfOrigin?, harmonizedSystemCode?, provinceCodeOfOrigin?, requiresShipping?, available?}

  • discount: Create, activate, deactivate, delete, add codes to, or lightly update a discount, code or automatic. Percentages are FRACTIONS from 0 to 1 (0.2 is 20% off). Money is a decimal string in the shop currency. create: kind amount_off, percentage, free_shipping or bxgy, method code or automatic, all customers only; refuses a code that already exists; needs an explicit startsAt; the dry run states the exact discount in words. activate and deactivate work on code and automatic discounts. delete needs confirm:"delete". add_codes adds up to 250 codes to a code discount and refuses codes that already exist. update changes only title, startsAt, endsAt and usageLimit. Use shopify_create_discount for a quick percentage code with customer segments. input: {action: create|activate|deactivate|delete|add_codes|update, id?, kind?: amount_off|percentage|free_shipping|bxgy, method?: code|automatic, title?, code?, startsAt?, endsAt?, percentage?, amount?, appliesOnEachItem?, appliesOncePerCustomer?, usageLimit?, minimumSubtotal?, minimumQuantity?, customerEligibility?, productIds?: [...], collectionIds?: [...], combinesWith?: {productDiscounts?, orderDiscounts?, shippingDiscounts?}, maximumShippingPrice?, buyQuantity?, buyProductIds?: [...], buyCollectionIds?: [...], getQuantity?, getProductIds?: [...], getCollectionIds?: [...], getPercentage?, usesPerOrderLimit?, codes?: [...]}

  • variants: Create, update and/or delete variants of one product (productVariantsBulkCreate / BulkUpdate / BulkDelete). Updates and deletes must name variants of this product. sku, tracked, cost, weight, requiresShipping, countryCodeOfOrigin and harmonizedSystemCode set the variant's inventory item. input: {productId, create?: [{price, compareAtPrice?, sku?, barcode?, optionValues: [{optionName, name}], inventoryPolicy?: DENY|CONTINUE, taxable?, tracked?, cost?, requiresShipping?, weight?: {value, unit: GRAMS|KILOGRAMS|OUNCES|POUNDS}, countryCodeOfOrigin?, harmonizedSystemCode?}], update?: [{id, price?, compareAtPrice?, sku?, barcode?, optionValues?: [{optionName, name}], inventoryPolicy?: DENY|CONTINUE, taxable?, tracked?, cost?, requiresShipping?, weight?: {value, unit: GRAMS|KILOGRAMS|OUNCES|POUNDS}, countryCodeOfOrigin?, harmonizedSystemCode?}], delete?: [...], strategy?: DEFAULT|REMOVE_STANDALONE_VARIANT|PRESERVE_STANDALONE_VARIANT}

  • options: Create, update and/or delete product options such as Size or Color (productOptionsCreate / productOptionUpdate / productOptionsDelete). createVariants:true also creates or removes the variants an option change implies; the default leaves variants as they are. input: {productId, create?: [{name, values: [...], position?}], update?: [{id, name?, position?, addValues?: [...], renameValues?: [{id, name}], deleteValueIds?: [...]}], delete?: [...], createVariants?}

  • delete: Permanently delete one product or customer by GID (productDelete / customerDelete). This cannot be undone: archive a product (shopify_update_product status ARCHIVED) when it may come back. Shopify refuses to delete a customer who has orders. input: {id}

  • create_customer: Create a customer (customerCreate) and add any addresses (customerAddressCreate; the first becomes the default). Marketing consent is out of scope: record it only from the customer's own opt-in. dryRun:true (the default) checks for an existing customer with the same email and previews the input. input: {firstName?, lastName?, email?, phone?, note?, tags?: [...], taxExempt?, locale?, addresses?: [{firstName?, lastName?, company?, address1?, address2?, city?, provinceCode?, countryCode?, zip?, phone?}]}

  • customer_address: Create, update, delete or set the default mailing address of a customer (customerAddressCreate / Update / Delete, customerUpdateDefaultAddress). addressId must belong to the customer. input: {customerId, action: create|update|delete|set_default, addressId?, address?: {firstName?, lastName?, company?, address1?, address2?, city?, provinceCode?, countryCode?, zip?, phone?}, setAsDefault?}

  • merge_customers: Merge two customer records into one (customerMerge). This cannot be undone. dryRun:true (the default) runs Shopify's customerMergePreview, which shows the resulting customer, the fields kept and anything blocking the merge. overrideFields chooses which customer's name, email, phone or default address to keep. input: {customerOneId, customerTwoId, overrideFields?: {customerIdOfFirstNameToKeep?, customerIdOfLastNameToKeep?, customerIdOfEmailToKeep?, customerIdOfPhoneNumberToKeep?, customerIdOfDefaultAddressToKeep?, note?, tags?: [...]}}

  • create_draft_order: Create a draft order (draftOrderCreate) from variants and/or custom line items, with an optional customer, addresses, discount and shipping line. No invoice is sent. dryRun:true (the default) runs draftOrderCalculate, which returns Shopify's real totals without creating anything. input: {lineItems: [{variantId?, title?, price?, quantity, sku?, taxable?, requiresShipping?}], customerId?, email?, phone?, note?, tags?: [...], poNumber?, taxExempt?, shippingAddress?: {firstName?, lastName?, company?, address1?, address2?, city?, provinceCode?, countryCode?, zip?, phone?}, billingAddress?: {firstName?, lastName?, company?, address1?, address2?, city?, provinceCode?, countryCode?, zip?, phone?}, useCustomerDefaultAddress?, appliedDiscount?: {value, valueType: FIXED_AMOUNT|PERCENTAGE, title?, description?}, discountCodes?: [...], shippingLine?: {title, price}, currencyCode?}

  • complete_draft_order: Complete a draft order and turn it into a real order (draftOrderComplete). Inventory is reserved and the order appears in the orders list. Without paymentGatewayId Shopify marks the order as paid. input: {id, paymentGatewayId?}

  • order_status: Cancel, close, reopen or mark an order as paid (orderCancel / orderClose / orderOpen / orderMarkAsPaid). cancel cannot be undone; it refunds the original payment only with refund:true and restocks only with restock:true. notifyCustomer defaults to false. The preview checks the action is allowed. input: {id, action: cancel|close|open|mark_paid, reason?: CUSTOMER|DECLINED|FRAUD|INVENTORY|STAFF|OTHER, refund?, restock?, notifyCustomer?, staffNote?}

  • refund: Refund line items and/or shipping on an order (refundCreate). The tool asks Shopify for the suggested refund (amounts, tax and the transactions to refund against) and refunds exactly that. dryRun:true (the default) returns the suggestion. To apply, pass dryRun:false with expectedAmount equal to the suggested total from the preview; any difference stops the write. notify defaults to false. input: {orderId, lineItems?: [{lineItemId, quantity, restockType?: NO_RESTOCK|CANCEL|RETURN, locationId?}], refundShipping?, shippingAmount?, note?, notify?, expectedAmount?}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "store": "<store>",
      "operation": "<operation>"
    },
    "name": "shopify_manage"
  }
}

Input Schema

NameRequiredDescriptionDefault
inputNoThe operation's fields, as listed in the description.
storeYes
dryRunNoTrue (the default) reads the current state and returns a preview without changing anything in Shopify. Pass false, after the user authorizes this store and exact change, to apply it.
confirmNoIrreversible operations need this with dryRun:false: "delete" for delete, "merge_customers" for merge_customers, "cancel" for order_status cancel.
operationYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.2.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (destructive=true, readOnly=false), it discloses dryRun:true default, read-before-write, read-back-after-write, customer notification defaults, irreversible confirmations, scope requirements, duplicate rejection, asynchronous file processing, and duplicate webhook behavior. These details materially improve safe invocation and align with the destructive annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The structure is good: a general behavior paragraph followed by one bullet per operation, with operation fields listed inline. It is necessarily long for 21 operations, but the density is high and a few per-operation details could be trimmed; it remains readable and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's breadth, destructive nature, nested input, and lack of output schema, the description covers the important behavioral and parameter context. It explains previews, confirmation, side effects, and operation-specific constraints sufficiently for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 60% and input is a generic object, the description supplies per-operation field lists, types, enums, defaults, and constraints for all 21 operations. This is far more semantic detail than the input schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states that this tool performs guided writes for one store, selected by operation, and the operation bullets name exact resources and Shopify mutations. It also distinguishes specific siblings, such as shopify_create_discount for quick percentage codes, shopify_set_inventory for basic inventory, and shopify_update_product for archiving.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives operation-specific when-to-use and when-not-to-use rules: metafield_definition is create-only, blog is update-only, draft_order excludes create/complete, completed draft orders are refused, and several operations require confirm. It also points to alternatives for specific cases, including shopify_create_discount, shopify_set_inventory, shopify_search/shopify_get for files, and shopify_update_product for archiving.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.