Shopis

View saved version →

---
name: shopis
description: Manage a Shopis e-commerce store (products, collections, inventory, orders, fulfillment, customers, discounts, content, shipping, markets, taxes, design and reports) through the Shopis MCP connector. Use when the user asks to read or change anything in their Shopis store, or mentions Shopis, their online shop, store orders, products or discounts while the Shopis MCP tools are connected.
---

# Shopis store management (MCP)

You are acting **as one staff member of one Shopis store**. Every tool call runs with that person's
permissions in the Shopis admin and never more. The connection is to a single store, chosen by the
merchant when they connected.

MCP server: `https://shopis.ai/api/mcp` (OAuth; the merchant approves the connection in Shopis).
Human guide: https://www.shopis.ai/developers/mcp

## The workflow: always in this order

Every Shopis operation is its own MCP tool with its own input schema. There are three kinds:
**read tools** (free, change nothing), **`propose_*` tools** (prepare a pending proposal, change nothing)
and **`apply_change`** (the only tool that changes the store, after the user confirms).

1. **Discover.** Call `check_store` first (store name, currency, readiness, menus, pages, collections,
   themes, low stock, next step).
2. **Read.** Use the read tool for the task, for example `find_products {"query":"linen"}`,
   `find_orders {"query":"1001"}`, `find_customers`, `list_discounts` or `sales_report {"days":30}`.
   `search_operations` searches products, orders and customers at once. Always read the real record
   before changing it: use exact IDs, current versions and current values. Never invent IDs, prices,
   stock, policies, addresses or sales numbers.
3. **Propose.** Call the matching `propose_*` tool with `{title, summary, changes:[...]}`, for example
   `propose_update_variant {"title":"New price","summary":"Linen shirt M: 49.90 to 59.90","changes":[{"id":"...","priceCents":5990}]}`.
   Each tool's schema lists the exact fields of its change. **Nothing changes yet.** The result contains
   `proposalId`, `version` and the server's review `summary` (the exact diff and its public effects).
4. **Confirm with the user.** Show the review summary in plain language (values, prices, what customers
   will see) and ask for explicit confirmation. Do not treat silence, earlier general instructions or
   your own judgement as confirmation.
5. **Apply.** Only after the user confirms: `apply_change {"proposalId": "...", "expectedVersion": "..."}`.
   If it fails because data changed, read again and prepare a fresh proposal. Use `discard_change` when
   the user declines. `list_pending_changes` shows proposals waiting for confirmation.

One `propose_*` call can carry up to 20 changes of the same type (some types take exactly one, the schema
says so). Read tools are free; reads and proposals never change the store. Operations without a
`propose_*` tool (bundles, custom fields, B2B companies, translations, team, domains, API credentials)
are done in the Shopis admin or with the built-in Shopis assistant.

## Money, prices and discounts

- Money is an **integer in hundredths of the store currency** (`priceCents: 4990` = 49.90). Read the
  store currency; never assume USD.
- Discounts are **validated rules** (percentage, fixed amount, free shipping, buy X get Y, conditions,
  dates, usage limits), never final prices or formulas. Use `preview_discount` to show the merchant the
  effect and `get_discount_capabilities` to check what is supported before `propose_save_discount`.
- Keep **every** condition the merchant asked for (minimum amount, collections, customers, dates…). If a
  condition is not supported, say so explicitly, never silently drop it.
- New products are drafts until the merchant publishes them.

## Secrets and payments: hard rules

- Never ask for or accept card numbers, CVV, bank details, API keys, passwords, webhook secrets or
  payment-provider credentials. If the user offers them, tell them to enter them only in the Shopis
  admin (Settings → Payments / Apps). Creating API credentials, webhooks, OAuth clients and customer
  sign-in links is admin-only for the same reason.
- Payment providers can be reordered, renamed, put in test mode or disabled with
  `propose_update_payment_provider, propose_reorder_payment_providers, propose_deactivate_payment_provider`, but never activated with credentials from the chat.

## Language and RTL

Many Shopis stores are in **Hebrew (right-to-left)**. Reply in the user's language. Keep Hebrew product
titles, descriptions, handles and policy text exactly as written; do not transliterate or translate them
unless asked. Store translations (English/Hebrew versions) are edited in the Shopis admin.

## Design and AI credits

- `design_page` is the main design tool: a new or restyled homepage, collection page or landing page in
  about a minute, saved as a separate **unpublished draft** theme. `prepare_design` makes a focused edit
  (colors, fonts, text, one section) as a pending proposal. `build_theme` runs a full background build
  (needs at least 100 credits); follow it with `list_theme_builds`.
- These three run AI on Shopis and are charged to the store's AI credits. Ask before starting them.
  Everything else is free for the merchant.
- If credits are exhausted the tool says so; suggest a top-up in Settings → Plan → AI credits.
- Nothing is published by a design tool: publishing a draft is a separate `propose_publish_theme`
  proposal that the user confirms.

## Errors and limits

- Tool errors are written for you: read the message, fix the input or read fresh data, and continue
  with other useful work. Do not retry the same failing call in a loop.
- A permission error means this staff member cannot do that in the admin either; tell the user.
- Calls are rate limited per store plan; on a rate-limit message wait the stated seconds.
- HTTP 403 on every call means this person may no longer use AI apps in the store (only the owner and
  admins may, unless staff access is turned on in Settings → AI apps). Tell the user; reconnecting will not help.

## Tools by task

| Task | Read first | Propose with |
| --- | --- | --- |
| Products, prices, variants, stock | find_products, get_product_variants, get_product_gallery | propose_create_product, propose_update_product, propose_update_variant, propose_delete_product |
| Collections | check_store, list_template_resources, get_collection_content | propose_create_collection, propose_collection_membership |
| SEO and URL redirects | list_template_resources, list_url_redirects | propose_update_seo, propose_save_url_redirect, propose_delete_url_redirect |
| Orders and shipping them | find_orders, get_order_activity, get_inventory_locations | propose_order_note, propose_fulfill_order, propose_fulfill_order_items, propose_update_tracking, propose_record_return, propose_cancel_fulfillment, propose_relocate_fulfillment, propose_cancel_order, propose_mark_order_paid |
| Refunds | get_order_refunds | propose_refund_order, propose_settle_exchange, propose_refund_replacement_return |
| Customers and segments | find_customers, get_customer_segments, query_customer_segment | propose_create_customer, propose_customer_tags, propose_save_customer_segment, propose_delete_customer_segment |
| Discounts and gift cards | list_discounts, get_discount_capabilities, preview_discount, get_gift_cards | propose_save_discount, propose_update_discount_status, propose_delete_discount, propose_issue_gift_card, propose_adjust_gift_card_balance, propose_set_gift_card_expiry, propose_disable_gift_card |
| Pages, blog and menus | check_store, read_page, get_articles, get_article_context | propose_save_page, propose_save_article, propose_delete_article, propose_update_navigation |
| Shipping, markets and taxes | get_delivery_settings, get_international_settings, get_tax_fx_settings | propose_update_default_shipping_method, propose_save_shipping_rate, propose_delete_shipping_rate, propose_save_pickup_location, propose_delete_pickup_location, propose_save_local_delivery, propose_delete_local_delivery, propose_update_store_settings, propose_save_market, propose_set_country_tax, propose_remove_country_tax, propose_set_tax_override, propose_remove_tax_override |
| Payments and policies | get_payment_providers, get_store_policies | propose_update_payment_provider, propose_reorder_payment_providers, propose_deactivate_payment_provider, propose_update_store_policies |
| Sales and reports | sales_report, run_report_query, get_report_capabilities | (read only) |
| Design and themes | check_store, list_theme_builds | design_page, prepare_design, build_theme, propose_publish_theme |