Seller Runtime Toolkit

Use this skill when you need direct, scriptable access to one Shopify store from OpenClaw.

This skill complements seller-api-workflow. Keep the existing workflow skill for higher-level business asks. Use this skill when the task is explicitly about Shopify setup status, documentation search, script execution, or troubleshooting those surfaces.

This skill is self-contained. You can copy the entire shopify-runtime/ folder into an OpenClaw workspace/skills/ directory and run it there without the seller-assistant plugin repository beside it.

Quick Start

• Configure the skill in OpenClaw instead of maintaining per-store profiles.
• Set this skill's apiKey in OpenClaw. Because the skill declares primaryEnv: "SHOPIFY_CLIENT_SECRET", OpenClaw injects that value into SHOPIFY_CLIENT_SECRET for each agent run.
• Set skills.entries."shopify-runtime".env.SHOPIFY_STORE_DOMAIN to your *.myshopify.com domain.
• Set skills.entries."shopify-runtime".env.SHOPIFY_CLIENT_ID to your Shopify app client id.
• Optionally set skills.entries."shopify-runtime".env.SHOPIFY_API_VERSION to override the default API version.
• Run the bundled script with node.
• Read references/shopify-provider.md when the request touches auth, scopes, orders, or write access.
• Read references/runtime-contract.md when you need the output shape or command examples.

Example OpenClaw config:

{
  skills: {
    entries: {
      "shopify-runtime": {
        apiKey: { source: "env", provider: "default", id: "SHOPIFY_CLIENT_SECRET" },
        env: {
          SHOPIFY_STORE_DOMAIN: "your-store.myshopify.com",
          SHOPIFY_CLIENT_ID: "your_shopify_client_id",
          SHOPIFY_API_VERSION: "2026-01",
        },
      },
    },
  },
}

Auth And Scope Notes

• This skill currently authenticates with Shopify by exchanging SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET for an Admin API access token. It does not use a pre-issued SHOPIFY_ACCESS_TOKEN.
• This flow is intended for a Shopify app owned by the same organization as the target store and installed on that same store.
• Read operations usually need matching Shopify Admin API scopes such as read_products, read_inventory, read_orders, or read_customers.
• Write operations usually need the matching write scopes such as write_products, write_inventory, or write_orders.
• Order access can still fail even with basic scopes. Older orders may require read_all_orders, and protected customer data access may still be required.

Capability Boundaries

• Prefer Admin GraphQL for normal reads and writes. Use REST only when GraphQL is not the best fit.
• --mode read blocks local REST writes and GraphQL mutations before the request is sent.
• --mode write only removes the local read-only guard. Shopify still enforces the app's granted scopes.
• status confirms local skill readiness, not that Shopify token exchange will succeed.

Commands

Inspect current setup

Use this when the user asks whether the skill is ready, which store it is pointed at, or which API version it will use.

node skills/shopify-runtime/scripts/seller-runtime.mjs status

Search provider and official docs

Use this before writing an API script from memory. Prefer provider notes and the narrowest matching official documentation entry.

node skills/shopify-runtime/scripts/seller-runtime.mjs search --query "orders graphql pagination"

Add --limit or --refresh when needed.

Execute JavaScript

Use this after you know the request shape. Default to --mode read. Only use --mode write when the user clearly asked for a write operation and the Shopify token should allow it.

cat <<'EOF' | node skills/shopify-runtime/scripts/seller-runtime.mjs execute --mode read
return await provider.graphql(`
  query {
    shop {
      name
    }
  }
`)
EOF

The script body should use provider.graphql(...) or provider.request(...). In this runtime, provider.graphql(...) returns the validated GraphQL data object directly. Prefer piping the script on stdin so you do not need temporary files. --script-file is still supported when a real file is more convenient.

Working Rules

• This skill targets one configured Shopify store per agent run.
• Search docs before inventing request shapes or filters from memory.
• Keep execution scripts narrow and return concise structured objects instead of raw payloads when possible.
• Treat requestSummary, rawResponses, and logs as execution evidence when you explain the outcome.
• Read mode blocks REST write methods and GraphQL mutations locally. Write mode still depends on the Shopify token having matching Admin API access.
• The runtime reads SHOPIFY_STORE_DOMAIN, SHOPIFY_CLIENT_ID, SHOPIFY_CLIENT_SECRET, and optional SHOPIFY_API_VERSION from the environment that OpenClaw injects for the skill run.