Developer Handover Pack

Developer Handover Pack

Order Processing and Fulfilment

Monitors the Shopify paid-order webhook stream continuously. On receipt of each new webhook payload, it queries Linnworks via API to check live available stock for every SKU in the order. If all line items are in stock it routes the order downstream to the Label and Despatch Agent and simultaneously triggers a zone-sorted pick list in Linnworks. If any SKU is out of stock it posts a structured exception alert to Slack for the Fulfilment Manager and halts further automated processing for that order. This is the entry point of the automation and must be resilient to duplicate webhook deliveries from Shopify, which are normal behaviour under retries.

// Input
shopify.order_id          : string   // e.g. '5123456789'
shopify.line_items[]      : array
  .sku                   : string   // must match Linnworks SKU exactly
  .quantity              : integer
shopify.shipping_address : object   // full address block
shopify.total_weight_g   : integer  // used downstream for carrier selection

// Linnworks stock check (per SKU)
linnworks.available_qty  : integer  // live available stock

// Output (in-stock path)
routed_order.order_id    : string
routed_order.line_items  : array    // confirmed in-stock items with SKU + qty
routed_order.pick_list_id: string   // Linnworks pick list reference
routed_order.ship_addr   : object
routed_order.weight_g    : integer

// Output (exception path)
slack.channel            : '#fulfilment-exceptions'
slack.message            : string   // order ID + out-of-stock SKUs + quantities

Receives a stock-confirmed order record from the Order Routing Agent and orchestrates label creation, Shopify fulfilment write-back, and Xero cost posting. It sends the order weight, dimensions (if available), and destination to ShipStation, applies the pre-configured carrier selection ruleset to choose the correct service, and retrieves the label PDF and tracking number. The tracking number is written back to the Shopify order via the Fulfilment API, setting status to Fulfilled. The ShipStation shipment cost is then posted as a line item to the matching Xero sales order. This agent must complete its sequence atomically: if the Xero write fails, it should log the failure and retry rather than leave the Shopify order in an inconsistent fulfilled state.

// Input
routed_order.order_id    : string
routed_order.line_items  : array    // SKU, qty, weight per item
routed_order.ship_addr   : object   // name, address1, city, postcode, country_code
routed_order.weight_g    : integer

// ShipStation label request
shipstation.order_id     : string   // mapped from shopify.order_id
shipstation.service_code : string   // resolved via carrier selection ruleset
shipstation.carrier_code : string   // e.g. 'fedex', 'usps', 'ups'

// Output (ShipStation response)
shipstation.tracking_num : string
shipstation.label_url    : string   // PDF download URL
shipstation.shipment_cost: float    // in USD

// Output (Shopify write-back)
shopify.fulfillment.tracking_number : string
shopify.fulfillment.tracking_company: string
shopify.fulfillment.status          : 'success'

// Output (Xero posting)
xero.invoice_id          : string   // matched by order_id reference
xero.line_item.description: string  // 'Shipping: {carrier} {service}'
xero.line_item.unit_amount: float   // shipstation.shipment_cost
xero.line_item.account_code: string // pre-configured shipping expense account

Listens for the Shopify orders/fulfilled webhook event that is fired by the Label and Despatch Agent's write-back. On receipt, it identifies the tracking number, carrier name, and customer email from the Shopify fulfillment payload and fires a pre-built Klaviyo transactional event to trigger the branded tracking email. The Klaviyo event carries the tracking link, carrier display name, and an estimated delivery window calculated from the service level. This agent is the simplest of the three but is time-sensitive: the tracking email must fire within 90 seconds of the fulfilment event to meet the stated KPI.

// Input
shopify.fulfillment.order_id         : string
shopify.fulfillment.tracking_number  : string
shopify.fulfillment.tracking_company : string   // carrier display name
shopify.fulfillment.tracking_url     : string   // pre-formed carrier tracking link
shopify.order.email                  : string   // customer email address
shopify.order.shipping_address.name  : string   // customer first name for personalisation

// Klaviyo event payload (POST to Track API)
klaviyo.event              : 'Order Shipped'
klaviyo.customer_properties.$email  : string
klaviyo.properties.tracking_number  : string
klaviyo.properties.tracking_url     : string
klaviyo.properties.carrier_name     : string
klaviyo.properties.estimated_delivery_window : string  // e.g. '3-5 business days'
klaviyo.properties.order_id         : string

// Output
klaviyo.event_id           : string   // confirmation of event receipt
klaviyo.email_status       : 'queued' // Klaviyo sends asynchronously

// ============================================================
// ORDER PROCESSING AND FULFILMENT: END-TO-END DATA FLOW
// ============================================================

// TRIGGER
// Shopify fires orders/paid webhook on payment confirmation
SHOPIFY_WEBHOOK_PAYLOAD {
  order_id          : '5123456789'
  line_items[]      : [{ sku: 'SKU-001', quantity: 2 }, { sku: 'SKU-047', quantity: 1 }]
  shipping_address  : { name, address1, city, zip, country_code }
  total_weight_g    : 1850
  customer.email    : 'customer@example.com'
  financial_status  : 'paid'
}

// ---- AGENT 1: ORDER ROUTING AGENT -------------------------
// Step 1a: Dedupe check against Supabase seen_orders table
SUPABASE.seen_orders.SELECT(order_id) -> if found: HALT (duplicate)

// Step 1b: Per-SKU stock query to Linnworks Inventory API
LINNWORKS_REQUEST {
  endpoint  : GET /api/Stock/GetStockItemsFull
  params    : { SKUs: ['SKU-001', 'SKU-047'], location_id: '{warehouse_location_id}' }
}
LINNWORKS_RESPONSE {
  'SKU-001' : { available_qty: 14 }
  'SKU-047' : { available_qty: 0 }   // <- out of stock
}

// Step 1c: Decision branch
IF all line_items.available_qty >= line_items.quantity
  -> ROUTE TO: Label and Despatch Agent (routed_order object)
  -> CREATE:   Linnworks pick list (zone-sorted, pick_list_id returned)
ELSE
  -> POST TO:  Slack #fulfilment-exceptions
     slack.message : 'Exception: Order 5123456789 | Out-of-stock: SKU-047 (need 1, have 0)'
  -> WRITE TO: Supabase exceptions table
  -> HALT automated flow for this order_id

// HANDOFF: Order Routing Agent -> Label and Despatch Agent
// Field: routed_order
routed_order {
  order_id     : '5123456789'
  line_items   : [{ sku: 'SKU-001', qty: 2, weight_g: 900 }]  // only in-stock items
  ship_addr    : { name, address1, city, zip, country_code }
  total_weight_g: 1850
  pick_list_id : 'LW-PL-20240505-001'
}

// ---- AGENT 2: LABEL AND DESPATCH AGENT --------------------
// Step 2a: Carrier selection from Make data store ruleset
CARRIER_RULESET_LOOKUP(total_weight_g=1850) {
  1000 < weight <= 5000 : carrier_code='usps', service_code='usps_priority'
}
-> resolved: carrier_code='usps', service_code='usps_priority'

// Step 2b: ShipStation label creation
SHIPSTATION_REQUEST {
  endpoint     : POST /orders/createshipment
  body {
    orderId         : '5123456789'
    carrierCode     : 'usps'
    serviceCode     : 'usps_priority'
    weight          : { value: 1850, units: 'grams' }
    shipTo          : { ...ship_addr }
  }
}
SHIPSTATION_RESPONSE {
  shipmentId      : 'SS-88291'
  trackingNumber  : '9400111899223456789012'
  labelUrl        : 'https://ssapi.shipstation.com/shipments/label/SS-88291.pdf'
  shipmentCost    : 7.85   // USD
  carrierCode     : 'usps'
}

// Step 2c: Store label URL and tracking number in Supabase orders table
SUPABASE.orders.INSERT {
  order_id, tracking_number, label_url, shipment_cost, carrier_code, created_at
}

// Step 2d: Shopify fulfilment write-back
SHOPIFY_REQUEST {
  endpoint : POST /orders/5123456789/fulfillments.json
  body {
    fulfillment {
      tracking_number  : '9400111899223456789012'
      tracking_company : 'USPS'
      tracking_url     : 'https://tools.usps.com/go/TrackConfirmAction?tLabels=9400...'
      notify_customer  : false
    }
  }
}
SHOPIFY_RESPONSE {
  fulfillment.id     : 'FUL-774432'
  fulfillment.status : 'success'
}

// Step 2e: Xero shipping cost posting
XERO_REQUEST {
  endpoint : PUT /invoices/{xero_invoice_id}/lineitems
  body {
    description  : 'Shipping: USPS Priority'
    unitAmount   : 7.85
    accountCode  : '420'   // shipping expense account, confirm with Priya Nair
    quantity     : 1
  }
}
XERO_RESPONSE {
  lineItemId : 'XI-99201'
  status     : 'OK'
}

// HANDOFF: Label and Despatch Agent -> Customer Notification Agent
// Triggered by: Shopify orders/fulfilled webhook (auto-fired by Shopify on fulfillment write)
SHOPIFY_FULFILLED_WEBHOOK {
  order_id             : '5123456789'
  fulfillment_id       : 'FUL-774432'
  tracking_number      : '9400111899223456789012'
  tracking_company     : 'USPS'
  tracking_url         : 'https://tools.usps.com/go/TrackConfirmAction?tLabels=9400...'
  customer.email       : 'customer@example.com'
  shipping_address.name: 'Jane Smith'
}

// ---- AGENT 3: CUSTOMER NOTIFICATION AGENT -----------------
// Step 3a: Dedupe check against Supabase notified_fulfilments
SUPABASE.notified_fulfilments.SELECT(fulfillment_id) -> if found: HALT

// Step 3b: Estimated delivery window lookup from Make data store
DELIVERY_WINDOW_LOOKUP(service_code='usps_priority') -> '3-5 business days'

// Step 3c: Klaviyo Track API event fire
KLAVIYO_REQUEST {
  endpoint : POST https://a.klaviyo.com/api/track
  body {
    token : '{klaviyo_public_key}'
    event : 'Order Shipped'
    customer_properties {
      $email      : 'customer@example.com'
      $first_name : 'Jane'
    }
    properties {
      order_id                  : '5123456789'
      tracking_number           : '9400111899223456789012'
      tracking_url              : 'https://tools.usps.com/go/TrackConfirmAction?tLabels=9400...'
      carrier_name              : 'USPS Priority'
      estimated_delivery_window : '3-5 business days'
    }
  }
}
KLAVIYO_RESPONSE {
  status : 1   // 1 = accepted
}

// Step 3d: Write fulfillment_id to Supabase notified_fulfilments (dedupe record)
SUPABASE.notified_fulfilments.INSERT { fulfillment_id, order_id, sent_at }

// ============================================================
// FLOW COMPLETE
// Elapsed time trigger-to-notification: target < 90 seconds
// Manual steps remaining: Pick (Step 05), Pack (Step 06), Label apply + carrier handoff (Step 08)
// ============================================================