# Shopify

2

min read

Sankalp

#### Shopify E-Commerce MCP Tools

##### Overview

The Shopify MCP (Model Context Protocol) tools provide comprehensive access to your e-commerce store data through Shopify's powerful GraphQL Admin API. This integration enables seamless analysis of sales performance, customer behavior, product data, and business metrics without exposing any personal identifiable information (PII).

##### Key Benefits

- **Complete Store Access**: Connect to all your Shopify store data including sales, products, customers, and orders
- **Privacy-First Design**: All tools are designed to exclude customer PII while providing valuable business insights
- **Advanced Filtering**: Leverage Shopify's sophisticated search syntax for precise data filtering
- **Real-time Insights**: Access up-to-date sales metrics, inventory levels, and customer behavior patterns
- **Scalable Analysis**: Auto-pagination handles stores of any size efficiently
- **Flexible Reporting**: Create custom analysis with powerful query combinations

#### Tool Reference

##### 1\. Get Sales Data by Query

**Purpose**: Analyze comprehensive sales performance with detailed revenue metrics and order statistics.

**What it does**: Retrieves complete sales data for orders matching your search criteria, including gross sales, discounts, order counts, and average order values. All data is automatically aggregated across currencies and time periods.

**Key Parameters**:

- `query` (required): Search query using Shopify's search syntax
- `sortKey` (optional): Sort orders by specific criteria
- `reverse` (optional): Reverse chronological order

**Sales Metrics Retrieved**:

- Gross Sales: Total revenue including discounts
- Total Discounts: Sum of all applied discounts
- Order Count: Number of matching orders
- Average Order Value: Revenue per order
- Currency Breakdown: Multi-currency sales data

**Sample Use Cases**:

- Monthly revenue analysis and growth tracking
- Campaign performance measurement by UTM parameters
- Geographic sales performance by shipping regions
- Product category revenue analysis
- Discount effectiveness evaluation

**Example Query**:

query:"created_at:>=2024-01-01 AND created_at:<=2024-01-31 AND financial_status:paid"

**Example Output**

{
"sales_data":{
"gross_sales":125450.75,
"total_discounts":12545.08,
"order_count":847,
"average_order_value":148.11,
"currency":"USD",
"date_range":"2024-01-01 to 2024-01-31"
}
}

##### 2\. Get Customers Count by Query

**Purpose**: Analyze customer segments and measure audience growth without accessing personal information.

**What it does**: Returns precise customer counts for any segment or filter criteria. Perfect for measuring marketing effectiveness, segment sizing, and customer lifecycle analysis.

**Key Parameters**:

- `query` (required): Customer search criteria using Shopify syntax

**Customer Segmentation Options**:

- Marketing consent status
- Purchase behavior and spending levels
- Geographic location
- Account creation dates
- Order frequency patterns
- Customer lifetime value ranges

**Sample Use Cases**:

- Marketing list sizing for campaigns
- Customer lifetime value segment analysis
- Geographic market size assessment
- Email marketing audience measurement
- Loyalty program eligibility counting

**Example Query**:

query:"accepts_marketing:true AND total_spent:>500 AND country:US"

**Example Output**:

{
"customer_count":2847,
"query_criteria":"accepts_marketing:true AND total_spent:>500 AND country:US",
"segment_description":"US customers who accept marketing with >$500 lifetime spend"
}

##### 3\. Get Orders Count by Query

**Purpose**: Quick order volume analysis and sales trend measurement across any time period or criteria.

**What it does**: Provides exact order counts for any filter combination, enabling rapid analysis of sales patterns, seasonal trends, and operational metrics.

**Key Parameters**:

- `query` (required): Order filtering criteria

**Order Analysis Dimensions**:

- Financial and fulfillment status
- Date ranges and seasonal patterns
- Customer segments and geography
- Product categories and campaigns
- Sales channels and marketing attribution

**Sample Use Cases**:

- Daily/weekly/monthly sales volume tracking
- Seasonal trend analysis
- Fulfillment performance monitoring
- Campaign conversion measurement
- Channel performance comparison

**Example Query**:

query:"created_at:>=2024-12-01 AND created_at:<=2024-12-31 AND fulfillment_status:fulfilled"

**Example Output**:

{
"order_count":1456,
"query_criteria":"Holiday season fulfilled orders",
"time_period":"December 2024"
}

##### 4\. List Products by Query

**Purpose**: Browse and analyze product catalog with flexible filtering for inventory and merchandising decisions.

**What it does**: Returns product listings with essential information including titles, descriptions, and global IDs. Optimized for product discovery, catalog management, and inventory analysis.

**Key Parameters**:

- `query` (required): Product search and filtering criteria
- `first` (optional): Number of products to return (max 250, default 50)

**Product Filtering Options**:

- Status and publication state
- Product type and vendor
- Inventory levels and availability
- Tags and collections
- Price ranges and discounts
- Creation and update dates

**Sample Use Cases**:

- Inventory level monitoring
- Product performance analysis preparation
- Catalog organization and management
- Seasonal product identification
- Vendor performance tracking

**Example Query**:

query:"product_type:electronics AND inventory_total:>0 AND status:active"

**Example Output**:

{
"products":[

{
"gid":"gid://shopify/Product/123456789",
"title":"Wireless Bluetooth Headphones",
"description":"Premium noise-canceling headphones...",
"product_type":"electronics"
}

],
"total_found":847,
"has_next_page":true
}

##### 5\. List Orders by Query

**Purpose**: Detailed order analysis with comprehensive filtering for sales operations and customer service.

**What it does**: Retrieves order listings with essential data including dates, values, and order IDs. Designed for sales analysis, order management, and customer service workflows.

**Key Parameters**:

- `query` (required): Order search criteria
- `first` (optional): Orders per page (max 250, default 50)
- `after` (optional): Pagination cursor for next page

**Order Data Retrieved**:

- Order GID and reference numbers
- Order creation and update dates
- Total order values and currency
- Financial and fulfillment status

**Sample Use Cases**:

- Order processing queue management
- Sales performance deep-dive analysis
- Customer service order lookup
- Fulfillment workflow optimization
- Revenue trend analysis

**Example Query**:

query:"financial_status:paid AND total_price:>100 AND shipping_address_country:CA"

##### 6\. List Customers by Query

**Purpose**: Customer segment analysis and audience insights while maintaining complete privacy protection.

**What it does**: Provides customer listings with anonymized references and global IDs. Perfect for segment analysis, marketing planning, and customer behavior studies without exposing personal information.

**Key Parameters**:

- `query` (required): Customer filtering criteria
- `first` (optional): Customers per page (max 250, default 50)
- `after` (optional): Pagination cursor
- `sortKey` (optional): Sort by various customer attributes
- `reverse` (optional): Reverse sort order

**Customer Insights Available**:

- Anonymized customer references
- Global IDs for detailed analysis
- Segmentation compatibility
- Purchase behavior patterns

**Sample Use Cases**:

- Marketing segment preparation
- Customer lifecycle analysis setup
- Audience sizing for campaigns
- Behavioral pattern identification
- Loyalty program planning

**Example Query**:

query:"orders_count:>10 AND total_spent:>1000 AND accepts_marketing:true"

##### 7\. Get All Details by GID

**Purpose**: Comprehensive object analysis using Shopify's Global ID system for deep-dive insights.

**What it does**: Retrieves complete details for any Shopify object (Product, Order, or Customer) using its Global ID. Provides maximum detail while maintaining privacy standards.

**Key Parameters**:

- `gid` (required): Global ID of the Shopify object

**Detailed Data by Object Type**:

**Products**:

- Variants, pricing, and inventory data
- SEO optimization details
- Collection associations and tags
- Media assets and descriptions
- Vendor and category information

**Orders**:

- Complete order value breakdown
- Line items and quantities
- Discount applications
- Fulfillment and shipping status
- Payment and billing information (no customer PII)

**Customers**:

- Purchase statistics and metrics
- Order count and lifetime value
- Marketing consent status
- Account creation and activity dates
- Geographic and behavioral insights (anonymized)

**Sample Use Cases**:

- Detailed product performance analysis
- Order investigation and customer service
- Customer value and behavior analysis
- Inventory and pricing optimization
- Marketing effectiveness measurement

**Example GID Formats**:

Product:"gid://shopify/Product/123456789"

Order:"gid://shopify/Order/987654321"

Customer:"gid://shopify/Customer/456789123"

#### Advanced Search Syntax

##### Query Language Fundamentals

Shopify's search syntax enables sophisticated filtering across all tools. The syntax supports terms, connectives, modifiers, and comparators for precise data retrieval.

**Basic Structure**:

field_name:value

field_name:>value(greater than)

field_name:<value(less than)

field_name:>=value(greater thanorequal)

field_name:<=value (less than or equal)

**Connectives**:

- `AND` \- Both conditions must be true
- `OR` \- Either condition must be true
- Implicit `AND` \- Space between terms assumes AND

**Modifiers**:

- `NOT` or `-` \- Exclude matching results
- `*` \- Prefix wildcard matching
- `( )` \- Group complex conditions

##### Common Search Fields by Object

**Product Queries**:

title:*wireless*

product_type:electronics

vendor:Apple

status:active

inventory_total:>0

created_at:>=2024-01-01

tag:bestseller

price:>50

**Order Queries**:

created_at:>=2024-01-01

financial_status:paid

fulfillment_status:fulfilled

total_price:>100

shipping_address_country:US

utm_source:facebook

utm_campaign:summer2024

customer_id:123456

**Customer Queries**:

customer_date:>=2024-01-01

total_spent:>500

orders_count:>5

accepts_marketing:true

country:US

state:ENABLED

email:*@gmail.com

tag:vip

##### Advanced Query Examples

**Complex Product Analysis**:

(product_type:clothing OR product_type:accessories)AND

vendor:Nike AND

inventory_total:>10AND

-tag:discontinued AND

price:>=25AND price:<=200

**Sales Performance Analysis**:

created_at:>=2024-01-01AND created_at:<=2024-12-31 AND

financial_status:paid AND

(utm_source:google OR utm_source:facebook) AND

total_price:>75 AND

shipping_address_country:US

**Customer Segmentation**:

total_spent:>1000AND

orders_count:>5AND

accepts_marketing:trueAND

customer_date:>=2023-01-01AND

country:US AND

-tag:wholesale

##### Getting Started

##### Prerequisites

- Active Shopify store with appropriate API access
- Valid Shopify access tokens with required scopes
- Understanding of your store's data structure and business needs

##### Required API Scopes

- `read_orders` \- Access to order data
- `read_products` \- Access to product information
- `read_customers` \- Access to customer data (anonymized)
- `read_analytics` \- Access to sales and performance metrics

##### Basic Workflow

1. **Discovery**: Start with count queries to understand data volumes
2. **Segmentation**: Use filtering to identify relevant data subsets
3. **Analysis**: Retrieve detailed data for specific objects using GIDs
4. **Insights**: Combine multiple tools for comprehensive business analysis
5. **Optimization**: Use findings to improve sales, marketing, and operations

##### Common Analysis Workflows

##### Sales Performance Dashboard

**Daily Revenue Tracking**:

1.Get sales data forcurrent month
2.Get order counts by week
3.Analyze top-performing product types
4.Track average order value trends

**Campaign Performance Analysis**:

1.Filter orders by UTM parameters
2.Calculate conversion rates and ROI
3.Analyze customer acquisition costs
4.Track geographic performance

##### Customer Intelligence

**Segment Analysis**:

1.Count customersinkey segments
2.Analyze purchase behavior patterns
3.Identify high-value customer characteristics
4.Track customer lifecycle progression

**Marketing Optimization**:

1.Size email marketing audiences
2.Analyze customer lifetime values
3.Identify cross-sell opportunities
4.Track retention and churn patterns

##### Inventory Management

**Product Performance**:

1.List products by performance metrics
2.Analyze inventory levels and turnover
3.Identify bestsellers and slow movers
4.Track seasonal demand patterns

**Catalog Optimization**:

1.Review product descriptions and tags
2.Analyze pricing strategies
3.Identify collection performance
4.Track vendor contributions

#### Best Practices

##### Data Retrieval Efficiency

**Query Optimization**:

- Use specific date ranges to limit data scope
- Combine filters to reduce result sets
- Leverage pagination for large datasets
- Cache frequently accessed data locally

**Performance Guidelines**:

- Start with count queries before detailed retrieval
- Use GID-based lookups for specific object analysis
- Batch related queries together
- Monitor API rate limits and quotas

### Analysis Strategy

**Structured Approach**:

- Define clear business questions before querying
- Use progressive filtering to refine results
- Validate findings with multiple data perspectives
- Document query patterns for repeatability

**Data Privacy**:

- All tools automatically exclude customer PII
- Use anonymized references for customer analysis
- Focus on aggregate patterns rather than individual behaviors
- Maintain compliance with data protection regulations

#### Advanced Features

##### Multi-Currency Support

All sales data tools automatically handle multi-currency stores, providing:

- Currency-specific breakdowns
- Converted totals in store's primary currency
- Exchange rate considerations
- Regional sales performance analysis

#### Pagination Handling

The tools automatically manage pagination across large datasets:

- Cursor-based pagination for consistent results
- Auto-continuation for complete data retrieval
- Progress tracking for long-running queries
- Optimal page size selection

#### Real-Time Data Access

Integration with Shopify's live data systems ensures:

- Up-to-date inventory levels
- Current order statuses
- Real-time customer behavior
- Immediate campaign performance tracking