New Integration: Shopify

Description

Add Shopify integration to sync e-commerce data including orders, products, customers, inventory, and store analytics into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - OAuth-based API integration
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

integrations/shopify/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Shopify Admin API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Shopify Admin API Integration

OAuth Setup

• Use OAuth 2.0 Authorization Code flow
• Register app on Shopify Partners dashboard
• API Version: 2026-01 (latest)
• Supports both REST and GraphQL Admin APIs
• Required scopes: read_orders, read_products, read_customers, read_inventory, read_analytics, read_fulfillments
• Base URL: https://{store}.myshopify.com/admin/api/2026-01/

Key Endpoints (REST)

• GET /orders.json - List orders
• GET /orders/{id}.json - Get order details
• GET /products.json - List products
• GET /products/{id}.json - Get product details
• GET /customers.json - List customers
• GET /inventory_levels.json - Inventory levels
• GET /fulfillments.json - Fulfillment status
• GET /webhooks.json - List registered webhooks

Key Endpoints (GraphQL)

• POST /graphql.json - All GraphQL queries (recommended by Shopify)
  • orders - Query orders with filtering
  • products - Query products and variants
  • customers - Query customer data
  • inventoryItems - Query inventory

Events to Track

1. Orders - New orders, fulfillments, cancellations, refunds
2. Products - Product creation, updates, inventory changes
3. Customers - New customers, profile updates, account events
4. Inventory - Stock level changes, restock events
5. Fulfillments - Shipping updates, delivery confirmations
6. Analytics - Sales trends, conversion metrics

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement Shopify OAuth 2.0 flow in account-create.ts
• Create API utilities in utils.ts for orders, products, customers, and inventory
• Implement sync logic in schedule.ts with webhook support for real-time events
• Convert e-commerce events to CORE activity format
• Add error handling and rate limiting (40 requests/min for REST, cost-based for GraphQL)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Shopify strongly recommends GraphQL over REST for new integrations
• REST rate limit: 40 requests per app per store per minute
• GraphQL uses a cost-based rate limiting system
• API is versioned (e.g., 2026-01); old versions are deprecated on a rolling basis
• Webhooks available for real-time event notifications (orders, products, customers, etc.)
• Consider using Shopify's official Node.js library: @shopify/shopify-api

Resources

• REST Admin API Reference
• GraphQL Admin API Reference
• Shopify Developer Documentation
• Shopify API Node.js Library

Labels

enhancement, integration, new-feature