Shopify Debug Bundle

Overview

Collect all diagnostic information needed for Shopify support tickets: API version compatibility, access scopes, rate limit state, recent errors, and connectivity checks.

Prerequisites

Shopify access token (shpat_xxx) available
curl and jq installed
Store domain known (*.myshopify.com)

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# shopify-debug-bundle.sh
set -euo pipefail

STORE="${SHOPIFY_STORE:-your-store.myshopify.com}"
TOKEN="${SHOPIFY_ACCESS_TOKEN}"
VERSION="${SHOPIFY_API_VERSION:-2024-10}"
BUNDLE_DIR="shopify-debug-$(date +%Y%m%d-%H%M%S)"

mkdir -p "$BUNDLE_DIR"

echo "=== Shopify Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Store: $STORE" | tee -a "$BUNDLE_DIR/summary.txt"
echo "API Version: $VERSION" | tee -a "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a "$BUNDLE_DIR/summary.txt"
echo "---" | tee -a "$BUNDLE_DIR/summary.txt"

Step 2: Collect API State

# Shop info and plan
echo "--- Shop Info ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/api/$VERSION/shop.json" \
  | jq '{name: .shop.name, plan: .shop.plan_name, domain: .shop.domain, timezone: .shop.iana_timezone}' \
  >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "FAILED: shop.json" >> "$BUNDLE_DIR/summary.txt"

# Granted access scopes
echo "--- Access Scopes ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/oauth/access_scopes.json" \
  | jq '.access_scopes[].handle' \
  >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "FAILED: scopes" >> "$BUNDLE_DIR/summary.txt"

# Supported API versions
echo "--- API Versions ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/api/versions.json" \
  | jq '.supported_versions[] | {handle, display_name, latest, supported}' \
  >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "FAILED: versions" >> "$BUNDLE_DIR/summary.txt"

Step 3: Test Rate Limit State

# GraphQL rate limit check — inspects cost headers
echo "--- Rate Limit State ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ shop { name } }"}' \
  "https://$STORE/admin/api/$VERSION/graphql.json" \
  | jq '.extensions.cost' \
  >> "$BUNDLE_DIR/summary.txt" 2>&1

# REST rate limit check — inspect response headers
echo "--- REST Rate Limit Headers ---" >> "$BUNDLE_DIR/summary.txt"
curl -sI -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/api/$VERSION/shop.json" \
  | grep -iE "(x-shopify-shop-api-call-limit|retry-after|x-request-id)" \
  >> "$BUNDLE_DIR/summary.txt" 2>&1

Step 4: Collect Environment Info

echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"

# SDK version
echo "--- @shopify/shopify-api ---" >> "$BUNDLE_DIR/summary.txt"
npm list @shopify/shopify-api 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "not installed" >> "$BUNDLE_DIR/summary.txt"

# Environment variables (redacted)
echo "--- Env Vars (redacted) ---" >> "$BUNDLE_DIR/summary.txt"
echo "SHOPIFY_API_KEY: ${SHOPIFY_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "SHOPIFY_API_SECRET: ${SHOPIFY_API_SECRET:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "SHOPIFY_ACCESS_TOKEN: ${SHOPIFY_ACCESS_TOKEN:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "SHOPIFY_SCOPES: ${SHOPIFY_SCOPES:-[NOT SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "SHOPIFY_API_VERSION: ${SHOPIFY_API_VERSION:-[NOT SET]}" >> "$BUNDLE_DIR/summary.txt"

Step 5: Package and Report

# Redact any leaked tokens from the bundle
find "$BUNDLE_DIR" -type f -exec sed -i 's/shpat_[a-f0-9]\{32\}/shpat_[REDACTED]/g' {} +

tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo ""
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo "Contents:"
ls -la "$BUNDLE_DIR/"
echo ""
echo "Review before sharing — check for sensitive data!"

Output

shopify-debug-YYYYMMDD-HHMMSS.tar.gz containing:
- summary.txt — shop info, scopes, API versions, rate limits, environment
- All secrets automatically redacted

Error Handling

Diagnostic	What It Reveals	If It Fails
Shop info	Store name, plan, timezone	Token invalid or store unreachable
Access scopes	What your app can access	Token expired or revoked
API versions	Which versions the store supports	Network issue
Rate limit state	Current bucket fill level	Token or network issue
SDK version	Whether SDK needs updating	Package not installed

Examples

Sensitive Data Checklist

ALWAYS REDACT before sharing:

Access tokens (shpat_xxx)
API keys and secrets
Customer PII (emails, names, addresses)
Order details with customer data

Safe to include:

Store name and plan
API version and scopes
Error messages and X-Request-Id values
Rate limit headers
SDK/runtime versions

Quick One-Liner Health Check

curl -sf -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  "https://$SHOPIFY_STORE/admin/api/2024-10/shop.json" \
  | jq '{name: .shop.name, plan: .shop.plan_name}' \
  && echo "HEALTHY" || echo "UNHEALTHY"

Resources

Next Steps

For rate limit issues, see shopify-rate-limits.