Shopify Plugin for OpenCode

Comprehensive Shopify Admin API integration for managing your e-commerce store through OpenCode. This plugin provides tools for products, orders, customers, inventory, collections, and fulfillments.

Prerequisites

• A Shopify store (any plan)
• A custom app with Admin API access

Setup

1. Create a Custom App in Shopify

1. Go to your Shopify admin panel
2. Navigate to Settings > Apps and sales channels
3. Click Develop apps (you may need to enable custom app development first)
4. Click Create an app
5. Give your app a name (e.g., "OpenCode Integration")

2. Configure API Scopes

In your custom app settings, go to Configuration > Admin API integration and enable these scopes:

Required scopes:

• read_products, write_products - Product management
• read_orders, write_orders - Order management
• read_customers, write_customers - Customer management
• read_inventory, write_inventory - Inventory management
• read_fulfillments, write_fulfillments - Fulfillment operations
• read_locations - Location data

3. Install the App and Get Credentials

1. Click Install app to install it on your store
2. After installation, go to API credentials
3. Copy the Admin API access token (you'll only see this once!)

4. Configure Environment Variables

Create a .env file in your project:

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx
SHOPIFY_API_VERSION=2024-10  # Optional, defaults to 2024-10

Available Tools

Store Information

| Tool | Description | |------|-------------| | shopify-test-connection | Test connection and verify credentials | | shopify-get-shop-info | Get comprehensive store information | | shopify-get-analytics | Get sales and order analytics |

Products

| Tool | Description | |------|-------------| | shopify-list-products | List products with filtering and sorting | | shopify-get-product | Get product details by ID or handle | | shopify-search-products | Advanced product search | | shopify-create-product | Create a new product | | shopify-update-product | Update product details | | shopify-delete-product | Delete a product | | shopify-add-product-variant | Add variant to a product | | shopify-update-variant-price | Update variant pricing |

Orders

| Tool | Description | |------|-------------| | shopify-list-orders | List orders with filtering | | shopify-get-order | Get order details including line items | | shopify-update-order | Update order notes/tags/address | | shopify-cancel-order | Cancel an order | | shopify-create-fulfillment | Fulfill an order with tracking |

Customers

| Tool | Description | |------|-------------| | shopify-list-customers | List customers with filtering | | shopify-get-customer | Get customer details and order history | | shopify-create-customer | Create a new customer | | shopify-update-customer | Update customer information |

Collections

| Tool | Description | |------|-------------| | shopify-list-collections | List all collections | | shopify-get-collection | Get collection with products |

Inventory

| Tool | Description | |------|-------------| | shopify-list-locations | List store locations | | shopify-list-inventory-levels | Get inventory levels | | shopify-adjust-inventory | Adjust inventory quantities |

Usage Examples

List Products

List all products from my Shopify store

List products with tag "sale" sorted by price

Product Management

Create a new product called "Summer T-Shirt" with description "Comfortable cotton t-shirt"

Update product gid://shopify/Product/123 to have status ACTIVE

Order Management

Show me unfulfilled orders

Get details for order #1001

Create fulfillment for order gid://shopify/Order/123 with tracking number 1Z999AA10123456784

Customer Search

Find customers with email containing @gmail.com

List customers sorted by total spent

Inventory

Show inventory levels at all locations

Adjust inventory for item gid://shopify/InventoryItem/123, add 50 units at location gid://shopify/Location/456

Analytics

Get sales analytics for the last 30 days

Query Syntax

Product Queries

• title:shirt - Products with "shirt" in title
• vendor:Nike - Products from vendor Nike
• product_type:Apparel - Products of type Apparel
• tag:sale - Products with tag "sale"
• status:active - Active products only
• sku:ABC123 - Products with specific SKU

Order Queries

• financial_status:paid - Paid orders
• fulfillment_status:unfulfilled - Unfulfilled orders
• created_at:>2024-01-01 - Orders after date
• name:#1001 - Order by number

Customer Queries

• email:*@example.com - Customers with specific email domain
• orders_count:>5 - Customers with more than 5 orders
• total_spent:>100 - High-value customers
• state:enabled - Active customers

GraphQL IDs

Shopify uses GraphQL global IDs in the format:

• Products: gid://shopify/Product/123456
• Orders: gid://shopify/Order/123456
• Customers: gid://shopify/Customer/123456
• Variants: gid://shopify/ProductVariant/123456
• Locations: gid://shopify/Location/123456
• Inventory Items: gid://shopify/InventoryItem/123456

When listing resources, you'll receive these IDs which you can use for subsequent operations.

Error Handling

The plugin handles common errors:

• Authentication errors: Check your access token
• Rate limiting: The plugin respects Shopify's rate limits
• Not found: Resource may have been deleted
• Permission errors: Check your app's API scopes

API Version

The plugin defaults to API version 2024-10. You can change this by setting SHOPIFY_API_VERSION in your environment. Shopify releases new API versions quarterly.

Troubleshooting

"Access denied" errors

Ensure your custom app has all required scopes enabled and the app is installed on your store.

"Shop not found" errors

Double-check your SHOPIFY_STORE_DOMAIN. It should be just the domain without https:// (e.g., your-store.myshopify.com).

Rate limiting

Shopify has query cost limits. If you hit them, the plugin will return an error. Wait a moment and retry.

License

MIT