Shopify Integration

Connect your Shopify store to sync orders automatically to the Fulfillment module.

Overview

The Shopify integration enables:

• Automatic order import from Shopify
• Real-time webhook sync for new orders
• Fulfillment status updates back to Shopify
• Product data synchronization
• Inventory level sync (optional)

Prerequisites

• Shopify store with admin access
• PROIGN tenant with Fulfillment module enabled
• Admin or owner role in PROIGN

Setup Steps

1. Create Custom App in Shopify

1. Go to Shopify Admin → Settings → Apps and sales channels → Develop apps
2. Click "Create an app" and name it "PROIGN Integration"
3. Under "Configuration", click "Configure Admin API scopes" and select the required scopes below
4. Click "Install app" and confirm
5. Copy the Admin API access token (shown only once — store it securely)

Required API Scopes

2. Connect in PROIGN

1. Go to Fulfillment → Settings → Integrations
2. Click "Connect Shopify"
3. Enter your Shopify store URL (e.g., your-store.myshopify.com)
4. Paste the Admin API access token
5. Click "Test Connection" to verify
6. Click "Save" to complete setup

3. Configure Webhook (Automatic)

PROIGN automatically registers webhooks when you connect. The following events are subscribed:

• orders/create - New order placed
• orders/updated - Order modified
• orders/cancelled - Order cancelled
• products/update - Product changed

Sync Configuration

Configure how orders are synced:

Order Flow

1. Order Created - Customer places order on Shopify
2. Webhook Received - PROIGN receives order data
3. Order Imported - Appears in Fulfillment queue
4. Pick & Pack - Warehouse processes order
5. Ship - Label created, tracking added
6. Sync Back - Shopify order marked fulfilled with tracking

Webhook Security

Every inbound Shopify webhook is verified using HMAC-SHA256 before processing. The gateway validates the X-Shopify-Hmac-Sha256 header against the request body:

// Webhook verification flow
const hmac = request.headers.get("X-Shopify-Hmac-Sha256");
const body = await request.text();

// Compute expected HMAC using shared secret
const key = await crypto.subtle.importKey(
  "raw",
  encoder.encode(SHOPIFY_WEBHOOK_SECRET),
  { name: "HMAC", hash: "SHA-256" },
  false,
  ["sign"]
);
const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
const expected = btoa(String.fromCharCode(...new Uint8Array(signature)));

// Reject if HMAC doesn't match
if (hmac !== expected) {
  return new Response("Unauthorized", { status: 401 });
}

Webhooks that fail HMAC validation are rejected immediately and logged for security monitoring. The webhook secret is stored as an encrypted Cloudflare Worker secret.

Webhook Payload

When a new order is created in Shopify, the webhook delivers a payload that PROIGN maps to its internal order format:

// Shopify orders/create webhook (simplified)
{
  "id": 5678901234,
  "order_number": 1042,
  "financial_status": "paid",
  "fulfillment_status": null,
  "line_items": [
    {
      "id": 12345,
      "title": "Product Name",
      "sku": "SKU-001",
      "quantity": 2,
      "price": "29.99"
    }
  ],
  "shipping_address": {
    "name": "John Smith",
    "address1": "123 Main St",
    "city": "Austin",
    "province": "TX",
    "zip": "78701",
    "country": "US"
  }
}

// Mapped to PROIGN fulfillment order
{
  "shopify_order_id": 5678901234,
  "shopify_order_number": "#1042",
  "status": "pending",
  "items": [...],
  "shipping_address": {...}
}

Manual Sync

Trigger a manual sync for historical orders:

POST /api/[tenant]/sync/shopify

{
  "from_date": "2026-01-01",
  "to_date": "2026-01-31",
  "status": "unfulfilled"
}

Troubleshooting

Orders Not Syncing

• Verify API token has correct scopes
• Check webhook is registered in Shopify
• Review order status filter settings
• Check PROIGN sync logs for errors

Fulfillment Not Updating in Shopify

• Verify write_orders scope is granted
• Check fulfillment location is correctly configured
• Review API rate limits

Duplicate Orders

• PROIGN uses Shopify order ID for deduplication
• If duplicates appear, check for multiple webhook registrations

API Reference

# Test connection
POST /api/[tenant]/integrations/shopify/test

# Get sync status
GET /api/[tenant]/sync/status

# Trigger manual sync
POST /api/[tenant]/sync/shopify

# Disconnect Shopify
DELETE /api/[tenant]/integrations/shopify

Related