DIY Developer Guide: Building Custom Integrations for Shopify

Overview

Shopify is a RESTful and GraphQL-powered eCommerce platform used by merchants globally. It provides rich APIs that allow external applications to create, read, update, and delete store data across products, orders, inventory, and more.

This guide will walk you through everything you need to build robust integrations between Shopify and external systems like ERPs (e.g., Sage Intacct), fulfillment solutions (e.g., 3PLs), CRMs, or analytics platforms.

---

Prerequisites

• Shopify Partner or Admin access (to generate API keys)
• A Shopify Store (dev or live)
• Admin API access scope (REST or GraphQL)
• App created in Shopify Admin (for authentication)
• Tools: Postman, Insomnia, or GraphQL Explorer

---

Step 1: Authentication

REST Admin API (OAuth 2.0)

1. Register your app via the Shopify Partner Dashboard.
2. Use OAuth 2.0 Authorization Code Flow to obtain an access token.
3. Token must be stored securely (encrypted at rest).

Token Header Example:

GET /admin/api/2023-10/orders.json
Host: yourstore.myshopify.com
X-Shopify-Access-Token: {access_token}

Private Apps (deprecated)

Only used for legacy stores. Avoid for long-term solutions.

---

Step 2: Discovery and Data Mapping

Common Shopify Objects:

• Product, Variant
• Order, Line Item, Fulfillment
• Customer, Address
• Inventory, Location
• Transaction, Refund
• Webhook, Metafield

Process:

1. Document external system schema.
2. Map to Shopify fields (including nested objects).
3. Pay attention to:
   • Variant IDs vs Product IDs
   • Line item structure (SKU, quantity, price, discounts)
   • Multi-location inventory fields

---

Step 3: Building the Integration Flow

Examples:

• Orders → ERP: Pull order/create event or poll /orders.json
• Inventory ← ERP: Push quantity changes to /inventory_levels/set.json
• Customer → CRM: Sync new customer records via webhooks or polling

REST Example: Fetch Orders

GET /admin/api/2023-10/orders.json?status=any&created_at_min=2024-04-01

REST Example: Update Inventory

POST /admin/api/2023-10/inventory_levels/set.json
{
  "location_id": 123456,
  "inventory_item_id": 654321,
  "available": 100
}

GraphQL Example: Create Product

mutation {
  productCreate(input: {
    title: "My Custom Product",
    variants: [{ price: "99.00", sku: "ABC-123" }]
  }) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}

---

Step 4: Webhooks for Real-Time Sync

Use Shopify Webhooks to react to changes:

• Topics: orders/create, products/update, customers/delete, etc.
• Endpoint must respond with 200 OK within 5 seconds.
• Must verify HMAC signature to confirm authenticity.

Example HMAC Verification (Node.js):

const crypto = require("crypto");
const hmac = crypto
  .createHmac("sha256", SHOPIFY_SECRET)
  .update(req.rawBody, "utf8")
  .digest("base64");

if (hmac === req.headers["x-shopify-hmac-sha256"]) {
  // Valid webhook
}

---

Step 5: Testing and Validation

• Use Shopify Admin UI or the GraphiQL Explorer to test payloads.
• Validate:
  • Field-level integrity (quantities, dates, prices)
  • Inventory sync across multiple locations
  • Timezone and currency consistency
• Use retry mechanisms and alerting on webhook delivery failures.

---

Step 6: Deployment and Scalability

• Use background job queues (e.g., SQS, Sidekiq, Celery) for async processing.
• Implement rate limiting backoff: Shopify REST API allows 2 calls/second.
• For GraphQL, monitor cost-based throttling (based on query complexity).
• Use CDN edge caching (Cloudflare, Fastly) for read-heavy APIs.

---

Step 7: Maintenance and Monitoring

• Track API deprecations: Shopify API versions expire every 12 months.
• Implement dashboarding for sync status, failed jobs, and webhook latency.
• Create rollback or replay utilities for failed jobs or incorrect updates.

---

Optional Enhancements

• Embedded App Interface (using Shopify Polaris UI + App Bridge)
• Bulk APIs for large imports (e.g., bulkOperationRunQuery)
• Integration via middleware (Zapier, n8n, Workato) for simple syncs
• Sync Metafields to handle custom ERP fields

---

Summary

Shopify offers a highly flexible, modern API stack for eCommerce integration—but it demands careful design for authentication, data mapping, throttling, and webhook reliability. Done right, a Shopify integration can act as the central nervous system of your digital commerce ecosystem.