Prompts & Best Practices
Get the most out of Shopigent by using the right prompts, safety patterns, and workflows.
Key principles
1. Dry-run before write
Every curated write tool accepts dryRun: true. Preview before a live call:
Dry-run: update the price of "Approach Under Glove" to €39.99.
The preview is not executed. When the tool has a GraphQL document, the preview includes that document. A dry-run does not require approval and does not run the write. A later call without dryRun runs the write when the plan allows it. That live call pauses only if the tool's confirmation setting is on, or the action is one of the four that always pause. update_product_variant_price has confirmation off by default. bulk_update_prices has confirmation on by default.
2. Use categories explicitly
Shopigent has nine seeded merchant-tool categories (Products, Content, Metaobjects & Custom Data, Theme Pull Requests, Orders, Customers, Discounts, Fulfillments, Inventory). Mention the category for faster tool routing:
Use products tools: find all products with no description in Italian.
vs.
What products need Italian descriptions?
3. Chain operations, don't guess
Instead of asking for everything at once, chain:
1. List my products tagged "clearance".
2. For each, update the price to 40% off current.
3. Show me the total discount value.
The agent resolves each step separately. A write pauses only when that tool's confirmation setting is on, or the action is one of the four that always pause.
4. Confirmation gate pattern
Confirmation-gated writes (for example deletes, refunds, and Theme Pull Request creation) require confirmed: true. Use this pattern:
Delete product with ID gid://shopify/Product/12345.
→ Returns confirmation_pending with a token.
Confirm: yes, with the same token.
→ Executes the delete and logs it.
An agent can propose writes on its own. Destructive tools pause by default. Publishing, variant shipping weight, media upload, and theme pull request creation always pause. You can turn the gate off for every other write.
Prompts by role
Store owner
I'm going on holiday. Check my inventory: what needs reordering,
are there any stuck fulfillments, and do I have active discounts
that expire while I'm away?
List all products with 0 inventory and no reorder point set.
Developer
I need to rename "Trail Beanie" to "Trail Beanie 2.0" across all
languages. Dry-run a translation update for each language the product
has, then execute.
Read "config/settings_schema.json" from my connected theme repository and
review it for schema issues. Do not write or open a PR.
Marketing
Draft a 15% discount code for email subscribers. The code should
be single-use per customer, valid for 48 hours, and exclude sale items.
Find products with less than 2 inventory — these are running out
and need promotion before they're gone.
Tool priorities by task
| If you want to… | Use… |
|---|---|
| Discover what's in stock | list_products with inventory filters |
| Edit a product | update_product (dry-run first) |
| Check revenue | list_orders (date range filter) |
| Run a promotion | create_discount |
| Fix customer details | get_customer → update_customer |
| Manage content | create_article, update_page |
| Propose a theme repository change | github_create_theme_pr (Growth/Pro) |
| Translate the store | set_translations (Pro) |
Rate limits by plan
| Plan | Tool calls / day | Best for |
|---|---|---|
| Free | 25 | Reads, and curated write previews that are not executed. Live writes are refused. Custom tools are not included. |
| Growth | 500 | Daily operations with writes |
| Pro | No daily cap (60/min fair use) | Power use + custom tools + translations |
A dry-run counts toward the daily allowance. It does not execute the write.
Pro tips
- Name your operations — agents follow steps better when you say "Step 1… Step 2…"
- Use filters —
list_productswithquery: "status:ACTIVE"returns useful subsets - Check the audit log — every call is recorded. Review what your agent did.
- Least privilege scopes — enable only the categories your agent needs
- Trial the Pro plan — unlock non-theme resource translations and remove the daily call cap. The 60-calls-per-minute fair-use limit still applies.