@shopify/dsh-shopify

🧠 Agent usage conventions (the "skills")

These conventions are injected into the agent's system prompt when the plugin mounts; they are also the ground rules for anyone prompting the agent with Shopify:

• IDs: REST tools take numeric resource IDs (e.g. product_id: '8313381814466'); GraphQL tools take GIDs (gid://shopify/Product/123). Convert with GraphQL's legacyResourceId when crossing.
• Pagination: REST list tools return next_page_info — loop with page_info until it is null; never silently truncate. GraphQL lists: request pageInfo { hasNextPage endCursor } and paginate with after.
• Rate limits: REST bucket ~40 GET / ~20 write calls per minute; GraphQL ~1000 cost points/min (~50/s refill). On 429 / THROTTLED / a full X-Shopify-Shop-Api-Call-Limit bucket, back off (1s, 2s, 4s) and reduce concurrency. Prefer limit: 50–100 over huge pages.
• userErrors: mutations return validation failures in the payload's userErrors array with HTTP 200 — always inspect them. Top-level GraphQL errors are also validation, not transport, failures.
• Deprecated REST endpoints: the REST Admin API is legacy; prefer shopify_graphql_* tools for new product-model work (options, media, publishing) and anything REST does not expose.
• Refunds: always call shopify_calculate_refund first, then change transaction kind from 'suggested_refund' to 'refund' before shopify_create_refund.
• Money: amounts are decimal strings ('19.99'); always pass the shop currency (from shopify_get_shop_details / shopify_query_shop) and never assume USD.
• Timezones: Shopify stores timestamps in UTC, but date filters evaluate in the shop's local timezone (iana_timezone from shopify_get_shop_details) — adjust boundary-day queries.
• Destructive actions (shopify_delete_*, shopify_disable_gift_card) are irreversible: confirm with the user before executing.

---