Deep Dive - Shopify Integration with HandledScript

Shopify powers over 1.7 million businesses worldwide, making it one of the most important platforms to integrate with. In this deep dive, we'll explore how HandledScript makes Shopify integration incredibly straightforward.

Why Shopify Integration Matters

During my time at Shopify, I worked with thousands of merchants who needed to connect their stores to external systems. The most common integration patterns included:

• Order fulfillment - Sending new orders to warehouse management systems
• Inventory synchronization - Keeping product quantities up to date
• Customer data sync - Connecting to CRM and email marketing platforms
• Analytics and reporting - Sending data to business intelligence tools

Traditionally, each of these required building a custom application, managing webhooks, and handling Shopify's API complexities.

HandledScript's Shopify Integration

HandledScript provides built-in Shopify triggers and actions that handle all the complexity for you:

Available Triggers

// New order created
trigger shopify.orderCreated {
  store: "your-store.myshopify.com"
  events: ["orders/create", "orders/paid"]
}

// Product updated
trigger shopify.productUpdated {
  store: "your-store.myshopify.com" 
  events: ["products/update"]
}

// Customer registered
trigger shopify.customerCreated {
  store: "your-store.myshopify.com"
  events: ["customers/create"]
}

// Inventory level changed
trigger shopify.inventoryChanged {
  store: "your-store.myshopify.com"
  events: ["inventory_levels/update"]
}

Available Actions

// Update product inventory
action shopify.updateInventory {
  productId: input.productId,
  variantId: input.variantId,
  quantity: input.newQuantity,
  location: "primary"
}

// Create or update product
action shopify.updateProduct {
  productId: input.productId,
  data: {
    title: input.title,
    description: input.description,
    price: input.price,
    inventory_quantity: input.quantity
  }
}

// Fulfill an order
action shopify.fulfillOrder {
  orderId: input.orderId,
  trackingNumber: input.trackingNumber,
  trackingCompany: input.carrier,
  notifyCustomer: true
}

Real-World Example: Complete Order Processing

Here's a comprehensive workflow that demonstrates the power of HandledScript's Shopify integration:

workflow ComprehensiveOrderProcessor {
  // Listen for paid orders
  trigger shopify.orderCreated {
    store: "demo-store.myshopify.com"
    events: ["orders/paid"]
  }
  
  // Validate and process the order
  transform validateOrder {
    input: trigger.orderData
    output: {
      orderId: input.id,
      orderNumber: input.order_number,
      customer: {
        id: input.customer.id,
        email: input.customer.email,
        firstName: input.customer.first_name,
        lastName: input.customer.last_name
      },
      shippingAddress: {
        company: input.shipping_address.company,
        address1: input.shipping_address.address1,
        address2: input.shipping_address.address2,
        city: input.shipping_address.city,
        province: input.shipping_address.province,
        zip: input.shipping_address.zip,
        country: input.shipping_address.country_code,
        phone: input.shipping_address.phone
      },
      lineItems: input.line_items.map(item => ({
        productId: item.product_id,
        variantId: item.variant_id,
        sku: item.sku,
        title: item.title,
        quantity: item.quantity,
        price: parseFloat(item.price),
        weight: item.grams,
        requiresShipping: item.requires_shipping
      })),
      totalPrice: parseFloat(input.total_price),
      shippingCost: parseFloat(input.total_shipping_price_set.shop_money.amount),
      taxAmount: parseFloat(input.total_tax)
    }
  }
  
  // Send to warehouse management system
  action deposco.createOrder {
    input: transform.validateOrder,
    config: {
      apiKey: env.DEPOSCO_API_KEY,
      clientId: env.DEPOSCO_CLIENT_ID
    }
  }
  
  // Generate shipping label
  action easypost.createShipment {
    input: {
      toAddress: transform.validateOrder.shippingAddress,
      fromAddress: env.WAREHOUSE_ADDRESS,
      parcel: {
        weight: transform.validateOrder.lineItems.reduce((total, item) => 
          total + (item.weight * item.quantity), 0
        )
      }
    },
    config: {
      apiKey: env.EASYPOST_API_KEY
    }
  }
  
  // Update Shopify with tracking information
  action shopify.fulfillOrder {
    orderId: transform.validateOrder.orderId,
    trackingNumber: action.easypost.trackingCode,
    trackingCompany: action.easypost.carrier,
    notifyCustomer: true
  }
  
  // Send to analytics platform
  action analytics.track {
    event: "order_processed",
    userId: transform.validateOrder.customer.id,
    properties: {
      orderId: transform.validateOrder.orderId,
      orderValue: transform.validateOrder.totalPrice,
      itemCount: transform.validateOrder.lineItems.length,
      shippingCost: transform.validateOrder.shippingCost
    }
  }
}

Best Practices for Shopify Integration

1. Handle Webhook Verification

HandledScript automatically handles Shopify webhook verification, but you should still validate critical data:

transform validateShopifyData {
  input: trigger.orderData
  validate: {
    required: ["id", "email", "total_price"],
    customerId: input.customer?.id != null,
    hasLineItems: input.line_items?.length > 0
  }
}

2. Use Environment Variables

Never hardcode API keys or store URLs:

trigger shopify.orderCreated {
  store: env.SHOPIFY_STORE_URL
  apiKey: env.SHOPIFY_API_KEY
}

3. Implement Error Handling

HandledScript provides built-in retry logic, but you can customize it:

action shopify.updateInventory {
  productId: input.productId,
  quantity: input.quantity,
  retry: {
    attempts: 3,
    backoff: "exponential"
  },
  onError: "skip" // or "halt"
}

Performance Considerations

• Batch operations when possible to reduce API calls
• Use filters in triggers to process only relevant events
• Implement rate limiting awareness for high-volume stores

Next Steps

This is just the beginning of what's possible with HandledScript and Shopify. In upcoming posts, we'll cover:

• Advanced inventory synchronization patterns
• Multi-store management
• Custom app development with HandledScript
• Performance optimization techniques

---

Want to try HandledScript with your Shopify store? Check out our Getting Started guide or join our Discord community for support.