shopify-payments-apps — Claude skill: GraphQL for Shopify payments
Writes GraphQL queries and mutations against the Shopify Payments Apps API. Handy when you work on payment sessions, refunds or captures.
npx skills add openai/plugins --skill shopify-payments-apps -a codexWhat shopify-payments-apps does
The skill walks the agent through Payments Apps API work in a fixed order: look up the operation in the docs, write the code from what comes back, then validate it. Searches target an operation or component name rather than the whole task description, so the agent stops leaning on whatever it remembers about the schema.
Two scripts do the work. scripts/search_docs.mjs queries the documentation vector store, and scripts/validate.mjs checks the generated code. The validator takes flags for model, client and version names, plus --artifact-id and --revision. When a check fails, the agent searches for the reported error type, fixes it and validates again, up to three attempts.
Node.js is required. Both scripts report to Shopify at shopify.dev/mcp/usage: search queries, validation results, skill name, model and client identifiers. Set OPT_OUT_INSTRUMENTATION=true to turn that off — otherwise the reporting is on.
What it helps with
- write a GraphQL mutation that creates a payment session
- handle authorization, capture and settlement for a payment
- reconcile a refund or void against the original transaction
- add error handling for declined payments and network failures
- wire up 3D Secure and payment confirmation webhooks
Example prompts for the agent
- Write the paymentSessionPending mutation for the Payments Apps API and validate it
- Generate a GraphQL query for a refund on a transaction, search the docs for an example first
- Run my code through
scripts/validate.mjsand fix whatever the validation reports
How to install shopify-payments-apps
1Skills CLI (Vercel)
npx skills add openai/plugins --skill shopify-payments-apps -a codex2Manually: put the files in place
.agents/skills/shopify-payments-apps/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add openai/plugins --skill shopify-payments-apps -a claude-code2Manually: put the files in place
~/.claude/skills/shopify-payments-apps/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/shopify-payments-apps/
Manually: put the files in place
.cursor/skills/shopify-payments-apps/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install openai/plugins shopify-payments-apps2Manually: put the files in place
.github/skills/shopify-payments-apps/SKILL.mdPlatform CLI
gemini skills install https://github.com/openai/plugins --path plugins/shopify/skills/shopify-payments-appsManually: put the files in place
.devin/skills/shopify-payments-apps/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: Codex skills: how to install, where they live, how to call them
Questions about shopify-payments-apps
How do I install shopify-payments-apps in Claude?
Run npx skills add openai/plugins --skill shopify-payments-apps -a codex. The skill file then sits at .agents/skills/shopify-payments-apps/SKILL.md.
What does shopify-payments-apps do?
It helps write GraphQL operations for the Shopify Payments Apps API: it searches the developer docs for examples first, then runs the generated code through a validator.
What data does the skill send to Shopify?
Both scripts report search queries, validation results, the skill name and version, and model and client identifiers. Set OPT_OUT_INSTRUMENTATION=true to opt out.
