
Shopify Payments Apps
Build or extend Shopify Payments Apps against current Admin/API versions using Shopify.dev doc search instead of stale copy-paste.
Overview
Shopify Payments Apps is an agent skill for the Build phase that searches versioned Shopify.dev documentation to implement Payments Apps integrations correctly.
Install
npx skills add https://github.com/shopify/shopify-ai-toolkit --skill shopify-payments-appsWhat is this skill?
- Doc search against shopify.dev with multiple pinned API version targets
- Supports unstable and dated API version constants for forward-compatible lookups
- Staging host and Minerva token flow for shopify-dev staging servers
- CLI-oriented search script suitable for agent-driven documentation retrieval
- Focused on Shopify Payments Apps domain rather than generic theme editing
- Multiple supported API version labels including unstable and dated releases
Adoption & trust: 4.7k installs on skills.sh; 373 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are building a Shopify Payments App but official API and payments docs span versions and staging environments you cannot keep in chat context.
Who is it for?
Solo builders or tiny teams shipping Shopify Payments Apps who need version-accurate doc lookup while coding integrations.
Skip if: Non-Shopify storefronts, theme-only tweaks, or merchants who only need Shopify Payments toggle settings in admin.
When should I use this skill?
You are implementing or debugging a Shopify Payments App and need authoritative, version-specific Shopify.dev references.
What do I get? / Deliverables
Your agent pulls current Shopify.dev guidance for payments apps against the API versions you target, reducing wrong endpoints before you wire checkout flows.
- Doc search results mapped to payments app tasks
- Version-aligned API reference snippets
- Staging configuration notes when using dev servers
Recommended Skills
Journey fit
Payments app work is integration-heavy backend surface area, so the Build integrations shelf is the primary placement. Payments apps connect your service to Shopify’s commerce graph, which is classic third-party integration work.
How it compares
Integration skill with live doc search, not a hosted MCP replacement for your payments processor’s own API.
Common Questions / FAQ
Who is shopify-payments-apps for?
Developers building Shopify Payments Apps or payment-related extensions who use AI agents during integration and compliance research.
When should I use shopify-payments-apps?
While building checkout or payments integrations, validating API version support, or debugging staging against Shopify dev/staging hosts.
Is shopify-payments-apps safe to install?
Check this page’s Security Audits panel; staging doc search may require Minerva tokens and outbound network access you should scope narrowly.
SKILL.md
READMESKILL.md - Shopify Payments Apps
#!/usr/bin/env node // <define:__SUPPORTED_VERSIONS__> var define_SUPPORTED_VERSIONS_default = ["unstable", "2026-07", "2026-04", "2026-01", "2025-10", "2025-07"]; // src/agent-skills/scripts/search_docs.ts import { parseArgs } from "util"; // src/http/index.ts var PROD_BASE_URL = "https://shopify.dev/"; var SHOP_DEV_BASE_URL = "https://shopify-dev.shop.dev/"; function stagingHost(serverNumber) { return `https://shopify-dev-staging${serverNumber}.shopifycloud.com/`; } function resolveShopifyDevBaseUrl(options) { const env = options?.env ?? process.env; const stagingRaw = env.SHOPIFY_DEV_STAGING_SERVER_NUMBER?.trim(); if (stagingRaw) { if (!/^\d+$/.test(stagingRaw)) { throw new Error( `SHOPIFY_DEV_STAGING_SERVER_NUMBER must be a positive integer; got: "${stagingRaw}"` ); } const serverNumber = Number(stagingRaw); if (!Number.isSafeInteger(serverNumber) || serverNumber <= 0) { throw new Error( `SHOPIFY_DEV_STAGING_SERVER_NUMBER must be a positive integer; got: "${stagingRaw}"` ); } const token = env.MINERVA_TOKEN; if (!token) { const audience = stagingHost(serverNumber).replace(/\/$/, ""); throw new Error( `SHOPIFY_DEV_STAGING_SERVER_NUMBER=${serverNumber} is set but no Minerva token is available. Staging servers are behind Minerva. Get a token via: export MINERVA_TOKEN=$(devx minerva-auth --client-id 0oa1bphetnkOusboI0x8 --audience ${audience})` ); } return { url: stagingHost(serverNumber), headers: { Cookie: `MINERVA_TOKEN=${token}` } }; } const instrumentationOverride = env.SHOPIFY_DEV_INSTRUMENTATION_URL?.trim(); if (instrumentationOverride && options?.uri?.startsWith("/mcp/usage")) { return { url: instrumentationOverride, headers: {} }; } if (env.DEV && env.DEV !== "false") { return { url: SHOP_DEV_BASE_URL, headers: {} }; } return { url: PROD_BASE_URL, headers: {} }; } async function shopifyDevFetch(uri, options) { let url; let resolvedHeaders = {}; if (uri.startsWith("http://") || uri.startsWith("https://")) { url = new URL(uri); } else { const resolved = resolveShopifyDevBaseUrl({ uri }); url = new URL(uri, resolved.url); resolvedHeaders = resolved.headers; } if (options?.parameters) { Object.entries(options.parameters).forEach(([key, value]) => { url.searchParams.append(key, value); }); } const response = await fetch(url.toString(), { method: options?.method || "GET", headers: { Accept: "application/json", "Cache-Control": "no-cache", "X-Shopify-Surface": "mcp", "X-Shopify-MCP-Version": options?.instrumentation?.packageVersion || "", "X-Shopify-Timestamp": options?.instrumentation?.timestamp || "", ...resolvedHeaders, ...options?.headers }, ...options?.body && { body: options.body } }); if (!response.ok) { let errorBody; try { errorBody = await response.text(); } catch { } throw new Error( errorBody ? `HTTP ${response.status}: ${errorBody}` : `HTTP error! status: ${response.status}` ); } return await response.text(); } // src/data/supported-versions-schema.json var supported_versions_schema_default = { admin: [ { name: "unstable" }, { name: "2026-07", releaseCandidate: true }, { name: "2026-04", latestVersion: true }, { name: "2026-01" }, { name: "2025-10" }, { name: "2025-07" } ], "storefront-graphql": [ { name: "unstable" }, { name: "2026-07", releaseCandidate: true }, { name: "2026-04", latestVersion: true }, { name: "2026-01" }, { name: "2025-10" }, { name: "2025-07" } ], partner: [ { name: "unstable" }, { name: "2026-07", releaseCandidate: true }, { name: "2026-04", lates