Shopify Delivery Integration & Automated Tasking

Shopify offers excellent native webhook capabilities and powerful automation tools that make delivery integration straightforward. With clean APIs, comprehensive documentation, and a robust app ecosystem, Shopify is one of the easiest platforms to connect with automated delivery services.

This guide shows you how to integrate your Shopify store with our frozen food delivery automation system.

Why Shopify Integration Excels

Shopify is built for modern e-commerce automation, making delivery integration smoother than most platforms:

Shopify’s Advantages:

• Native webhooks – Built-in, reliable, no plugins needed
• Clean JSON structure – Well-organized data format
• Shopify Flow – Visual automation builder (Shopify Plus)
• Powerful Admin API – Full read/write capabilities
• App ecosystem – Thousands of automation apps
• Excellent documentation – Clear, comprehensive guides
• Order fulfillment workflow – Designed for external services

The Shopify Difference:

✅ Webhooks are stable and reliable
✅ JSON payload is clean and logical
✅ No complex filtering needed
✅ Automatic retry on webhook failures
✅ Built for third-party fulfillment

Integration Methods: Three Approaches

Method 1: Native Shopify Webhooks (Recommended for Most)

Best for:

• Simple, reliable automation
• Quick setup without apps
• Direct webhook integration
• Businesses of any size

How it works:

1. Configure webhook in Shopify Admin
2. Shopify sends order data when event occurs
3. We receive and create delivery task
4. Email notifications keep you informed

Advantages:

• ✅ Built-in to Shopify (all plans)
• ✅ No monthly app fees
• ✅ Reliable and fast
• ✅ Easy to set up

Limitations:

• ⚠️ One-way communication (no auto order updates)
• ⚠️ Email notifications only (not in Shopify)

Method 2: Shopify Flow Automation (Shopify Plus Only)

Best for:

• Shopify Plus merchants
• Visual workflow builders
• Complex automation logic
• Multiple conditions and actions

How it works:

1. Create Flow workflow with visual builder
2. Trigger on order events
3. Add conditions (product tags, order value, etc.)
4. Action: Send webhook to us

Advantages:

• ✅ Visual, no-code interface
• ✅ Complex logic without coding
• ✅ Multiple triggers and conditions
• ✅ Easy to modify

Limitations:

• ⚠️ Requires Shopify Plus plan
• ⚠️ Still one-way communication

Method 3: Custom Shopify App (Advanced)

Best for:

• Full automation including order updates
• Custom requirements
• Two-way communication needed
• Developer resources available

How it works:

1. Build or install custom Shopify app
2. App monitors orders via Admin API
3. Sends delivery tasks to us
4. Receives status updates from us
5. Updates order status in Shopify

Advantages:

• ✅ Complete automation loop
• ✅ Order status updates in Shopify
• ✅ Custom logic and features
• ✅ Full control

Limitations:

• ⚠️ Requires development expertise
• ⚠️ Monthly app costs (if using third-party)
• ⚠️ More complex setup and maintenance

Recommendation: Start with Method 1 (Native Webhooks), upgrade to Method 2 if you have Shopify Plus, or Method 3 if you need full automation.

Shopify Webhook Structure

What Shopify Sends

Shopify webhooks deliver clean, well-structured JSON. Unlike some platforms, Shopify’s payload is logical and doesn’t need extensive filtering.

Example Shopify Order Webhook Payload:

{
  "id": 820982911946154508,
  "email": "customer@example.com",
  "created_at": "2024-10-15T14:25:00-04:00",
  "updated_at": "2024-10-15T14:25:00-04:00",
  "number": 1234,
  "note": "Customer delivery instructions here",
  "token": "abc123",
  "financial_status": "paid",
  "fulfillment_status": null,
  "customer": {
    "id": 115310627314723954,
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+27821234567"
  },
  "billing_address": {
    "first_name": "John",
    "last_name": "Smith",
    "address1": "123 Main Street",
    "address2": "Apartment 4B",
    "city": "Johannesburg",
    "province": "Gauteng",
    "country": "South Africa",
    "zip": "2000",
    "phone": "+27821234567"
  },
  "shipping_address": {
    "first_name": "John",
    "last_name": "Smith",
    "address1": "123 Main Street",
    "address2": "Apartment 4B",
    "city": "Johannesburg",
    "province": "Gauteng",
    "country": "South Africa",
    "zip": "2000",
    "phone": "+27821234567"
  },
  "line_items": [
    {
      "id": 466157049,
      "title": "Frozen Meal Pack",
      "quantity": 2,
      "sku": "FROZEN-001"
    }
  ]
}

What’s great about Shopify’s structure:

• ✅ Clearly labeled fields
• ✅ Consistent naming conventions
• ✅ Separate billing and shipping addresses
• ✅ Customer object with all contact info
• ✅ Order notes included
• ✅ No unnecessary nested complexity

Our Required JSON Schema for Shopify

Here’s the exact format we need from your Shopify store:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TheFrozenFoodCourierShopifyReceiver",
  "description": "The Frozen Food Courier Shopify Webhook Schema",
  "type": "object",
  "properties": {
    "senderID": {
      "description": "Your Merchant Code",
      "type": "string",
      "$comment": "Get this from thefrozenfoodcourier.co.za/register"
    },
    "orderNumber": {
      "description": "Shopify Order Number",
      "type": "string",
      "$comment": "From order.number or order.name"
    },
    "orderID": {
      "description": "Shopify Order ID",
      "type": "integer",
      "$comment": "From order.id (optional but helpful)"
    },
    "customerEmail": {
      "description": "Customer Email",
      "type": "string",
      "$comment": "From order.email or order.customer.email"
    },
    "customerNote": {
      "description": "Order Notes",
      "type": "string",
      "$comment": "From order.note (optional - delivery instructions)"
    },
    "shipping": {
      "type": "object",
      "properties": {
        "firstName": {"type": "string"},
        "lastName": {"type": "string"},
        "phone": {"type": "string", "$comment": "Mobile for SMS/WhatsApp"},
        "email": {"type": "string"},
        "address1": {"type": "string"},
        "address2": {"type": "string"},
        "city": {"type": "string"},
        "province": {"type": "string"},
        "country": {"type": "string"},
        "zip": {"type": "string", "$comment": "Postal code"}
      },
      "required": ["firstName", "lastName", "phone", "address1", "city", "province", "zip"]
    },
    "dispatchReadyDate": {
      "description": "Dispatch Ready Date",
      "type": "string",
      "$comment": "Optional - from order metafield"
    },
    "taskAction": {
      "description": "Action to perform",
      "type": "string",
      "$comment": "UPDATE or CANCELLED"
    }
  },
  "required": ["senderID", "orderNumber", "customerEmail", "shipping", "taskAction"]
}

Mapping Shopify Fields to Our Schema

Direct mapping from Shopify webhook:

Our Field	Shopify Source	Example
senderID	Your merchant code	“TFFC-MERCHANT-001”
orderNumber	order.number or order.name	“1234” or “#1234”
orderID	order.id	820982911946154508
customerEmail	order.email	“customer@example.com”
customerNote	order.note	“Gate code: 1234”
shipping.firstName	order.shipping_address.first_name	“John”
shipping.lastName	order.shipping_address.last_name	“Smith”
shipping.phone	order.shipping_address.phone	“+27821234567”
shipping.email	order.email	“customer@example.com”
shipping.address1	order.shipping_address.address1	“123 Main Street”
shipping.address2	order.shipping_address.address2	“Apt 4B”
shipping.city	order.shipping_address.city	“Johannesburg”
shipping.province	order.shipping_address.province	“Gauteng”
shipping.country	order.shipping_address.country	“South Africa”
shipping.zip	order.shipping_address.zip	“2000”
taskAction	Always	“UPDATE”

Note: Shopify’s clean structure makes mapping straightforward!

Step-by-Step Setup Guide

Method 1: Native Shopify Webhooks (Detailed Setup)

Step 1: Register as Merchant

1. Visit thefrozenfoodcourier.co.za/register
2. Complete registration
3. Save your merchant code
4. Note the webhook URL provided

Step 2: Access Shopify Webhooks

1. Log into Shopify Admin
2. Go to Settings (bottom left)
3. Click Notifications
4. Scroll down to Webhooks section
5. Click Create webhook

Step 3: Configure Webhook

Event: Choose the trigger event

• Recommended: Order payment (fires when order is paid)
• Alternative: Order creation (fires when order created)
• Alternative: Order fulfillment (fires when marked fulfilled)

Format: JSON

URL: Enter the webhook URL from your registration

Webhook API version: Use latest (currently 2024-10)

Step 4: Create Transformation Template

Shopify allows you to transform the webhook payload before sending. Click “Use transformation” and enter:

{
  "senderID": "YOUR_MERCHANT_CODE_HERE",
  "orderNumber": "{{ order.order_number }}",
  "orderID": {{ order.id }},
  "customerEmail": "{{ order.email }}",
  "customerNote": "{{ order.note }}",
  "shipping": {
    "firstName": "{{ order.shipping_address.first_name }}",
    "lastName": "{{ order.shipping_address.last_name }}",
    "phone": "{{ order.shipping_address.phone }}",
    "email": "{{ order.email }}",
    "address1": "{{ order.shipping_address.address1 }}",
    "address2": "{{ order.shipping_address.address2 }}",
    "city": "{{ order.shipping_address.city }}",
    "province": "{{ order.shipping_address.province }}",
    "country": "{{ order.shipping_address.country }}",
    "zip": "{{ order.shipping_address.zip }}"
  },
  "taskAction": "UPDATE"
}

Replace YOUR_MERCHANT_CODE_HERE with your actual merchant code.

Step 5: Test the Webhook

1. Click Send test notification
2. Shopify sends a test payload to us
3. Check your email for our confirmation
4. Verify test order appears in your merchant dashboard

Step 6: Save and Activate

1. Click Save webhook
2. Webhook is now active
3. New orders will automatically trigger delivery tasks

Step 7: Monitor First Orders

1. Place a real test order
2. Verify webhook fires (check Shopify webhook logs)
3. Confirm you receive our email notification
4. Check customer receives pre-delivery notification

Method 2: Shopify Flow (Shopify Plus)

Step 1: Access Shopify Flow

1. Shopify Admin → Apps
2. Click Shopify Flow (pre-installed on Plus)
3. Click Create workflow

Step 2: Set Up Trigger

1. Click Select a trigger
2. Choose Order paid or Order created
3. Click Add trigger

Step 3: Add Conditions (Optional)

To filter only frozen food orders:

1. Click + to add condition
2. Select Order tag
3. Condition: contains “Frozen”
4. Or use Product type if categorized

Step 4: Add Webhook Action

1. Click + to add action
2. Select Send HTTP request
3. Configure:
   • Method: POST
   • URL: Your webhook URL
   • Headers:
     • Key: Content-Type
     • Value: application/json
   • Body: Use JSON with Liquid variables

{
  "senderID": "YOUR_MERCHANT_CODE",
  "orderNumber": "{{ order.orderNumber }}",
  "orderID": {{ order.id }},
  "customerEmail": "{{ order.email }}",
  "customerNote": "{{ order.note }}",
  "shipping": {
    "firstName": "{{ order.shippingAddress.firstName }}",
    "lastName": "{{ order.shippingAddress.lastName }}",
    "phone": "{{ order.shippingAddress.phone }}",
    "email": "{{ order.email }}",
    "address1": "{{ order.shippingAddress.address1 }}",
    "address2": "{{ order.shippingAddress.address2 }}",
    "city": "{{ order.shippingAddress.city }}",
    "province": "{{ order.shippingAddress.province }}",
    "country": "{{ order.shippingAddress.country }}",
    "zip": "{{ order.shippingAddress.zip }}"
  },
  "taskAction": "UPDATE"
}

Step 5: Test and Turn On

1. Click Test workflow (uses sample data)
2. Verify webhook received
3. Click Turn on workflow
4. Monitor first real orders

Method 3: Custom Shopify App (Advanced)

For Developers or Using Third-Party App:

Option A: Build Custom App

1. Create Private App:
   • Shopify Admin → Apps → App and sales channel settings
   • Develop apps → Create an app
   • Configure Admin API scopes: read_orders, write_orders
2. Set Up Webhooks via API:

// Create webhook programmatically
const webhook = {
  topic: "orders/paid",
  address: "https://your-webhook-url.com",
  format: "json"
};

// Using Shopify API
fetch('/admin/api/2024-10/webhooks.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Shopify-Access-Token': 'YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({ webhook })
});

3. Receive Status Updates:

// Endpoint to receive our updates
app.post('/delivery-status', (req, res) => {
  const { senderID, orderNumber, deliveryStatus } = req.body;
  
  // Verify it's from us
  if (senderID !== "THEFROZENFOODCOURIER") {
    return res.status(403).json({ error: "Unauthorized" });
  }
  
  // Update order in Shopify
  updateShopifyOrder(orderNumber, deliveryStatus);
  
  res.status(200).json({ success: true });
});

async function updateShopifyOrder(orderNumber, status) {
  // Add note to order or update custom field
  const note = `Delivery Status: ${status}`;
  
  // Use Shopify Admin API to update
  // Implementation depends on your setup
}

Option B: Use Third-Party App

Popular Shopify apps that can help:

• Mechanic – Powerful automation platform
• Order Automator – Webhook and automation tool
• Zapier – Connect Shopify to webhooks

Note: We’re not affiliated with these apps – evaluate based on your needs

Advanced Features

Scheduled Deliveries with Metafields

If customers choose delivery dates:

Step 1: Create Order Metafield

1. Settings → Custom data → Orders
2. Add definition: “Delivery Date”
3. Namespace: custom
4. Key: delivery_date
5. Type: Date

Step 2: Include in Webhook

In transformation template:

{
  ...
  "dispatchReadyDate": "{{ order.metafields.custom.delivery_date }}",
  "dispatchReadyDateMask": "YYYY-MM-DD",
  ...
}

Filtering by Product Tags

To only send frozen orders:

Tag your frozen products: frozen-food

In Shopify Flow:

• Condition: If order contains product with tag frozen-food
• Then: Send webhook

In webhook transformation:

{% if order.tags contains 'frozen' %}
  {
    /* Your webhook payload */
  }
{% endif %}

Multiple Warehouse Locations

If using Shopify locations:

Include location in payload:

{
  ...
  "collectionLocation": "{{ order.location.name }}",
  "collectionAddress": "{{ order.location.address1 }}, {{ order.location.city }}"
}

Receiving Delivery Status Updates

Method 1: Email Notifications (All Plans)

Setup: Configure during merchant registration

What you receive:

• Task accepted confirmation
• Address validation status
• Planned/scheduled notifications
• Dispatched alerts
• En route updates
• Completed/failed confirmations

How to use:

• Monitor delivery progress via email
• Forward updates to customers if desired
• Manually update Shopify order notes/tags

Method 2: Order Notes via API (Custom App)

If you build a custom app:

What we can do:

1. Receive status updates from us
2. Add timeline events to Shopify order
3. Update order tags (e.g., delivery-in-progress)
4. Send custom email to customer

Example Order Timeline Event:

// Add note to order
const note = {
  note: `Delivery Status: ${deliveryStatus} at ${timestamp}`,
  order_id: orderId
};

shopify.order.addNote(note);

Method 3: Customer Notifications

Built-in option: Use our tracking link in Shopify order confirmation:

1. Shopify Admin → Settings → Notifications
2. Edit “Order confirmation” template
3. Add our tracking link variable (we provide this)
4. Customer clicks to see live tracking

Troubleshooting

Problem: Webhook Not Firing

Check:

• ✓ Webhook is saved and active
• ✓ Event type matches order workflow (paid vs created)
• ✓ Order actually triggered the event
• ✓ Check Shopify webhook logs (Settings → Notifications → Webhooks → View details)

Solution:

• Review webhook delivery attempts in Shopify
• Check error messages
• Verify webhook URL is correct

Problem: Webhook Fails Validation

Check webhook delivery logs for:

• Missing merchant code (senderID)
• Missing required fields (email, phone, address)
• Invalid JSON format
• Wrong data types

Solution:

• Verify transformation template syntax
• Test with actual order data
• Check all Liquid variables are correct

Problem: Wrong Address Sent

Common issues:

• Billing address sent instead of shipping
• Incomplete shipping address
• Customer didn’t provide all details

Solution:

• Ensure using order.shipping_address.* fields
• Require complete shipping address at checkout
• Use address validation app on Shopify

Problem: Phone Number Format

Issue: Phone numbers may include country code or not

Solution:

• Use order.shipping_address.phone (includes format as entered)
• Consider phone validation app
• We handle various formats, but mobile preferred

Best Practices

1. Test Thoroughly Before Going Live

Testing checklist:

• ✓ Place test order with real address
• ✓ Verify webhook fires
• ✓ Check we receive correct data
• ✓ Confirm customer gets pre-delivery email
• ✓ Monitor first 5-10 real orders closely

2. Handle Edge Cases

Consider:

• Orders with no shipping address (digital + physical?)
• International orders (if you ship outside SA)
• Partial fulfillments
• Order cancellations
• Gift orders (different recipient)

3. Tag Your Frozen Products

Create consistent tagging:

• Tag: frozen-food or requires-frozen-delivery
• Use in Flow conditions or filters
• Makes automation more reliable

4. Communicate with Customers

In product descriptions:

• “Delivered via specialized frozen food courier”
• “You’ll receive delivery tracking”
• “Professional temperature-controlled delivery”

In order confirmation:

• “Your frozen items will be delivered by The Frozen Food Courier”
• Include expected delivery timeframe
• Link to what3words guide for precise delivery

5. Monitor Webhook Health

Weekly checks:

• Review failed webhook attempts (if any)
• Check delivery success rate
• Monitor customer feedback
• Review automation logs

Shopify Plans and Features

Available on All Shopify Plans

✅ Native webhooks
✅ Webhook transformations
✅ Basic automation
✅ Order notes
✅ Customer notifications

Shopify Plus Additional Features

✅ Shopify Flow (visual automation)
✅ Advanced API access
✅ Custom fulfillment services
✅ Wholesale channel

You don’t need Shopify Plus for delivery automation – native webhooks work perfectly on all plans!

Related Resources

Integration Guides:

• Delivery Automation Overview
• Work Order Processing
• Real-Time Tracking
• WooCommerce Integration
• Wix Integration

Shopify Documentation:

• Shopify Webhooks
• Webhook Transformations
• Shopify Flow (Plus only)
• Admin API

Get Help

Technical Support: 📧 hello@thefrozenfoodcourier.co.za

We can help with:

• Webhook URL and merchant code
• Transformation template assistance
• Payload requirements
• Shopify Flow configuration
• Testing and troubleshooting
• Custom integration consultation

Have a Shopify developer or agency? We’re happy to work directly with them to ensure perfect integration!

The Frozen Food Courier – Seamless Shopify integration for frozen food delivery