Shopify Admin API SOP#

Overview#

Shopify has two distinct APIs — know which one to use:

APIPurposeAuthStorefront API / MCP ( /api/mcp)Read product catalog, cart (read-only)None requiredAdmin API (GraphQL/REST)Write products, tags, inventory, etc.X-Shopify-Access-Token

The Storefront MCP is read-only. For any write operation, use the Admin API directly via the http tool.

---

Credentials#

Stored as skill secrets (injected at runtime):

• SHOPIFY_STORE_DOMAIN — e.g. your-store.myshopify.com
• SHOPIFY_ACCESS_TOKEN — shpat_xxx token from a Custom App with required scopes

---

How to Call the Admin API#

Use the http tool with X-Shopify-Access-Token header.

GraphQL (recommended)#

text

POST https://{SHOPIFY_STORE_DOMAIN}/admin/api/2024-01/graphql.json
Headers:
  Content-Type: application/json
  X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}

REST#

text

GET/PUT https://{SHOPIFY_STORE_DOMAIN}/admin/api/2024-01/products/{id}.json
Headers:
  X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}

---

Common Operations#

Add / update product tags (full overwrite — include all existing tags)#

graphql

mutation {
  productUpdate(input: {
    id: "gid://shopify/Product/{PRODUCT_ID}",
    tags: ["existing-tag1", "existing-tag2", "new-tag"]
  }) {
    product { id title tags }
    userErrors { field message }
  }
}

⚠️ tags is a full replacement. Always fetch current tags first, then merge.

Read product tags#

graphql

{ product(id: "gid://shopify/Product/{PRODUCT_ID}") { id title tags } }

ID formats#

• Numeric: 15501243941233
• GraphQL GID: gid://shopify/Product/15501243941233

---

Token Scopes#

For full product management, the token needs: read_products, write_products

For broader operations add: read_orders, read_inventory, write_inventory, read_themes, write_themes

---

Getting a Token (Custom App)#

1. Shopify Admin → Settings → Apps → Develop apps
2. Create or open a Custom App → Configure → Admin API scopes
3. Install the app → API credentials tab → copy the shpat_xxx token (shown once)
4. Store it via: PUT /skills/shopify-admin/secrets {"SHOPIFY_ACCESS_TOKEN": "shpat_xxx", "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"}

If you use a Dev Dashboard app (Partner App), the token is obtained via OAuth. See the OAuth Refresh SOP below.

---

OAuth Token Refresh SOP (Dev Dashboard apps)#

When a token expires (401) or needs new scopes:

Step 1 — Verify redirect URL is configured#

In shopify.app.toml:

toml

[auth]
redirect_urls = [ "https://example.com" ]

If empty, add it and run: shopify app deploy --force

Step 2 — Open the authorization URL#

text

https://{SHOPIFY_STORE_DOMAIN}/admin/oauth/authorize?client_id={CLIENT_ID}&scope={SCOPES}&redirect_uri=https://example.com&state=refresh

Step 3 — Extract the code from the redirect URL#

Browser redirects to https://example.com/?code=XXXXXX&... Extract the code value (valid for ~60 seconds).

Step 4 — Exchange code for token#

text

POST https://{SHOPIFY_STORE_DOMAIN}/admin/oauth/access_token
Body: {"client_id": "{CLIENT_ID}", "client_secret": "{CLIENT_SECRET}", "code": "{code}"}

Response contains the new access_token.

---

Gotchas#

1. shopify app dev triggers APP_UNINSTALLED webhook — avoid for production stores. Use shopify app deploy to update config only.
2. Existing token scopes don't auto-update after Dev Dashboard scope changes — must re-run OAuth.
3. Storefront MCP ( /api/mcp) is already configured in Kocoro for product search. Admin write ops bypass MCP entirely.